Revision/Update Information: May, 2001
Permission to reproduce this document is hereby granted, provided that all such reproductions include all of this document (including this copyright notice), and are not distributed for profit or resale.
Contents |
This section contains 6 chapters which describe the OECN Menu Processor for the system manager. It includes a complete description of the theory and implementation of the menu processor on a VAX/VMS system. The 6 chapters are:
Introduction
Theory
Implementation
Invoking the Menu Processor
Modifying and Creating Menu Systems
Customizing Menus from the Distribution
The OECN Menu processor provides a flexible user menu interface to
State Software programs. It also can be used to create menus for DCL
commands, and other layered products. Menu definitions will be provided
for all state software programs. Individual A-sites will be able to add
customized menus to the default menu system provided.
1.1 Features
The Menu processor provides the following features:
Features for the system manager:
The basic theory behind the Menu processor is fairly simple. The menu
definitions are stored in an RMS indexed file. The menu definitions are
flexible enough to allow creation of menus containing any combination
of DCL commands, programs and information.
2.1 Definition of Terms
First, it will be helpful to define some terms that will be used throughout the rest of this document.
Term | Meaning |
---|---|
Menu Processor | The program that the user runs to enter a menu system. |
menu | A menu consists of the menu heading and the menu items on that menu. |
menu name | The name of the menu as defined in the MENUEDT program. |
menu item | An item on a menu. An item belongs to a specific menu and must have a label that is unique throughout the menu system. |
label | A label is the unique name for an item. It is defined in the MENUEDT program and is the label the user will see on the actual menu. |
menu file | A file created by MENUEDT that contains the menu definitions for one for more menus. |
menu system | A menu system is a collection of menus that the user has access to. This is the logical menu system as viewed by a specific user. A system may consist of one or more physical menu files. |
menu specification | A menu specification is the format for specifying a menu. The specification may contain a file and/or a menu name. |
alias | For each item in the menu system an alias is created. It has the same name as the item's label. The alias is global to the entire menu system, i.e., it crosses all menu file boundaries. The alias must be unique within each menu system. |
Figure 2-1 displays a graphical representation of a possible menu system.
Figure 2-1 Conceptual View of a Menu system
+-----------------------Menu-System-------------------+ | +Menu-File+ | | | | +-Alias-File-+| | | +Menu+ | | || | | | | | | || | | +----+ | | || | +----+----+ | || | +-------+------------+ +------------+| | +---Menu+File--+ +Menu+File-+ +-Secur-File-+| | | +Menu+ | | | | || | | | | | | +Menu+ | | || | | +-+--+ | | | | | | || | | +------+ | | +----+ | | || | | +Menu+ +Menu+| +----+-----+ +------------+| | | | | | || +----+------+ | | | +----+ +-+--+| | | | | | +------+ | +Menu+File+ +Menu+File+ | | | +Menu+ +Menu+| | +Menu+ | | +Menu+ | | | | | | | || | | | | | | | | | | | +----+ +----+| | +----+ | | +----+ | | | +--------------+ +---------+ +---------+ | +-----------------------------------------------------+ |
You can see from Figure 2-1 that a menu system as seen by the user may consist of multiple menu files, and a menu file may contain multiple menus. This provides considerable flexibility for designing and modifying a menu system.
The menu system that is included with the distribution will have a separate menu file for each OECN state software package. Additionally, each major package will have a local menu. This local menu will be in a separate menu file and left blank. You will be able to customize this local menu without disturbing the other menus.
A more detailed description of how to modify and create menus will follow later in this document. The method used to customize local menus will be discussed.
Each menu system has one alias file. This file is used to find an item's location if the user enters an alias.
Also, the menu system may have one local security file. This file is
optional and created by the OSA utility. See the OECN Software Security
for VAX/VMS System Manager manual for more information about security
and the OSA utility.
2.3 Menu Specifications
Throughout this document there are references to menu specifications. Wherever a menu specification is required the following syntax is allowed:
@menu_file\menu_name |
Parameter | Meaning |
---|---|
@menu_file | Name of a menu file that contains menu_name. If not specified then menu_name is assumed to exist in the current menu file. |
menu_name | A menu within either the specified menu file or the current menu file. |
A valid menu specification contains one or both of these components.
If a menu name is specified without a menu file then the menu is assumed to exist in the current menu file. If there is no current menu file then OECN$MENU is used.
If a menu file is specified without a menu name then the default menu of the menu file's header record is used.
If both the menu file and menu name are specified they must be separated by a backslash (\).
Examples:
Specification | Result |
---|---|
@BUD_MENU\USAS_PRC | Goes to the USAS_PRC menu of the BUD_MENU file. |
@MAIN_MENU | Goes to the default menu of the MAIN_MENU file. |
LOCAL | Goes to the LOCAL menu of the current file. |
Each menu system may have exactly one alias file. An alias file contains a record for each menu item in the menu system. This alias record contains a pointer to the proper menu file that contains the item.
When the user enters a label name that is not on the current menu, the alias file is checked for the label. If found then the item is located in the appropriate menu file, and, assuming the user has access to the item, it is executed. This allows the user to get to any item or menu in the menu system without navigating through the intervening menus.
The alias file is built automatically by the MENUUTL program. See
Section 5.2.1, Building the Alias File for more information about creating the alias file.
2.5 Option execution
By default, the menu processor does not spawn subprocesses to
execute user options. All commands are executed in the user's current
process. This implies that menu processor image must exit and restart
(activate) after each option has completed. This is called
"terminate and execute" mode. This mode may provided
optimal response time for smaller VAX processors, particularly machines
with small memory configurations.
2.5.1 Spawning Options
Another mode that may be chosen by the system manager is "spawn and execute". In this mode, most commands are executed in a subprocess. The menu processor remains running in the main process and does not terminate. Spawning options may reduce response time for larger VAX machines with excess physical memory.
No firm guidelines can be provided to suggest which mode will provide optimal response time and resource utilization for a given system. Response time in both modes is determined by machine size, available memory, tuning, typical load on the system, etc. Trial and error under a typical work load is the only way to determine the best mode. If the time required to spawn a process is less than the time required to activate the menu image, then spawning is preferable.
To implement menu option spawning the system manager must be aware of the following:
Prior to implementing spawning you must carefully consider whether any custom menu files contain any options that fall under #4 above. The subprocess that is created by the menu processor is temporary (i.e., the subprocess logs out as soon as the option has completed). This means that any commands performed in the subprocess will not be permanent. If you have options that change user logicals, create processes, etc. or anything that must affect both the main process and the subprocess, you must modify your custom menu files.
The MENUEDT program will allow you to define an item type "DP" (DCL
command in Parent). These types of items will always be executed in the
main process using "terminate and execute". These means that any
commands executed in this way will affect both the main process and
subprocess. These types of items should be used sparingly and will
seldom be necessary. The only item in the menu files distributed by
SSDT that need the "DP" item type was the DETPRT option of the LOCAL
menu. All other SSDT menu items may be executed in a subprocess.
2.5.2 Selecting Execution Mode
To select either "terminate and execute" or "spawn and execute" mode, the system manager needs only define a single logical. The logical name is OECN$MENU_BEHAVIOR and may be defined in the SYSTARTUP procedure. The valid values are: TERMINATE or SPAWN. For example, if you want to use "spawn and execute", add the following line the SYSTARTUP procedure:
$ DEFINE/SYSTEM OECN$MENU_BEHAVIOR "SPAWN" |
This logical also can be defined at the group or process level. If the
logical is not defined, the default is "TERMINATE".
2.6 Inactivity Timeout
The menu processor has an optional feature that will cause it to automatically exit if the user does not enter a command after a specified period of time. This might be a useful security feature for user users who remain idle in the menu for long periods of time or forget to logout.
The system manager may add a command to the OECN$MENU_BEHAVIOR logical that will enable the timeout feature. The following syntax may be used:
$ DEFINE/SYSTEM OECN$MENU_BEHAVIOR "TIMEOUT=n" |
Where n is the number minutes to wait with no activity. After the timeout period expires without any options being entered, the menu processor will exit automatically.
The menu processor simply exits the menu and returns to DCL it does not log the user off the system. It is up to the local captive login procedure or other mechanism to log the user off. |
Several steps are required in order to implement the Menu Processor on your system. The steps are briefly outlined below, detailed explanations follow:
The Menu Processor uses files from the OECN, MENU and HELP packages.
Install these packages as usual using OECN_INSTALL. For further
information about OECN_INSTALL see OECN_INSTALL.DOC in the VAX manager
documentation directory.
3.2 Establish OECN Logicals
Several logicals are used by the Menu Processor to locate the menu files and VMS Help libraries.
Logical | Purpose |
---|---|
OECN$MENU$FILES 1 | Device and directory where the menu files are located. |
OECN$MENU 2 | Default menu file if none is specified by the user when the Menu Processor is invoked. |
OECN$ALIAS 2 | Default alias file that is used if none is specified when the Menu Processor is invoked. |
OECN$SECUR | Local security file. Optional. Created by OSA utility to define local security. |
OECN$HELP 1 | Device and directory where the VMS Help libraries are located. |
OECN$MENU_HELP 2 | Default menu help library. Used when the user presses [PF2] or ?. |
OECN_MENU_PROMPT | Default prompt to be used in the Menu Processor. Optional. May be overridden by the user with a SET PROMPT command. |
OECN_MENU_MODE | Default mode. Optional. May contain the "MENU" or "COMMAND". May be overridden by the user with a SET MODE command. |
OECN$MENU_BEHAVIOR | Optional logical that may contain commands to control how the menu processor behaves at run-time. This logical is defined by the system manager. See 3.2.1. |
OECN$MENU$FILES and OECN$HELP must be defined in either the SYSTARTUP
or individual LOGIN.COM files. These logicals may be defined at the
system, group or process level. For example, the OECN$MENU logical may
be defined for each user to provide a different default menu.
3.2.1 Specifying options with OECN$MENU_BEHAVIOR logical
This section describes the commands that may be placed in the OECN$BEHAVIOR logical. The syntax for the logical definition is:
$ DEFINE/SYSTEM OECN$MENU_BEHAVIOR "command[,command]..." |
Where [command] is one of the commands in the following table. The command(s) must be enclosed in quotes and be in uppercase. When multiple commands are specified they must be separated by commas (,). This logical can be defined at the system, group, job or process level.
Command | Description |
---|---|
TERMINATE | Causes the processor to use the " terminate and execute " method for executing options. This is the default behavior. |
SPAWN | Causes the processor to spawn all DCL and Program type action items in a subprocess. |
TIMEOUT=n | Sets the inactivity timeout interval to n minutes. |
NOTIMEOUT | Disables inactivity timeout. This is the default behavior. |
For example, to specify the spawn option and a timeout of 30 minutes use the following command:
$ DEFINE/SYSTEM OECN$MENU_BEHAVIOR "SPAWN,TIMEOUT=30" |
Move the menu files (OECN$ROOT:[MENU.DIST]*.DAT) to the directory referenced by OECN$MENU$FILES.
Move the VMS Help libraries from the HELP package distribution directory to the directory referenced by OECN$HELP.
The users of the Menu Processor must have read access to the above files.
Also move the following files to the OECN$ directory:
OECN$ROOT:[OECN.V1P0.DIST]MENU.EXE
OECN$ROOT:[OECN.V1P0.DIST]OECN_MENU.COM
The users must have execute access to these files.
3.4 Add Global Symbol
Add the following symbol to either your SYLOGIN.COM or each user's LOGIN.COM who will be using the system:
$ OECN_MENU :== $OECN$:MENU |
This creates a foreign command that the OECN_MENU.COM procedure uses to
invoke the Menu Processor. Other symbols may be necessary to make it
easier for your users to invoke a menu. These symbols will be discussed
in the Chapter 4, Invoking the Menu Processor. The OECN_MENU symbol is the only required symbol.
3.5 Install the Menu Processor
Although it is not necessary for proper execution of the Menu Processor, it is strongly recommended that you install the Menu Processor as a known image.
Because the Menu Processor does not spawn a subprocess it must be reactivated after each time the user selects a menu item. If the image is not installed, image activation will cause a noticeable delay in the Menu Processor.
The recommended method of installing the image is to add the following commands to your SYSTARTUP.COM:
$ INSTALL :== $INSTALL/COMMAND_MODE $ INSTALL ADD OECN$:MENU.EXE/OPEN/SHARED/HEADER |
The Menu Processor must be invoked via a command procedure that is provided as part of the OECN package. The Menu Processor depends on this command procedure to perform several vital functions and to actually execute any items selected by the user. Absolutely nothing useful will happen if the Menu Processor is invoked directly.
Additionally, the Menu Processor is invoked by the command procedure with a foreign command. Therefore the following symbol definition is required. See Section 3.4, Add Global Symbol.
$ OECN_MENU == "$OECN:MENU" |
To invoke the menu processor the following command must be used:
$ @OECN$:OECN_MENU [menu spec] [alias file] [menu_option] |
The OECN_MENU.COM command procedure is provided with the distribution and must be used to invoke the menu processor.
The first parameter is an optional menu specification that specifies the default menu file and menu to be used. If the menu specification is not supplied then OECN$MENU is used by default. See Section 2.3, Menu Specifications for more information about menu specifications.
The second optional parameter is the alias file for the menu system being invoked. If not specified then OECN$ALIAS is used by default.
The third optional parameter is a menu command, option or alias to be executed. If this parameter is specified then the menu processor will execute the option and return to DCL, the user will not be left in the menus after the option has finished executing. This could be used as a replacement for the DCL RUN command, particularly for batch procedures. This would insure that batch procedures do the same security checking as interactive processes.
The menu processor will operate properly in batch only if the third parameter is supplied. If the parameter is not specified the menu processor will not function in batch. |
This command may be defined in a global symbol, invoked from a captive
login procedure or from inside another procedure. No restrictions are
placed on the method of invoking the Menu Processor.
4.1 Examples
For most users the following symbol definition is sufficient:
$ MENU == "@OECN$:OECN_MENU" |
This will invoke the Menu Processor with the default menu and alias file. This will normally, unless changed by you, be the MAIN_MENU file, which contains menu items for all state software packages.
If users will be using the third parameter (or it will be used from batch) then the following symbol might be used:
$ MENU == "OECN$:OECN_MENU """" """" " |
This will leave the first two parameters as null (accepting the default menu and alias files) and allow the third parameter to be specified after the MENU symbol.
As another possibility, suppose that you have a payroll user that would rather be started out in the USPS menu. In this case put this symbol in that user's LOGIN procedure:
$ MENU == "@OECN$:OECN_MENU @PAY_MENU" |
This will put the user in the PAY_MENU directly. Note that this does not restrict the user to the PAY_MENU, it just starts them out in that menu.
The MENUEDT program is a fully functional maintenance program for modifying and creating menu files. Another program, MENUUTL, provides several necessary and useful utilities when manipulating the files, such as building the alias file and reporting functions.
Record Type | Function |
---|---|
File Header Record | Contains information about the entire menu file. There is only one file header record per file. |
Menu Header Record | Contains information specific to one menu. There is no structural or logical limit to the number of menus that may exist in a menu file. |
Item Record | Contains the actual item that appears on a menu. Each item record belongs to one and only one menu. The number of items is limited by the Menu Processor to 50 items (about 4 screens). |
The menu files and records form a loose hierarchy. That is,
the hierarchy is created by the person developing the menu system. The
hierarchy is not enforced by the MENUEDT program or even the Menu
Processor. The menus can be connected in an almost limitless number of
combinations. It is impossible for the MENUEDT program to know exactly
what the runtime environment will be for the menu file. Thus, very
little error checking is performed or even attempted. This means that
menus that you modify or create should be tested thoroughly before
being made available to your users.
5.1 Using MENUEDT
When you first run the MENUEDT program it will prompt you for the name of the menu file to modify. If the file does not exist it will be created.
Option | Function |
---|---|
Add | Adds new records of any type. |
Change | Enters change mode for the current record. |
Delete | Deletes the current record. |
Top | Goes to top of file (File header record). |
Find | Finds a record by menu or item name. |
Next | Goes to the next record. |
Simulate | Simulates how the menu will look to the user. The simulation is approximate since the MENUEDT upper window is smaller than in the Menu Processor. |
Open | Closes the current menu file and prompts for a new menu file to open. |
Exit | Exits MENUEDT. |
This section and the following sections show sample screens that are
used by MENUEDT to modify the various record types. After each screen
is a detailed explanation of each field and its purpose.
5.1.2 File Header Record
The first record in each menu file must be a File Header record and each file must contain exactly one Header record.
Menu File Header Record: 1. Desc: 2. Default menu: 3. Modify default security identifiers |
Field | Description |
---|---|
Desc | This description is used in the heading for all menus in this file. |
Default Menu | Is the default menu for this file if the user does not specify a menu when the file is invoked. This menu will normally be the top-level menu for this file. |
Modify default security identifiers | Enters the Security Id Maintenance screen to allow default security identifiers to be placed on the menu file. See Section 5.1.5 for more information about security identifiers. |
The Menu Header record contains information about each menu in the file. There must be exactly one Header record for each menu contained in the file.
Menu header record: 1. Menu Name : 2. Description : 3. Heading Type: 4. Help file : 5. Help topic : 6. Parent Menu : 7. Modify Security Identifiers |
field | Description | ||||
---|---|---|---|---|---|
Menu Name | Name of the menu. This is the name that will be displayed in the menu heading. | ||||
Description | This description is used in the heading for this menu. | ||||
Heading Type |
Indicates what type of menu heading to use for this menu.
|
||||
Help File | The VMS Help file that will be used if the user enters HELP at this menu. | ||||
Help topic | The initial topic string used when the user enters HELP. | ||||
Parent Menu | Must contain the parent menu specification for this menu. This is the menu that the user will return to when they enter /EXIT or ^. If this field is blank then the menu is assumed to be the top level menu of the menu system. | ||||
Modify security identifiers | Enters the Security Id Maintenance screen to allow security identifiers to be placed on the menu. See Section 5.1.5 more information about security identifiers. |
One menu item record must be specified for each desired item on a menu. A menu can contain a maximum of 50 item records. If there are less than 8 items then the menu will be double spaced, otherwise the menu will be single spaced. If there are more items than will fit on one screen then the menu will be divided into multiple screens.
An item may be of one of four types, the value and meaning of the Action field is determined by the Item Type field. The four possible types and the meaning of the Action field are defined in Table 5-5.
Item Type | Interpretation of Action Field |
---|---|
D | DCL command to execute |
DP | DCL command to execute in Parent process |
P | Program filespec to execute |
M | Menu specification |
T | Ignored |
Menu Item record: 1. Menu Name: 2. Label : 3. Desc : 4. Item Type: 5. Action : 6. Item order#: 7. Modify Security Identifiers |
Field | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Menu Name 1 | Name of the menu that this item belongs to. | ||||||||||
Label 1 | Label of this item that the user will use to reference this item. | ||||||||||
Desc | Description displayed for this item. | ||||||||||
Item Type |
Indicates what type of item this is:
|
||||||||||
Action | Contains the action to be performed when this item is selected. See Section 5.1.4.1 for more information. | ||||||||||
Item order # | This field is used to order the items on the menu. By default the items are in alphabetical order by Item Label. If you want to change the order of the items then you may put a number in the Item Order# field. This number does not affect the number that the user will use to invoke the item, it only affects the physical order of the items on the menu. | ||||||||||
Modify security identifiers | Enters the Security Id Maintenance screen to allow security identifiers to be placed on the item. See section Section 5.1.5 for more information about security identifiers. |
Much of the Menu Processor's flexibility is provided by the values that may be placed in the Action field. The Action field and the Item Type field together determine what will happen when the user chooses an item from a menu.
Item Type D (DCL)
If Type = "D" then Action must contain a valid DCL command. Any DCL command may be specified, including command procedures. These commands may be executed in subprocess depending on the setting of OECN$MENU_BEHAVIOR (See Section 2.5). For example, the following are valid for Action:
@PURGE_TEXT_FILES
Write sys$output "Hello there."
If the DCL command requires or allows parameters to be specified you may place a tilde (~) at the location where the parameters should be placed.
As a simple example, assume that you have a print procedure that allows the filename and the number of copies as parameters. Item Label is PRINT and the name of the command procedure is OECN$UTL:PRINT.COM. On the PRINT item record you would put the following in the Action field:
@OECN$UTL:PRINT ~ ~ |
When the user enters the PRINT item from the Menu Processor they may specify the parameters on one line. For example, the user could enter:
Menu> PRINT MYFILE.TXT 10 |
The DCL command that would be executed by the Menu Processor would be:
$ @OECN$UTL:PRINT MYFILE.TXT 10 |
Up to 8 parameters may be specified. Parameters containing spaces must be enclosed in quotes. (Parameters may not contain quotes.) Lowercase characters are preserved inside of quotes. Parameters are replaced from left to right. No other parsing of the parameters is done. Parameters are always considered to be optional, if the user does not specify a parameter then the tilde (~) will be replaced by a space.
Item Type DP (DCL in Parent)
Type "DP" is identical to type "D" except that the Action line is always executed in the parent process. This only has an effect if the menu processor is in "spawn and execute" mode (See Section 2.5).
This item type should be used sparingly and only when the command must be executed in the parent process. This is only necessary when the commands being executed must affect both the parent and subprocess. Examples of such commands are:
Item Type P (Program)
If Type = "P" then the Action field contains the full VMS file specification for an executable image to be executed by the DCL RUN command. The distinction between programs and DCL commands is made primarily for compatibility with the HP version of the Menu Processor. However, future VAX releases may take advantage of this distinction.
Item Type M (Menu)
If Type = "M" then the Action field must contain a valid menu specification. This type of item allows the user to move from one menu to another at a lower level. The menu specified may be in the current menu file or may specify a completely different menu file. See Section 2.3 for more information about menu specifications.
Item Type T (Text)
If Type = "T" then the action line is ignored. Text items are used to
put information or subheadings on a menu. For text items, the
Description field is simply displayed on the menu without a label or an
option number.
5.1.5 Menu Security Screen
The Modify Security Identifier screen allows you to require that the user has specific VMS identifiers before they are allowed access to certain menu elements.
Security may be placed on any level: File, Menu or Item. If the user does not have access to a menu item, it will not appear on the menu.
Three levels of access can be specified for each identifier that appears on the Security Identifier screen: Read-only, Standard or Group Manager. See Section 5.1.5.1 for more information about how these identifiers are derived.
The following screen shows an example of a menu element that requires the user to have read-only access to the OECN_PPS identifier or standard access to the OECN_SALSIM identifier. Note that the user must only have one of the selected identifiers. Of course, users with OECN_SYSMAN access have access to all menu elements regardless of these identifiers.
1) OECN_EDCIMS 9) OECN_SYSMAN 2) OECN_EIS 10) OECN_USAS 3) OECN_OECN 11) OECN_USPS R 4) OECN_PPS 12) OECN_VIS 5) OECN_PVS 13) OECN_USER1 S 6) OECN_SALSIM 14) OECN_USER2 7) OECN_SECIMS 15) OECN_USER3 8) OECN_SECIMS_GRPMAN 16) OECN_USER4 (R = Read-Only, S = Standard, G = Group Manager) |
Security will be propagated through the menu structure. If security is not specified for a menu element, then security will be inherited from the level above it. The following list details the rules that are used to determine how security is inherited.
The identifiers OECN_USER1 through OECN_USER4 are for use locally at the A-sites. You may assign these identifiers in any manner you wish. For example, you may want to allow specific users to access VMS Mail. You could use OECN_USER1 to restrict a MAIL menu item to those users. These identifiers will not be used by SSDT in any State Software programs.
If four identifiers are not enough for your site, you may add new ones.
Up to 16 identifier positions have been reserved for use at the A-site
level. See OECN_IDS.LIB in OECN$LIB: for instructions.
5.1.5.1 Security Identifiers
The security identifiers that appear on the Security Identifier screen are the "standard" identifiers. Three possible identifiers exist for each standard identifier, which are used to specify three levels of access. These alternate identifiers are derived by adding a suffix to the standard identifier.
The following table lists the three access levels, in order of lowest level access to the highest.
Access Level | Suffix | Description |
---|---|---|
Read-Only | _RO | If a user holds the identifier then read-only access is granted. This user may execute read-only programs or have access to read-only functions within programs. |
Standard | none | If a user holds this identifier then the user is granted "standard" access to the identifier. This user is assumed to be a standard read-write user of the corresponding package. |
Group Manager | _GM | Users that hold this identifier are granted access to "group manager" functions. This user is assumed to hold special privileges within the corresponding package. |
For example, for the OECN_USPS identifier there are really three identifiers that may be granted to a user. These identifiers are:
OECN_USPS_RO
OECN_USPS
OECN_USPS_GM
All these access levels, and therefore all the identifiers, exist for all packages, even if the package itself does not implement the identifiers. In other words, the Menu Processor will test for all the identifiers, even if the individual package does not.
It also should be noted that the access levels will be applied to the
A-site specific identifiers. That is, there will also be OECN_USER1_RO
and OECN_USER1_GM identifiers available for use at the A-site level.
5.2 Using MENUUTL
The MENUUTL program provides some necessary functions for building, maintaining and documenting a menu system. The options provided are:
The first and the most important option of MENUUTL is the alias file build option. The alias file contains a pointer for each menu item in the system. Therefore, whenever you add or remove menu items from a menu file you must rebuild the alias file.
MENUUTL makes this process rather simple. All you have to do is run MENUUTL and choose option 1. MENUUTL will ask the following questions:
Physical name of top level menu file:___________ |
Enter the physical filespec of the top-level menu file. This is the current physical location of the top-level menu file.
Logical name of top level menu file:_____________ |
Enter the logical filespec of the top level menu file. This should be the logical name of the file that will be used when the user accesses the menu system.
The physical and logical name should normally be the same. |
Enter new alias filename: ___________________ |
Enter the name of the new alias file to be built. The alias file is always rebuilt from scratch and a new version is created.
After prompting for these values, MENUUTL will begin reading through the specified menu file and add an alias for each item found. It will also search for references to other menu files. If such references are found, MENUUTL will search those files for menu items and add aliases for each one.
MENUUTL uses the OECN$MENU$FILES logical to search for the menu files in the same manner as will be used by the Menu Processor. Therefore, the runtime environment for MENUUTL must be the same as when the Menu Processor will be invoked. |
As stated earlier, all aliases must be unique across the entire menu system. If MENUUTL finds a duplicate alias name, an error message will displayed and the duplicate will not be added. Processing will continue and the alias file will be usable, but the alias for the duplicate item will not exist.
You may also use the OECN$:BUILD_ALIAS.COM command procedure to build the alias file. This procedure will automatically build a new alias file using the current values of OECN$MENU$FILES, OECN$MENU and OECN$ALIAS. You can run this procedure after installing a new distribution or customizing menu files. If you frequently modify menu files, you could even run the procedure periodically in batch to ensure that the alias file is always up-to-date. |
This option will read through the specified menu file and create a
simulated menu listing. The listing will display the menu in as close
an approximation as possible on a hardcopy printer. The option will
only report on one menu file at a time and will be sorted in
alphabetical order by menu name.
5.2.3 Detailed Menu Listing
The detailed menu report lists all available information about the
specified menu file. This report is particularly useful for double
checking the action fields and security.
5.2.4 Hierarchical Listing
This report will display the structure of the menu system. The menus
are listed in the proper order as they appear on the menu. This option
will prompt for the top level menu file and menu where the listing is
to start. You need not necessarily start at the top of the entire menu
system.
5.3 OSA
The OSA, OECN Security Authorization, Utility may be used in conjunction with the OECN Menu Processor to fine tune security access. OSA can be used to enable user's access to individual programs to be granted or denied. This local security is defined by each A-site and is maintained separately from the menu system included on the OECN distribution. (See also VMS Manager's Guide)
This chapter describes the recommended procedure for customizing the menu files from the distribution. Following this procedure will ensure that you can install future releases with minimum effort and maintain a consistent user interface across the state.
Each major package has its own menu file. The file name for the primary menu file ends with _MENU and has an extension of .DAT. For example, the USAS menu file is named BUD_MENU.DAT. On the main menu of each package there is an item that links to a local menu file. This local menu file is an empty menu file that you may customize as you wish. The local menu filenames end with _LCL. Therefore, the USAS local menu is named: BUD_LCL.DAT.
It is recommended that you only modify the *_LCL menu files. If you modify the other primary menu files, you will not be able to install updated menu files in the future without making all of your modifications over again.
Security for all menu items may be customized, even if they are part of the distribution, without modifying the menu files. This is accomplished by using the OECN Security Authorization (OSA) utility. See the OECN Software Security for the VMS System Manager manual for information about the OSA utility and local security. |
Following is the recommend procedure for modifying one or more menu files.
The first step is to redefine OECN$MENU$FILES as a search list. For consistency with other customized files, it is recommended that you use OECN$CUSTOM. However, you may use any directory that you wish. The rest of this chapter assumes that you are placing the customized menu files in OECN$CUSTOM. For example:
$ DEFINE/SYSTEM OECN$MENU$FILES - _$ OECN$CUSTOM,DUA0:[ODE.MENU.DIST] |
This will cause the Menu Processor and MENUUTL to search first through OECN$CUSTOM and then the distribution menu files.
You may want to make this logical assignment in your current process, instead of at the SYSTEM level, while changing the menu files. This will prevent any users from getting into a half completed menu. |
Copy the *_LCL.DAT menu files that you want to modify from the distribution into OECN$CUSTOM. Then use MENUEDT to make the desired modifications. By making all modifications in OECN$CUSTOM: will insure that installing future releases will not overlay your customized local menus.
Use the Menu Processor and MENUUTL to test the new menus as needed. If
you're creating new menus, be sure that the users have read access to
the new files.
6.1.3 Build a New Alias File
After all desired changes have been made, use MENUUTL to rebuild the alias file. You may put the alias file in OECN$CUSTOM or simply replace the current alias file in OECN$ALIAS. If you change the location of the alias file be sure to redefine the OECN$ALIAS logical.
You may build the alias file manually by running MENUUTL, or you may
use the BUILD_ALIAS.COM procedure in the OECN$ directory.
6.1.4 Redefine OECN$MENU$FILES Permanently
If you have not already done so, define the logical OECN$MENU$FILES to be a search list as above at the SYSTEM level.
At this point your users should have access to the customized menus.
6.2 After a Distribution
If you modify the local menu files in this way, your changes will not be affected by any future releases. Changes made by SSDT will automatically be installed when you copy the distribution menu files to the OECN$MENU$FILES directory.
However, you will have to rebuild the alias file after installing each distribution. After a package has been installed and the menu files moved to thier proper location, you must rebuild the alias file.
You may build the alias file manually by running MENUUTL, or you may use the BUILD_ALIAS.COM procedure in the OECN$ directory. The BUILD_ALIAS.COM procedure will automatically build a new alias file using the files in OECN$MENU$FILES. You can run the procedure interactvely by typing:
$ @OECN$:BUILD_ALIAS |
Or you can submit it for batch processing using DCL SUBMIT. By default,
BUILD_ALIAS will rebuild the default menu system based on the current
values of OECN$MENU$FILES, OECN$MENU and OECN$ALIAS logicals. If you
have other menu systems on your system, you can pass parameters to
BUILD_ALIAS to indicate the location and names of the menu and alias
files. See the comments in BUILD_ALIAS.COM for more information about
using this procedure.
6.3 Intercepting Menu Actions
Sometimes it is desirable, or necessary, to redefine the action associated with a menu item. For instance, you may want to force certain actions prior to running a particular program or force certain options to run in batch.
This may be done by intercepting the action line of specific options without modifying the menu files supplied by SSDT. You must write a DCL command procedure that will replace the action line you are going to intercept. Then assign a special logical to point to this command procedure.
The logical must be defined as follows:
$ DEFINE/SYSTEM OECN$MENU_ACTION_label filespec |
Where label is the menu option label that you want to intercept and filespec is the full filespec of the DCL command procedure. The logical may be defined at the system, group or process level, so you may intercept the action line for different classes of users.
If the logical is defined system-wide it will affect all menu systems that you have active on your system. If you have multiple menu systems that contain the same label then they will all be affected. If this is not what you want you may need to define this logical at the group or process level. |
After this logical is defined the command procedure will be executed instead of the action line defined by the menu file.
The following parameters will be passed to the command procedure :
P1 | Menu label name that invoked the procedure |
P2 | Original action line defined by the menu file |
P3-P8 | Other parameters entered by the user |
The procedure may use these parameters as it wishes or ignore them.
For example, suppose that you want to automatically execute a backup of the USPS files prior to the user running BUDDIS. The following procedure, called PAY:BUDDIS_ACTION, might be used:
$! $! PAY:BUDDIS_ACTION.COM -- Procedure used by the BUDDIS menu option $! $ on error then exit $ $ @PAY:SAVEPAY ! A-site procedure to perform disk backup set of $ ! USPS files. $ $ DEFINE/USER SYS$INPUT SYS$COMMAND $ RUN OECN$PAY:BUDDIS $ $ EXIT |
The following logical definition would be made to intercept the BUDDIS action for all users:
$ DEFINE/SYSTEM OECN$MENU_ACTION_BUDDIS PAY:BUDDIS_ACTION |
The command procedure BATCH_MAIL_MESSAGE.COM can be used to send a VMS
mail message via a batch job. This is useful for messages with large
audiences where the user does not wish to tie up their terminal for an
extended period of time.
7.2 Sending a Mail Message via Batch
To use the command procedure for generic mail messages:
Create the desired mail message using a text file.
Submit the procedure as follows supplying the necessary parameter values:
$ SUBMIT OECN$:BATCH_MAIL_MESSAGE/PARAMETER=("P1","P2","P3","P4") |
Where:
The OECN_VIEW utility allows users to view text files on the screen. It can be used for report files produced by OECN state software or other text documents. OECN_VIEW is a TPU based product, layered on DEC/EVE.
By default, OECN_VIEW will search for files in OECN$OUT which have the following extensions: *.TXT, *.LIS, *.DOC, *.RPT, *.LPT, *.RPT. These are the only files that OECN_VIEW will show to the user when they use the "Go_File" function or invoke VIEW without a file name.
However, A-sites may customize both the directory and/or the extension if desired. Define the OECN_VIEW_DIRECTORY logical to define the directory(ies) to be searched. It may be a search-list. The default for OECN_VIEW_DIRECTORY is OECN$OUT.
In order to change the file extensions, define the logical OECN_VIEW_FILES to be a search list containing the filespecs to search. Each entry in the search list must refer to OECN_VIEW_DIRECTORY.
Examples of the logicals are given below:
8.2 OECN_VIEW.COM
The OECN_VIEW.COM command procedure is found in OECN$. It is used to define the two logicals, OECN_VIEW_DIRECTORY and OECN_VIEW_FILES. Observe the following notes from this procedure.
$!+ $! Notes: $! $! This procedure is a shell for the OECN_VIEW utility. It provides $! defaults for the file directory and file types that the user may view. $! $! A-sites can configure VIEW to behave differently if desired by defining $! the following logicals: $! $! OECN_VIEW_DIRECTORY = Defines the directory OECN_VIEW will search $! when user uses the 'Go File' command or invokes $! VIEW without a file name. This logical may $! be a search list. The default is OECN$OUT. $! $! OECN_VIEW_FILES = Filespecs which user can see when the use $! 'Go file'. The logical should be a searchlist $! containing wildcard specfications for the files $! names or types the user can view. Each $! equivalence string must refer to OECN_VIEW_DIRECTORY $! for the device/directory. That is, OECN_VIEW_FILES $! should specify just the wildcard filename and type. $!- |
The following sample command file shows how to customize the directories and the file extensions to be viewed.
$!+ $! VIEW_EXAMPLES.com $! $! Example of using OECN_VIEW to view shared documents. This $! command procedure may be added to a local menu to allow $! users to view documents on-line. $! $! In this example, users are given the ability to view internet documents. $! Allows users to view *.TXT and *.DOC files in the directory $! PUB:[INTERNET_DOCS]. $! $! - $ set noon $ set noverify $ $ define/user OECN_VIEW_DIRECTORY PUB:[PUBDOM.NWOCA.INTERNET_DOCS] $ $ define/user OECN_VIEW_FILES OECN_VIEW_DIRECTORY:*.TXT,- OECN_VIEW_DIRECTORY:*.DOC $ $ @oecn$:oecn_view $ $exit |
The VIEW utility works automatically from the MENU. However, you could define a symbol to execute VIEW from DCL.
For example, define:
LOOK := = @OECN$:OECN_VIEW |
Then use the LOOK command from the $ prompt.
8.2.3 OECN_EDIT
The OECN_VIEW utility uses a special editor called OECN_EDIT. Its purpose is to provide I/O routines to allow TPU to automatically read and translate VFC files into text. Please see Chapter 9, OECN EDIT Utility, for more details.
OECN_EDIT is a foreign command replacement for the EDIT/TPU DCL
command. It is completely command line (qualifier and parameter)
compatible with EDIT/TPU. Its purpose is to provide I/O routines to
allow TPU to automatically read and translate VFC files into text. When
using OECN_EDIT, all VFC files read by TPU are converted into text with
form-feed and line-feed characters to preserve formatting. All other
file types are NOT affected by OECN_EDIT and are read normally by TPU.
This is different from the default TPU editor, which ignores VFC
formatting. OECN_EDIT is used by the OECN_VIEW.COM procedure to allow
VFC files to be viewed correctly. However, it may also be used with any
TPU section file as an editor.
9.2 Using OECN_EDIT
In order to use OECN_EDIT as your interface to TPU, define the following symbol:
$ EDIT := = $OECN$:OECN_EDIT/TPU |
Note: The /TPU qualifier is required.
You may also include other qualifiers which you would normally use with EDIT/TPU, such as /SECTION, /UNIT, etc. OECN_EDIT will use the normal EVE section and initialization files by default.
The OECN_KEYMAP utility allows users to select a terminal emulator,
such as REFLECTIONS, EXCURSIONS, or PERSONA. Using this utility defines
the logical OECN$KEY_MAP to point to a .INI file containing the desired
keymapping. The mapping allows you to re-label the standard function
keys. You cannot actually reassign the program functions to different
keys. That is, from the programs point of view, the user is required to
press a VT200 F11 for the "Find" function. However, you can assign F11
to any PC key you wish in the emulator and then relabel F11 on the
screen to match the PC keyboard.
10.2 Using KEYMAP
Upon selecting the KEYMAP option from the OECN menu the user is given a list of keymapping options to select from. This menu of options is built by searching for all files named OECN$KEYMAP*.INI in either the OECN$ or the OECN$CUSTOM directory. If the same filename is found in both directories, only the one in OECN$CUSTOM will be used. The description used in the menu will be determined by whether or not a "DESCRIPTION=xxx" command is used. If the command is found in the .INI file, the description will be used for the menu, otherwise the filename will be used in the menu.
When a user selects their option, the name of the .INI file selected is recorded in a file called OECN$KEYMAP.DAT in their SYS$LOGIN directory. If keymapping is turned off, the OECN$KEYMAP.DAT file is deleted from the SYS$LOGIN directory.
The OECN_LOGIN procedure has been modified to look for the existence of this file and define the OECN$KEY_MAP logical to point to the .INI file found in the .DAT file. After selecting their option in KEYMAP, OECN_LOGIN will be immediately executed causing the logical to be defined for that process. Then, each time the user logs in, OECN_LOGIN will check for the OECN$KEYMAP.DAT file and set the OECN$KEY_MAP logical appropriately for that process.
The following standard .INI files have been created:
These files may be used as a starting point to create other .INI files for other terminal emulators that may be in use by districts or to support customized key mappings for districts. Instructions are included at the top of the .INI files which explain how the files need to be formatted and which keys are able to be mapped. It is recommended that the new .INI file be placed in the OECN$CUSTOM directory and be given a different name if it is to be an additional menu option. It is also recommended that the description inside the .INI file be changed to something meaningful to the user as this is what they will see in the KEYMAP menu.
SETUPENV is a general purpose utility for establishing or switching to user environments. The goal of the utility is to provide a single place to configure the software environment (primarily logicals) for given entities and allow user processes to configure based on these environment settings.
The concept for SETUPENV is similar to the BUNNY/FROG utilities available from NOACSC. However, it is intended to be more flexible and capable of configuring multiple environments. SETUPENV is not tailored to any particular software product. It may be used in the configuration of state software, McSIS, InfOhio, or any other software that requires logicals in establishing a user's environment.
The general goals of the utility are as follows:
The SETUPENV utility is very flexible allowing the capability to deal with the variety of possible setups in use at the OECN DA Sites. This flexibility leads to a significant number of options in both the DCL command interface and options available in the OECN$SETUP initialization file. However, it is unlikely that any one DA Site will need all of the features provided by SETUPENV. Most sites will only need a limited set of options.
To get started with SETUPENV it is recommended that a simple OECN$SETUP
file with a minimal set of options for just a few entities be created.
Starting small will give the opportunity to experiment with the utility
to see how, or if, it can fit into your environment.
11.2.1 Entity Types
SETUPENV manages a user's context by assuming that any given process will have one context in each of the four entity "types". The current types of entities are:
Therefore, a user may have one entity selected in each of these types and change the context for one entity without affecting the others. For example, a user might have a context in DISTRICT_A and BLG_B but be eligible to switch into several different LIBRARY entities. SETUPENV will allow the user to switch into different libraries without affecting the current district and building.
Entities can be linked together to form logical hierarchies. For example, a district entity might define the context for USPS, USAS, and EMIS. A building entity might define the context for McSIS. When a user selects a building, it may be desirable for the user's process to also select the corresponding district entity so that the EMIS logicals are switched automatically. SETUPENV can handle these relationships using the PARENT attribute in the OECN$SETUP file. Please refer to the PARENT attribute for more information.
SETUPENV must be defined as a foreign command:
$ SETUPENV :== $OECN$:SETUPENV |
Syntax:
$ SETUPENV [entry_code...] [/MENU] [/NEXT] [/RESET] [/LOGIN[=([SIS],[INFOHIO],[BY_ACCESS],[USERNAME[=n]])] [/TYPE={DISTRICT,BUILDING,OTHER,ALL] [/LOG] [/[NO]PROMPT] [/CATEGORIES={wildcard}] [/APPLICATION={application}] [/ARCHIVE=[archive_code]] [/[NO]RESTRICT_IRNS] [/PRINT] [/USE] [/BUNNY] [/FROG] |
When /LOGIN is specified, SETUPENV will not issue errors if a default entry can not be found. This allows SETUPENV/LOGIN to be used in system-wide login procedures even for users who do not normally need a specific software context. |
If /TYPE is not specified to indicate the type of the next entry, then the /TYPE defaults to the same type as the current entry (OECN$SETUP_ENTRY). That is, by default, /NEXT moves to the same type of entry as the current entry. If there is no current entry, then the default is DISTRICT. |
When /NEXT is used, if the specified or next entry cannot be found SETUPENV exits with an error severity.
After successfully selecting an entry, OECN_LOGIN.COM is executed to ensure the users OECN$x logicals are set correctly. If the DAS has established the OECN_LOGIN_EPILOGUE procedure, it will subsequently be executed. This provides a means for the DAS to customize the behavior and do any additional processing after an entry is selected.
Likewise, when /EMIS is specified, EMIS_SELECT_EPILOGUE and
EMIS_SWITCH_FY will be invoked after successfully selecting a database.
11.3 Logicals Created By SETUPENV
After successfully selecting an entry, SETUPENV establishes a series of logicals (OECN$SETUP_*) to describe the current context and to maintain it's own context for subsequent invocations of SETUPENV. These logicals may be used by DCL procedures but should never be modified or deassigned (use SETUPENV/RESET to deassign the logicals if necessary).
The logical OECN$SETUP_ENTRY contains the current selected entry. This is the primary entry that was specified as a parameter, selected via the menu, or selected using /NEXT.
The logical OECN$SETUP_ARCHIVE contains the archive code if one was selected using /ARCHIVE or the menu.
One logical is defined for each of the entry types that has been selected. A user can have one context in up to four different "types" of entries: DISTRICT, BUILDING, LIBRARY, OTHER. For each type that has been selected, the corresponding logical will be defined:
The logical will not exist for types that have not been selected.
The value of the OECN$SETUP_CURRENT_* logicals is a string that describes the selected entry. The format for the string entry is:
"entry_code,irn,categories,applications" Where: entry_code the entry for this type irn from IRN attribute categories space delimited list of categories from CATEGORIES attribute applications space delimited list of applications from APPLICATIONS attribute |
This string is formatted in a manner that is easily parsed using the F$ELEMENT lexical function.
The following logicals may also be defined depending on the selected entries relationship with other entries:
Any of the logicals that do not apply to an entry will not be defined
(e.g. for a parent entry, the siblings logical will not be defined).
11.4 OECN$SETUP.INI
The OECN$SETUP initialization file defines the environment for various entities which use OECN (or other) software products. The default filename is OECN$CUSTOM:OECN$SETUP.INI. OECN$SETUP may be defined as a logical to override the location and filename.
Each "section" in the INI file describes an "entity". An entity might be a district, building, library or other entity where a specific context needs to be established. When the SETUPENV utility is executed to select an entity, the context is defined as specified in the rules for that section.
The parameters and formats for each section are as follows:
USPS
USAS
EMIS
EIS
VIS
SIS (McSIS)
INFOHIO
LOGICAL=OECN$EMIS_STU_SEARCH,IF_EXISTS,OECN$EMIS$DTA:EMSALT.IDX LOGICAL=OECN$EMIS$DTA,CONCEALED,EMIS_ROOT:[LIVE] |
SETUPENV defines logicals in the reverse order that they appear in the section. Therefore, conditional logicals should be placed prior to any logicals which they refer to. |
IDENTIFIER="[101,*]"
IDENTIFIER=SIS_BLDA
IDENTIFIER="OECN_USAS+ARCHBOLD_FISCAL"
IDENTIFIER does not necessarily restrict users from selecting a specific entry. If a specific entry is specified on the command line (manually or via a DCL procedure), SETUPENV will establish the context regardless of the IDENTIFIER attributes. This is useful for sites who do not need, or do not desire, to code specific identifiers into the OECN$SETUP file. |
Prior to setting any given entry, SETUPENV will attempt to process special sections named "$RESET_type". If a $RESET section of the appropriate type exists in the INI file, it will be processed prior to setting an entry.
The following reset sections may be specified:
When a user selects an entry of a specific type, the corresponding reset section is invoked prior to setting the environment for the selected entry.
This is useful in cases where some entries specify a process logical but others use a group logical. In order to switch from one entry to another, it is necessary to deassign the common logical from the process table prior to switching to the group logicals.
For example, consider that DISTRICT_A has a process logical definition of OECN$DTA. But DISTRICT_B has a group logical for OECN$DTA. Switching from DISTRICT_A to DISTRICT_B requires that the OECN$DTA be deassigned so the group logical is visable. SETUPENV does not attempt to keep track of this, rather it permits you to create a $RESET entry for each type to deassign logicals appropriate for your site. For example, $RESET could be defined as:
SECTION=$RESET_DISTRICT
LOGICAL=OECN$DTA
LOGICAL=OECN$OUT,"SYS$DISK:[]"
The above entry would cause SETUPENV to deassign OECN$DTA and define
OECN$OUT to the default directory prior to setting any valid entry. In
general, you should explicitly deassign any logicals in the reset
section that are defined in any entry of the same type.
11.4.2 Sample OECN$SETUP File
Below is a very simple OECN$SETUP.INI file which defines entries for one district and two buildings. The setup file can contain many such entries for as many districts and buildings provided that the entry codes are unique.
SECTION=SAMPLE TYPE=DISTRICT DESCRIPTION="Sample City Schools" LOGICAL=EMIS_ROOT, FSA:[EMIS_SAMPLE.],CONCEALED LOGICAL=OECN$DTA, FSA:[SAMPLE] LOGICAL=OECN$FORM_DIRDEP, OECN$PAY:DIRPRT.FRM SECTION=SAME TYPE=BUILDING DESCRIPTION="Sample Elementary School" PARENT=SAMPLE TABLE=SIS_SAME IDENTIFIER=SIS_SAME SECTION=SAMH TYPE=BUILDING DESCRIPTION="Sample High School" PARENT=SAMPLE TABLE=SIS_SAMH IDENTIFIER=SIS_SAMH SECTION=$RESET_DISTRICT LOGICAL=EMIS_ROOT LOGICAL=OECN$DTA LOGICAL=OECN$FORM_DIRDEP |
In this example, the buildings point to the district using the PARENT attribute. This creates the appropriate relationship. When the user selects one of the buildings, the corresponding logicals from the district entry will also be set.
Also notice that the district entry uses LOGICAL's to define the individual logicals. But the building entries use shared logical tables created outside of SETUPENV.
The special $RESET_DISTRICT section is provided to ensure that the
district logical get reset appropriately prior to setting an entry.
11.4.3 Special "APPLICATION" Entries
If an entry is defined with one or more APPLICATION attributes, then SETUPENV will search for an entry named "$APP_app", where "app" is the application code. This allows logicals, symbols or tables that are common for an application to be grouped into shared entries. Consider the following example:
SECTION=DISTRICT_A TYPE=DISTRICT APPLICATION=USAS LOGICAL=DISTRICT_ROOT,CONCEAL,DISK1:[DISTRICT_A.] SECTION=DISTRICT_B TYPE=DISTRICT APPLICATION=USAS LOGICAL=DISTRICT_ROOT,CONCEAL,DISK1:[DISTRICT_B.] SECTION=DISTRICT_C TYPE=DISTRICT LOGICAL=DISTRICT_ROOT,CONCEAL,DISK1:[DISTRICT_C.] SECTION=$APP_USAS LOGICAL=OECN$DTA,DISTRICT_ROOT:[DATA] |
In this example, the DISTRICT_ROOT logical would be defined for all three districts. However, OECN$DTA would only be defined for DISTRICT_A and DISTRICT_B because they have APPLICATION=USAS. DISTRICT_C does not have the application attribute and so would not invoke the $APP_USAS entry.
Note: The above is for example only. In practice, OECN$DTA might be more efficiently defined as a system logical. |
Application entries do not have a corresponding "reset" section.
Logicals defined in this manner may need to be included in the
appropriate "$RESET_type" section to ensure they are reset.
11.4.4 Special "INCLUDE" Section
A special section may be specified in any INI file called $INCLUDE. This section may specify other INI files to be included and processed with the primary INI file. The $INCLUDE section may only contain "FILE" attributes to indicate the file(s) to be included.
The $INCLUDE section permits INI files to be split into manageable segments or for INI files to be generated automatically. For example, you might create one INI file for each district and it's associated buildings. Or a separate utility may have information for creating subsets of the INI file. For example, the primary OECN$SETUP.INI might have:
SECTION=$INCLUDE FILE=OECN$CUSTOM:DISTRICT_A.INI FILE=OECN$CUSTOM:DISTRICT_B.INI FILE=OECN$CUSTOM:DISTRICT_C.INI |
Each INI file may also have an $INCLUDE section to indicate other files to be included. There is a maximum of 100 files that may be included throughout all INI files.
There is a performance penalty incurred for splitting INI files into many parts. SETUPENV must read the primary and all included files each time it is invoked. |
Duplicate entries are handled by merging the entries together. For example, if two included files both contain an entry for DISTRICT_A, then the attributes (e.g. LOGICAL attributes ) from both sections will be combined into a single entry. If duplicate entries specify attributes that only occur once per entry, then the last INI file to be loaded supercedes the previous value.
The INI files are NOT processed as they are encountered in the file.
Rather they represent a list of INI files that need to be processed.
SETUPENV will complete processing of the current file prior to begin
processing the next file. Therefore, included INI files will always be
processed after the file that included it (although perhaps not
immediately after). In general, you should not depend on files being
processed in any particular order.
11.4.5 Limits
Certain limits which apply to the OECN$SETUP.INI file are shown in the table below. Limits are 'per entry' unless otherwise noted.
Attribute | Maximum Length | Limit |
---|---|---|
FILE (in $INCLUDE section) | 50 | 100 total in all files |
SECTION | 12 | 500 total in all files |
DESC | 40 | 1 |
TYPE | 12 | 1 |
IRN | 6 | 1 |
CATEGORIES | 40 | 1 |
APPLICATIONS | 10 | 15 (five per line) |
ARCHIVE | 6 | 20 |
ARCHIVE (tables) | 32 | 3 per archive |
PROMPT | 40 | 1 |
IDENTIFIERS | 80 | unlimited * |
LOGICAL (name) | 50 | unlimited * |
LOGCIAL (value) | 80 | 4 per logical |
SYMBOL (name) | 24 | unlimited * |
SYMBOL (value) | 50 | 1 per symbol |
TABLE | 50 | unlimited * |
GROUP | Octal Value | 1 |
PARENT | 12 | 1 |
* = Attributes which are "unlimited" are limited by virtual memory available to the user. Very large INI files with large numbers of logicals or symbols may exhaust virtual memory. |
The /EMIS qualifier provides functional compatibility with the EMIS_SELECT.COM procedure. In this mode, SETUPENV will read the existing OECN$EMIS_DBS file and convert it to equivalent setup entries. The primary advantage of using SETUPENV over EMIS_SELECT is it's ability to use the /NEXT qualifier to process databases sequentially. SETUPENV also provides a slightly improved user interface over the DCL version.
SETUPENV/EMIS can be used even if the DAS has not created an OECN$SETUP.INI file. |
When SETUPENV/EMIS reads the OECN$EMIS_DBS, it creates a special entry which is equavalent to:
SECTION=$EMIS_dbscode DESCRIPTION=description from DBS CATEGORIES=RP_x FY_fy flags ! See below LOGICAL=OECN$EMIS$DTA,dev:[dir] ! From DBS line IDENTIFIER=OECN_SYSMAN ! If the DBS line contained "HIDE" |
The CATEGORIES is constructed based on the optional reporting period and flags parameter from the DBS line. The CATAGORIES value will always be in the format "RP_x FY_fy flags". Where x is the reporting period and "fy" is the fiscal year from the EMIS configuration. If the DBS included any additional flags (other than HIDE), they will also be included in the categories.
One implication of the above is that the /CATEGORIES qualifier can be used to select specific reporting periods. For example:
$ SETUPENV/EMIS/NEXT/CATEGORIES="*RP_N*" |
Would select the next EMIS database for reporting period N.
SETUPENV will invoke the DA Site's EMIS_SELECT_EPILOGUE procedure if it exists. However, the EMIS_SELECT_PROLOGUE is not supported. DA Sites that depend on the prologue procedure should contact the SSDT for a work around. |
It is possible to completely convert from using the OECN$EMIS_DBS file to corresponding entries in OECN$SETUP.INI. To do so, simply create sections in the OECN$SETUP file as shown in the previous section. The entry code must be prefixed with "$EMIS_". The corresponding code should be removed from OECN$EMIS_DBS, otherwise they will both be processed.
To retain compatibility with EMIS_SELECT, you should be certain to define the CATEGORIES attribute in the same format as shown. When entries are stored in the OECN$SETUP file, SETUPENV will not access the EMIS database to retrieve the fiscal year, therefore you should explicitly include FY_fy in the CATEGORIES attribute.
One advantage of converting DBS entries into OECN$SETUP is that the entry definitions are not limited to defining a single logical (OECN$EMIS$DTA). The $EMIS_ entries can contain any other valid attribute types, including TABLE, APPLICATION, SYMBOL, etc.
At the time of this writing, the original EMIS_SELECT.COM procedure is still invoked by the EMIS_SELECT menu option. Therefore, if you wish to switch to SETUPENV immediately, you would have to modify the EMIS menu or customize the EMIS_SELECT.COM procedure. In the future, EMIS_SELECT.COM will be modified by the SSDT to use SETUPENV/EMIS instead of the current DCL procedure. |
SETUPENV is similar to the USE, BUNNY, and FROG utilities provided by NOACSC. In some respects SETUPENV is based on these utilities. While SETUPENV is not 100% compatible with these utilities, it does attempt to simulate most of the behaviors and should be able to co-exist with them.
To provide an easier transition for sites who are using NOACSC's utilities, SETUPENV also provides command line compatibility with the utilities. The following sections provide information regarding compatibility with each of the utilities.
Symbols may be established for each of the utilities to invoke SETUPENV in the appropriate compatibility mode:
USE :== $OECN$:SETUPENV/USE BUNNY :== $OECN$:SETUPENV/BUNNY FROG :== $OECN$:SETUPENV/FROG |
This should allow SETUPENV to be used without modifying any existing
command procedures.
11.6.1 USE Compatibliity
If /USE is specified as the first qualifier to SETUPENV, then the original USE qualifiers are accepted. The table below lists the USE qualifiers and the corresponding qualifier/behavor for SETUPENV. /PROMPT is the default for /USE.
The SETUPENV /PRINTER qualifier is the default. However, instead of defining SYS$PRINT, LCL$PRINT is defined to point the queue from the owner field.
Qualifier | SETUPENV Implementation |
---|---|
/OUTPUT | Not implemented |
/ARCHIVE=nnnn | /ARCHIVE=nnnn |
/HOME | /RESET |
/PRIMARY_RUN | /LOGIN=(SIS,INFOHIO,USERNAME=2)/NOPROMPT |
$ if f$search("SYS$LOGIN:PMDF_SIGNATURE.DOC").nes."" - then define PMDF_SIGNATURE "@SYS$LOGIN:PMDF_SIGNATURE.DOC" |
If /BUNNY is specified as the first qualifier to SETUPENV, then the original BUNNY qualifiers are accepted.
The SETUPENV defaults when /BUNNY is specified are:
$ SETUPENV/BUNNY/PROMPT/EMIS=NORESTRICT_IRNS |
These defaults are affected by the original BUNNY qualifiers per the following table.
Qualifier | SETUPENV Implementation |
---|---|
/ARCHIVE=nnnn | /ARCHIVE=nnnn |
/CURRENT_BUILDING | not implemented |
/EMIS | not implemented (logicals defined by entry) |
/INFOHIO | /LOGIN=INFOHIO |
/PRIMARY_RUN | /LOGIN=(SIS,INFOHIO)/NOPROMPT |
/LOGICAL_ONLY | /NOPROMPT |
/RESTRICT_IRNS | EMIS=RESTRICT_IRNS |
/SCHEDULE_BUILDER | Chains to SIS$EXE:SISMENU_CMSB.EXE |
For interactive processes, if neither /PRIMARY_RUN nor /LOGICALS_ONLY is specified then SETUPENV/BUNNY chains to SISMENU.EXE, unless overridden by /SCHEDULE_BUILDER.
If /FROG is specified as the first qualifier to SETUPENV, then the original FROG qualifiers are accepted.
The SETUPENV defaults when /BUNNY is specified are:
$ SETUPENV/FROG/PROMPT |
These defaults are affected by the original BUNNY qualifiers per the following table.
Qualifier | SETUPENV Implementation |
---|---|
/CURRENT_BUILDING | Not implemeneted |
/LOGICALS_ONLY | /NOPROMPT |
/PRIMARY_RUN | LOGIN=INFOHIO |
/PRINTER | /PRINTER (see below) |
/OPAC=RESTRICTED | Chains to "@LIS_MGR:OPAC" |
/OPAC=UNRESTRICTED | Chains to "@LIS_MGR:OPAC R" |
For interactive processes, if neither /PRIMARY_RUN nor /LOGICALS_ONLY is specified then SETUPENV/FROG chains to "@LIS_MGR:LISMENU SYSADM.M"., unless overridden by /OPAC
11.7 OECN$SETUPENV API
SETUPENV provides a callable API which can be used by programs to
select entries. The API parallels the qualifier functions and syntax.
11.7.1 Working Storage Field(s)
Picture for string field are maximum sizes that will be used by OECN$SETUPENV. The string fields are based by descriptor, so the field sizes are not required to be the exact size. |
01 WS-FUNCTION PIC S9(4) COMP VALUE 0. 88 SET-DB VALUE 0. 88 NEXT-DB VALUE 1. 88 RESET-DB VALUE 2. 88 MENU-SELECTION VALUE 3. 88 LOOKUP-DB VALUE 4. 88 LOGIN-DEFAULTS VALUE 5. 01 WS-FLAGS. 03 WS-SIS-DEFAULT PIC X. 03 WS-INFOHIO-DEFAULT PIC X. 03 WS-BY-ACCESS PIC X. 03 WS-BY-USERNAME PIC X. 03 WS-EMIS-RESTRICT PIC X. 03 WS-EMIS-SELECT PIC X. 03 FILLER PIC X(26). 01 WS-SELECTED-DB PIC X(40). 01 WS-SEL-TYPE PIC X(25). 01 WS-SEL-CATEGORIES PIC X(40). 01 WS-SEL-APPLICATION PIC X(10). 01 WS-SEL-ARCHIVE PIC X(6). 01 WS-TYPE PIC X(25). 01 WS-DESC PIC X(40). 01 WS-IRN PIC X(6). 01 WS-CATEGORIES PIC X(40). 01 WS-APPLICATIONS PIC X(80). 01 WS-PROMPT-STRING PIC X(40). 01 WS-ARCHIVE PIC X(6). 01 WS-STATUS PIC S9(9) COMP. 88 OECN__NORMAL VALUE EXTERNAL OECN__NORMAL. 88 OECN__NOMORE VALUE EXTERNAL OECN__NOMORE. 88 OECN__NOTFOUND VALUE EXTERNAL OECN__NOTFOUND. 01 WS-RELATIONSHIPS. 03 WS-RELATION-COUNT PIC S9(4) COMP. 03 WS-RELATIONSHIP OCCURS 0 TO 40 TIMES DEPENDING ON WS-RELATION-COUNT. 05 WS-RELATION-TYPE PIC X. 88 WS-RELATION-PARENT VALUE "P". 88 WS-RELATION-SIBLING VALUE "S". 88 WS-RELATION-CHILD VALUE "C". 05 WS-RELATION-ENTRY PIC X(12). |
CALL "OECN$SETUPENV" USING WS-FUNCTION BY DESCRIPTOR WS-FLAGS BY DESCRIPTOR WS-SELECTED-DB BY DESCRIPTOR WS-SEL-TYPE BY DESCRIPTOR WS-SEL-CATEGORIES BY DESCRIPTOR WS-SEL-APPLICATION BY DESCRIPTOR WS-SEL-ARCHIVE BY DESCRIPTOR WS-TYPE BY DESCRIPTOR WS-DESC BY DESCRIPTOR WS-IRN BY DESCRIPTOR WS-CATEGORIES BY DESCRIPTOR WS-APPLICATIONS BY DESCRIPTOR WS-RELATIONSHIPS BY DESCRIPTOR WS-PROMPT-STRING BY DESCRIPTOR WS-ARCHIVE GIVING WS-STATUS. |
The arguments passed by descriptor may be OMITTED if the return value is not desired. However, the argument list must not be shortened, that is, the caller should explictly include the OMITTED keyword. |
WS-FUNCTION (read)Indicates the function to perform. Behavior matches the corresponding DCL qualifiers.
The LOOKUP-DB function is specific to the API and not implemented via the DCL command. LOOKUP-DB returns the information about the specified entry without actually setting the logicals. This allows a program to retrieve information about an entry without switching contexts.
WS-FLAGSList of one character flags which modify the behavior of the API. Unless noted otherwise, the flags should either contain a spaces or a "Y" if the flag is on.
The following flags are applicable when the LOGIN-DEFAULTS function is requested:
WS-SIS-DEFAULT Same as /LOGIN=SIS WS-INFOHIO-DEFAULT Same as /LOGIN=INFOHIO WS-BY-ACCESS Same as /LOGIN=BY_ACCESS WS-BY-USERNAME If set, just contain an ascii numeric value indicating the number of characters to use from the username as the entry code. e.g. Placing "2" in this flag, is the same as /LOGIN=USERNAME=2 WS-EMIS-RESTRICT Same as /RESTRICT_IRNS WS-EMIS-SELECT is the same as /EMIS
WS-SELECT-DB (modify, by descriptor)Entry(s) from INI file to select. Optional if MENU or NEXT functions are being performed. The actual entry selected is also returned in this parameter.
WS-SEL-TYPE (read, by descriptor)
WS-SEL-CATEGORIES (read, by descriptor)Values to restrict entries by type and/or categories.
Same as /TYPE and /CATEGORIES qualifiers.
WS-SEL-APPLICATION (read, by descriptor)Value to select by application. Same as /APPLICATION qualifier.
WS-TYPE (write, by descriptor)
WS-DESC (write, by descriptor)
WS-IRN (write, by descriptor)
WS-CATEGORIES (write, by descriptor)Return values which describe the entry. Same values that are also placed in the OECN$SETUP_CURRENT Logical.
WS-APPLICATIONS (write, by descriptor)Space delimited list of appliations associated with the current entry.
WS-PROMPT-STRING (write, by descriptor)The string SETUPENV would use to create the DCL and Menu prompt if /PROMPT is specified. Note: The API never sets the prompt. The calling routine may use this string to set the prompts, if desired.
WS-RELATIONSHIPS (write, by descriptor)A structure that describes the selected entries relationship to other entries based on the PARENT attributes. Currently three types of relationships are defined: Parent, sibling or children. The types of entries returned in this table will vary depending on the entry selected.
Note
Calling routines should not assume that only these three types of relationships exist. Future versions of the API may return other relationships.
WS-ARCHIVEContains code of archive if one was selected.11.7.4 Return Status
OECN$SETUP returns one of the following conditions:
OECN__NORMAL = Function completed successfully (Item selected or reset) OECN__NOMORE = When using "next" function, no more matching entries were found. OECN__NOTFOUND = Specified entry was not found. OECN__INVNEXT = Invalid combination of TYPE and current entry for NEXT function. Must specify a starting entry or valid select type. 11.7.5 Description
The OECN$SETUPENV routine does basically everything that the SETUPENV DCL interface does; however, there are some notable exceptions. Here is a list that the callable interface does NOT provide:
- Does not simulate /USE, /BUNNY or /FROG behaviors. Those qualifiers are handled by the SETUPENV utility and are not exposed to the callable interface.
- Does not modify the Menu or DCL prompts (a string is returned for setting the prompt if desired).
- Does not invoke OECN_LOGIN or EMIS_SWITCH_FY to ensure that the correct state software logicals are defined based on the version of the data files. If the calling program depends on files/programs in any of the OECN$x logicals, it should take it's own action to ensure the correct version is selected (or contact the SSDT if this is important).
- Does not implement the function of /PRINTER
Chapter 12
Installing and Using UMP - User Mail Profile System12.1 Overview
The UMP package provides a means for DA-sites to maintain user e-mail profiles in a standard way. This will provides an efficient means of sending mail to a large variety of users across the state. It will also allows for the creation of an electronic "white pages phone directory" which permits an easy way to lookup an e-mail address for any user on the OECN network.
12.1.1 Feature List
UMP provides the following features:
- Ability to add/modify user profiles.
- Allows end-user to modify their own profile.
- Permits 'group managers' to manage other user profiles within their group
- Imports an existing distribution list and creates a basic user profile (NM or PMDF style distribution lists).
- Ability to provide complete 'centralized naming' facility for both local and remote addresses, including ability to create user aliases independent of username or mailbox address.
- Exports user profiles into the following formats:
- NM
- PMDF style distribution lists
- PMDF DIRECTORY DAEMON format- Handles OECN standard distribution lists and allows local distribution lists to be added.
- Includes a utility to create distribution lists based on VMS identifiers.
- Includes a utility to check UMP profiles against SYSUAF.
- Includes a utility to run during login to determine if user has modified their own profile.
- Includes a utility to transmit UMP data into the CSO white pages directory.
- Tracks whether the user has modified/updated their own profile. Optionally, users who have not updated their own profile will be asked if they wish to update their user mail profile during login.
12.1.2 Web Attachments for OECN state-wide mail
A special feature of the OECN state-wide lists is the ability to "web-ify" attachments send to the OECN lists. As messages addressed to the OECN lists pass through the central OECN mail server, they are inspected for certain attachment types. If a suitable attachment type is discovered, it is placed on a public web site and the original attachment is replaced by a web link (URL) pointing to the documents location. Thus, only a single copy of each attachment must be stored on the OECN web server and will not be delivered to each user's mailbox.
Each user subscribed to UMP has the option of receiving the original message with the attachments or the version containing web links instead of attachments. Most users will benefit from receiving web links instead of attachments (reduced local storage, shorter download times and reduce risk of viruses. However, some users may prefer the original attachments, especially if they download their mail for disconnected (off-line) reading.
The benefit of web attachments to DA Sites can be signficant. Without web attachments, any message containing a large attachment must be delivered to each user's mailbox separately consuming considerable disk space and computer resources to deliver.
However, each DA Site may decide how, and if, to implement OECN web attachments for their users. Converting existing users to web attachments may cause confusion or concerns. Therefore, DA Sites are encouraged not to switch existing users to web attachments without training or notification.
12.1.2.1 Enabling Web Attachments
Web attachments are only enabled for each DA Site upon request. If you wish your users to have the ability to request web attachments, you must set ENABLE_OECN_WEBATTACH to "YES" and send mail to listmaster@oecn.k12.oh.us. The listmaster will verify the correct configuration of your UMP configuration and enable web attachments if appropriate. Your request may be denied if you have a non-standard UMP configuration. In that case, the listmaster will explain the problem(s) with your configuration.
To see if web attachments are enabled for your site, look for the SITE command in OECN$UMP_STANDARD.INI and see if the "webatt" parameter is set for your domain. If this parameter is set, then web attachments are already enabled. Note: You can not change OECN$UMP_STANDARD.INI yourself. Only the OECN listmaster can make the change that affects the OECN mail server.
12.1.3 Files
The following sections describe the files used and produced by the UMP system.
Files and Procedures Used
File/Procedure Use OECN$UMP_LOCAL.INI Contains A-site specific information and list codes. OECN$UMP_STANDARD.INI Contains OECN_wide list codes and definitions. IMPORT_NM_LISTS.COM Used to import data from NM style distribution lists into user profiles. IMPORT_PMDF_LISTS.COM Used to import data from PMDF style distribution lists into user profiles. EXPORT_LISTS.COM Used to generate both NM and PMDF style distribution lists. EXPORT_DD.COM Used to generate a file suitable for loading into a PMDF DIRECTORY DAEMON database. UMP_SEND_CSO.COM Used to transmit UMP data to the CSO white pages directory. Files Created
The table below describes the files created by UMP. Unless otherwise specified, the files are created in OECN$UMP:.
File Description MAIL_*_A.DIS One file for each distribution list. This file contains addresses of users who have requested to receive original attachments sent to an OECN list.. MAIL_*_W.DIR One file for each distribution list. This file contains addresses of user who have requested web links to attachments sent to the an OECN lists. MAIL_ALIASES.DAT Alias file defining aliases for UMP generated lists. This file is intended to be loaded into the PMDF alias database or included into the PMDF alias file. USER_ALIASES.TXT Alias file defining aliases for UMP remote users to create centralized naming. This file is intended to be loaded into the PMDF alias database. USER_RESERVE.TXT File containing reversing entries for users to create centralized naming. This file is intended to be loaded into the PMDF reverse database. 12.2 UMP Menu and Profile Screen
The program may be executed by typing:
$RUN OECN$:UMPat the $ prompt or from the menu system, type:
Menu>UMPThe Main UMP Menu
The following menu will appear:
___________________________________________________________________ | | | UMP - User Mail Profile Maintenance | | ------------------------------------------------------------- | | 1. PERSONAL - Modify Personal Profile | | 2. MAINTAIN - Maintain User Profiles | | 3. EXIT - Exit program | | | | | | | | | | | | | | | | | | Menu: UMP Option> | | | | XXX Accept XX Help XX Exit XXX Next | |_________________________________________________________________|Profile Screen
When you execute the UMP program and select the MAINTAIN option, a User Mail Profile screen similar to the following will appear:
___________________________________________________________________________ | | | Updated 12-DEC-1995 16:26 | | | | Username DOE Group Node NWOCAC User Type STAFF | | Internet Host/Mailbox NWOCA.ORG | | Name Doe, John Phone | | Title NBEC/NWOCA SSDT Documentalist/Supp Fax | | Position Code Cell/Pager | | Alternate | | District IRN | | Building IRN | | County Henry | | District/Organization NBEC/NWOCA | | Street Address | | City, State, Zip | | Comment | | URL | | Site information | | Management Groups | | | | | | UMP: User Mail Profile for OECN Users | | XX Top XXX Find XXX Lockmode | | XX Help XXX Add XXX Set Defaults | | XX Exit XXX Delete XXX Email Lists | | XXX Next XXX Modify | |_________________________________________________________________________|EMAIL Lists
In order to view the Email lists you currently subscribe to, press the [Email Lists] key. A screen similar to the following will appear giving both OECN statewide and local distribution lists.
___________________________________________________________________________ | User DOE Name Doe, John | | Subscribe by name _________________ | | Receive OECN attachments as web links? Y | |Subscribed? -- Subscribed Distribution Lists -- | | -- OECN lists -- | | Y MAIL_STAFF DAS Staff [Restricted] | | Y MAIL_SUPT_PUB Superintendents-Pub [Restricted] | | Y MAIL_TREAS Treasuere [Restricted] | | -- NWOCA lists -- | | Y MAIL_SSDT SSDT Staff | | Y MAIL_STAFF_EMIS EMIS Staff | | Y MAIL_STAFF_FIS Fiscal Staff | | | | | | | | | | | | Press <Show All Lists> to see all available lists | | | | UMP: E-mail Distribution Lists 1 of 1 | | XXX Accept (Resort) XX Cancel XX Prev Screen | | XX First Screen XXX Last Screen XX Next Screen | | XX Help XXX Show All Lists | | XX Exit Dist Lists XXX Exit Dist Lists | | | |_________________________________________________________________________|The field "Receive OECN attachments as web links?" indicates if the user wishes to receive links, instead of attachments, for files sent to the OECN state-wide lists.
You may subscribe or unsubscribe to any unrestricted list by entering the name of the list in the indicated field at the top of the screen and pressing the [Accept] key.
Table of Email Distribution Lists
In order to see the available distribution lists, press the [Show All Lists] key. A set of screens such as the following will appear:
___________________________________________________________________________ | | | User DOE Name Doe, John | | Subscribe by name _________________ | | Receive OECN attachments as web links? Y | | Subscribed? -- All Available Distribution Lists -- | | -- OECN lists -- | | MAIL_CSTAFF C-site staff (obsolete) | | MAIL_EMIS EMIS Coordinators [Restricted] | | _ MAIL_LIBRARIAN Librarian | | MAIL_PRINC_NONPUB Principals-Nonpublic [Restricted] | | MAIL_PRINC_PUB Principals-Public [Restricted] | | MAIL_PRINC_ELEM Principals-Elementary [Restricted] | | MAIL_PRINC_SEC Principals-Secondary [Restricted] | | _ MAIL_SPECED Special Education | | Y MAIL_STAFF DAS Staff [Restricted] | | MAIL_SUPT_NONPUB Superintendents-Nonpublic [Restricted] | | Y MAIL_SUPT_PUB Superintendents-Pub [Restricted] | | MAIL_SUPT_CITY Superintendents-City [Restricted] | | MAIL_SUPT_COUNTY Superintendents-County [Restricted] | | This is the first screen | | | | UMP: E-mail Distribution Lists 1 of 6 | | XXX Accept (Resort) XX Cancel XX Prev Screen | | XX First Screen XXX Last Screen XX Next Screen | | XX Help XXX Show Subscribed | | XX Exit Dist Lists XXX Exit Dist Lists | |_________________________________________________________________________|12.3 Startup Procedure
Follow the steps below to install UMP on your system:
- Create the system logical OECN$UMP to point to the device and directory where profile and distribution lists will be created. You should NOT use the same directory as your NM: or OECN$MAIL directories. You should create a new directory to contain these files.
- Use OECN_INSTALL and INSTALL PACKAGE as usual to install the OECN package.
- If installing for the first time, copy OECN$UMP_LOCAL.INI to OECN$UMP with world:read protection.
Modify OECN$UMP_LOCAL.INI to contain A-site specific information. You must specify A-site name, DECnet node, and internet host names, etc. See the .INI file for more information.- Run the UMP.EXE program and choose the MAINTAIN option. Then exit the program. This will create empy .IDX files in OECN$UMP. Set the protections on the *.IDX files to W:RW.
12.4 Loading Initial Data
Load existing distribution lists. If using NM style distribution lists, then use:
$ @OECN$:IMPORT_NM_LISTSIf using PMDF style lists created by SWOCA's PUBDOM OECNMAIL utilities, then use:
$ @OECN$:IMPORT_PMDF_LISTSThen run OECN$:UMP/MAINTAIN to review the user profiles. It should have set, at least, the username, DECnet node, and host/domain. If the NM lists were loaded, it will also have the name, district and county from the NM lists. If a user was on more than one list, the user profile will have multiple list codes.
After running the import, the protection on the UMP*.IDX files should be set to W:RW.
You may, if desired, import from both the NM and PMDF style lists. Unique usernames will only be added once, and a user will not be assigned to the same list more than once. Running both imports essentially "merges" the NM and PMDF lists. This might be useful if you are uncertain which of your lists is more correct.
12.5 Importing Other Lists
The IMPORT_NM_LISTS.COM and IMPORT_PMDF_LISTS.COM only import the standard NM lists or lists created by SWOCA's OECN$MAIL utilities. If you have other local lists which contain users you want to assign to a list (either a standard list or a local list), you can use the UMPIMPORT.EXE utility directly.
The UMPIMPORT utiltiy can read an existing list (either NM or PMDF format) and assign the users to the distribution list code you specify. The UMPIMPORT utility takes three parameters in the following form:
$ UMPIMPORT :== $OECN$:UMPIMPORT $ UMPIMPORT {NM|PMDF} {code} {file}The first parameter indicates if the list to be imported is a NM list or a PMDF list. NM style lists must contain at least the DECnet address. PMDF style lists must contain internet addresses. The second parameter is the distribution list code to assign to the users. The code must be defined in either OECN$UMP_STANDARD.INI or OECN$UMP_LOCAL.INI. The final parameter is the file to import. See either IMPORT_NM_LISTS.COM or IMPORT_PMDF_LISTS.COM for examples of using UMPIMPORT.EXE.
12.6 INI File Commands
The following INI commands are used in either the OECN$UMP_LOCAL.INI or the OECN$UMP_STANDARD.INI files. The following is a summary of these commands. See either of these files for more examples of their use.
Table 12-1 Table of INI File Commands Command Fields Explanation * SET_ASITE = "{Asite}" A-site acronym. Required field. * SET_NODE = "{Node}" Default DECnet node, cluster prefered. Required field. * SET_DOMAIN = "{Domain}" Default domain. Used as default for user profile and PMDF aliases. For example, SET_DOMAIN = "NWOCA.ORG". Required field. * SET_USER_TYPE = "{Code}" Default for "User Type" field. * LOCAL_LIST_PREFIX = "{Prefix}" Alias prefix for local distribution lists. Example, LOCAL_LIST_PREFIX = "Local_". May be null if local lists are not to be prefixed. LOCAL_HOST = "{hostname}" This parameter defines host name(s) which should be considered "local" to the current system. You may include multiple LOCAL_HOST lines if needed. If a users "internet mailbox/host" field contins a local address, then a user alias will not be created for them. Use this parameter if you change the domain specified by SET_DOMAIN but you still have user profiles which refer to the old address. Without this parameter, UMP will consider profiles with the old domain to be remote users and will create aliases for them. * PROCESS_CHANNEL = "{process_channel_name}" This parameter may be used to set the name of the reprocess channel to be used for processing UMP distribution lists. By default, UMPEXPORT will assume the reprocess channel is named reprocess.domain_name where domain_name is the domain from the SET_DOMAIN parameter. * DIRECTORY_DOMAIN = "{directory_daemon_domain}" This parameter may be used to specifically set the name of the directory daemon domain, if any. If this parameter is not specified then UMPEXPORT will assume that the directory daemon is named PO.domain_name where domain_name is the deomain from the SET_DOMAIN parameter. REWRITE = "{user@host}","{To_Domain}" Used by the UMPEXPORT to rewrite a particular domain to a "pseudo_domain" for public use in the CSO (White Pages) and for address reverals. The pseudo_domain may be name of your directory channel or an alias for the local host. For example, REWRITE = *,"po.nwoca.org". In this example, the command would cause all of NWOCA's users to have an email address of "username@po.nwoca.org" regardless of their real host name. In this way, remote users will not learn the real host name (which may change). REWRITE supports full wildcarding on the "From" domain portion of the parameter. The user@host may be a wildcard pattern which matches user email address from the UMP profiles. The new_host is the domain that the address will be rewritten to. This parameter allows you better control over how addresses are published in the CSO database (OECN White Pages) and address reversal CSO_REWRITE = Synonym for REWRITE * ERRORS_TO = "{Email_Address}" Address for "errors-to" parameter on mailing lists. If not preset, the "errors_to" address defaults to "postmaster". * EMPTY_ADDRESS = "{Email_Address}" Email address to place in any empty distribution list to prevent bounces to mail sent to an empty list. Defaults to "empty@bitbucket" which is suitable if the default "bitbucket" channel is defined. * ENABLE_OECN_WEBATTACH = {YES|NO} Enables users to request and receive "web attachments" sent to the OECN lists. Default is "YES". Set to "NO" to prevent users from requesting web attachments. * OECN_WEBATTACH_DEFAULT = {YES|NO} Specifies the "web attachment" default for new users. By default, new users will receive web links instead of attachments. Set this to NO if you wish new users to recieve the original attachments. * ALLOW_USER_ALIAS = {YES|NO} Indicates whether the 'Alias' and 'From' fields should be activated. When set to NO (the default), the alias and from fields will be disabled. When set to YES, the fields will be active. Note: When set to YES, the DAS must customize thier procedures to load the USER_ALIASES.TXT and USER_REVERSE.TXT file into the appropriate PMDF database. LISTPARMS = "{named parameter}" Specifies named parameter(s) to added to the MAIL_ and local aliases created by UMP. Multiple named parameters may be specified using multiple LISTPARMS lines. The named parameters will be included on all MAIL_* and local UMP aliases. See the PMDF Managers Guide for information about named parameters. Note: Too many named parameters may prevent the alias from fitting in the PMDF Alias database. In that case, the MAIL_ALIASES.DAT file must be included into the PMDF alias file and the configuration compiled nightly. * PROTECT_SITE_INFO = [YES|NO] Protect "Site Info" field in UMP. The default is "YES". TYPE = {Type},"{Description}" Defines a distribution list type. Types 01---0z are reserved for OECN use. Types 10---zz are available for DAS use. Types must be defined prior to using a DEFINE_CODE line. DEFINE_CODE = [Type-],{Code},"{Description}", {List_Name},[User_Modifiable], [Master_Code] Type is a two digit no., considered above. Code is a 1 to 8 character code used in the UMP maintenance program. List_Name is the file name suffix used to create the distribution list filename. User_Modifiable (Y,N) allows the user to subscribe or unsubscribe to the list. The default is "NO", which means that the list is restricted. Master_Code contains the master list code to which a sublist refers. In the case of a master list, this field also contains the master list code. See the section, Defining Local Distribution Lists, for more details. The default list type for codes in the OECN - wide file is 01. e.g. in the OECN$UMP_STANDARD.INI file, DEFINE_CODE=COUN,... is equivalent to DEFINE_CODE=01-COUN,...
If the first character of the distribution codes is a hyphen (--), the distribution list is obsolete and should be phased out. This means that the export routines will not force creation of an alias pointing to empty distribution lists and will not assign these empty lists as a sub-list of a master list.
TYPE_RESTRICT = {Type},{Method},{Value} For example, TYPE_RESTRICT= 02,SUBSCRIBED,01-STF, restricts type 02 lists to users who are also subscribed to the list 01-STF. See the section below on Restricting Types, for more information and kinds of restrictions. CONVERT = {From_Code},{To_Code} This command will automatically convert an "old" distribution list code to a "new" one. For example, CONVERT = 01-PM,02-PM. The "From_Code" is the old (original) distribution list code, and "To_Code" is the new distribution list code. Note, that codes must specify both the type and code (e.g. 01-PM). You should NOT rely on the default prefix when specifying conversions. See the section below for more information on conversions. NM_MAP = {From_Code},{To_Code} The command causes codes to be mapped to produce a single old-style NM distribution list for compatibility with NM_SEARCH. SITE = "{Domain}",{CSO_ID} This command defines the OECN DAS host name. Each SITE in this section will be included in the OECN_xxxx distribution lists. It also specifies each site's CSO white pages identifiers. A range of CSO ids has been allocated to each site. These fields should not be modified. This command should not be placed in the OECN$UMP_LOCAL.INI file.
* This command can appear at most one time in the Local INI file.
12.7 Export NM and PMDF Style Lists
A procedure called OECN$:EXPORT_LISTS.COM to is used to create the NM and PMDF style distribution lists and associated aliases. It is recommended that each DAS write a custom DCL procedure which invokes EXPORT_LIST.COM which also contains any local commands to add aliases, etc. This procedure should be scheduled to run nightly to keep the aliases and distributions lists up to date. See Section 12.18 for an example procedure which takes advantage of most of UMP's features.To run the procedure:
$ @OECN$:EXPORT_LISTS "{options}"The P1 parameter should specify one or more of the following options separated by commas:
Option Description REBUILD Rebuild the PMDF alias database from scratch using the alias file(s) from UMPEXPORT. Use REBUILD if you allow UMP to control all the aliases in your database, or if you add additional aliases after EXPORT_LISTS.COM is executed. MERGE (Default) Merge the UMP aliases with the existing PMDF_ALIAS_DATABASE. Use this option if you control/rebuild the alias files prior to executing EXPORT_LISTS.COM Note: If this option is used then UMP will always add aliases and old UMP aliases will not be deleted unless you are rebuilding the database yourself elsewhere. Note: REBUILD and MERGE are mutually exclusive. USER Indicates that the USER_ALIASES.TXT and USER_REVERSE.TXT should be loaded into PMDF_ALIAS_DATABASE and PMDF_REVERSE_DATABASE, respectively. This should option should be specified if the DAS is using remote addresses or user alias features of UMP. DEFER Defers placing updated PMDF databases back into the PMDF production directories. This permits the DAS procedure to add additional aliases to the database before being used by PMDF. If this option is specified then the DAS's procedures are responsible for moving the databases back into the PMDF production directories. The PMDF database files created are: OECN$UMP:ALIASES.DAT (Alias database) OECN$UMP:REVERSE.DAT (reverse database). If you are using UMP as your only source of PMDF database aliases, you should specify REBUILD. This will ensure that any old or obsolete aliases are not retained in your database.
However, if you have other aliases which you are building into your local PMDF alias database, you must take local action to periodically rebuild the PMDF alias database using your own aliases. This is necessary to ensure that old aliases are not retained in your PMDF alias database.
If you are unfamilar with how aliases work in PMDF and how the alias database (PMDF_ALIAS_DATABASE) and the alias file (PMDF_ALIAS_FILE) interact, we recommend that you do the following:
- Allow UMP's EXPORT_LISTS.COM to rebuild the alias database from scratch (by specifying the REBUILD option). This will give UMP complete control over the aliases and ensure that no obsolete aliases are retained.
- Place any local aliases (those not created by UMP) in your PMDF_ALIAS_FILE. This file is not used by UMP and will allow you to create local aliases without them being wiped out by UMP. Alternatively, you can specify the DEFER option in EXPORT_LIST and write procedure which adds additional aliases prior to moving the databases into PMDF_TABLE:.
12.7.1 Centralized Naming
This section describes several ways in which UMP can be used to provide centrialized naming in a PMDF configuration. Centralized naming provides means to provide stable user email addresses regardless of where the users mail is actually being delivered. This section assumes you are already familar with the basic concepts of centralized naming in PMDF.
12.7.1.1 Remote Mail Boxes
UMP can provide centralized naming for users who have "remote" mailboxes. Using UMP's centralized naming, a user can have an address such as USER@das.org even if thier mail is being delivered to a different address (mailbox), regardless of where that mailbox resides. The centralized naming may be used to deliver mail to remote systems on behalf of the user, or simply as a means of forwarding mail without resorting to VMS Mail forwarding.
Examples of "remote" users include:
- Users who wish to have thier OECN mail delivered to a different account (e.g. on the same system or on a third-party ISP)
- Users who's mailbox exists on a school district mail server or another DAS mail server.
- Users who's mailbox is in PMDF popstore
The primary benefit of centralized naming is that it permits a user to have a stable mailing address even if the actual mailbox changes in the future. Everyone with an DAS can have the same host name in thier address regardless of where the mailbox reside.
UMP determines if a user requires an alias based on the "Internet Host/Mailbox" field on the profile. If the "Internet Host/Mailbox" field contains a different mailbox or a "remote" hostname, then the user is considered "remote" and an alias is generated. The definition of "remote" is if the host name portion of the address does not match the value of SET_DOMAIN or any LOCAL_HOST in the OECN$UMP_LOCAL.INI. For each user which UMP determines requires an alias, an line is written to USER_ALIASES.TXT. A line is also written to USER_REVERSE.TXT. USER_REVERSE.TXT contains the appropriate "address reversal" entry which allows PMDF to adjust the user's "From:" address for outgoing mail.
Both USER_ALIASES.TXT and USER_REVERSE.TXT are suitable for loading into the PMDF_ALIAS_DATABASE and PMDF_REVERSE_DATABASE, respectively. The use of these files is optional and is up to each DAS to determine if they are useful in their configuration. EXPORT_LIST will not load the files into PMDF by default. You must either set the USER option in EXPORT_LISTS or write a custom procedure to load these files after EXPORT_LISTS is executed.
Please note, the USER_REVERSE.TXT is only effective if mail sent by the user is routed through your system. For remote systems running mailers which send internet mail directly (such as a remote VMS system running PMDF), you must use that system's mechanisms for rewriting "From" address lines. For instance, on a remote PMDF system, adding a REVERSE mapping to the PMDF_MAPPING_FILE may be appropriate. Alternatively, you could take steps to ensure that all outgoing mail is routed through the system containing the UMP reversing entries.
When exporting CSO, the user's real mailbox will be exported by default. You can control this by using the REWRITE line in the local INI file to rewrite addresses to either the DAS domain, a host alias, or the directory channel. If you do this, be sure that you are loading the appropriate file into either PMDF_ALIAS_DATABASE or your directory channel. An address rewritten in this manner will be rewritten back to the username or alias on the UMP profile (not the username in the mailbox field).
12.7.1.2 User Aliases
UMP provides the ability to create a user-specific alias independent of the username or actual mailbox. For example, a username of "SMITH@nwoca.org" could have an alias of "dave.smith@nwoca.org". Furthermore, the user alias may optionally be used as the user's backward pointing (From:) address. This permits the user to have an easier to remember address as well as obscuring the actual username for security purposes.
The user aliases in UMP are implemented as two fields on the UMP profile called "Alias" and "From". The alias is a 32 character field which may consist of letters, digits or dots (.). The alias is required to have a least one dot to avoid duplicates with VMS usernames. The 'From' field is a flag indicating if the alias should be used as the profile's official "From:" address. If the "From" flag is set to 'N', then the alias is merely an alternative address for the user and will be published in the CSO (White Pages). If the flag is set to 'Y', then an entry will be added into the USER_REVERSE.TXT to reverse the backward pointing addresses for any mail sent by the user.
The 'Alias' and 'From' fields may only be modified by a system or group manager. That is, end-users cannot specify thier own alias or reversal. This allows the appropriate manager to control the alias standards. It also prevents users from changing thier alias or 'From:' address frequently without understanding the implications or attempting to forge mail messages.
Group managers are required to specify an "alias prefix" which matches one of the group codes they are responsible for. For example, if a group manager is responsible for the groups "AA,AB", then they may only specify aliases beginning with "aa." or "ab.". This helps ensure uniqueness in the mailbox namespace when multiple group managers are responsbile for different groups of profiles.
Since the DAS must take additional configuration steps in PMDF to implement aliases and address reversal, the 'Alias' and 'From' fields are disabled by default. The DAS must take explicit action (see below) to implement this feature.
12.7.1.2.1 Implementing User Aliases
The following steps must be performed in order to activate the user alias and address reversal using UMP:
- Configure PMDF to use the 'reverse database' on the appropriate channels. This feature is enabled by default in a standard PMDF configuration. See the PMDF documentation for more information.
- Set ALLOW_USER_ALIAS to YES in OECN$UMP_LOCAL.INI. This flag enables the 'Alias' and 'From' fields in UMP.
- Invoke EXPORT_LISTS.COM using the USER option to cause the USER_ALIASES.TXT and USER_REVERSE.TXT files to be loaded into the appropriate database. See Section 12.18, Example Procedure for Periodic Rebuilds for an example procedure which invokes EXPORT_LISTS.COM.
12.8 Distribution List Codes
Each distribution list code has a "type" prefix. The type value allows distribution lists to be organized into subsets independent of the list's name and allows restrictions to be placed on lists so users only see lists that may apply to them. The type codes also ensure that lists defined by the OECN do not conflict with those created by the DAS.
This version uses an 8 character code in the following format:
TT-CCCCCCWhere TT is the distribution list "type" (or category) and CCCCCC is the distribution list code. The following types are predefined by UMP:
01 OECN-wide user distribution lists 02 OECN DAS staff-only lists 10 Default type for lists defined by DAS Types beginning with "0" are reserved for OECN use. All other types (any type not starting with "0) are available for use by the DAS. Currently, a maximum of 100 types can be defined.
Type 10 is predefined and available for DAS use. To add additional types add a line to the local ini file, like:
TYPE=tt,"description"For example:
TYPE=11,"NWOCA Staff Lists"Once a type has been defined, you may use the type in subsequent DEFINE_CODE lines, for example:
DEFINE_CODE = 11-STFRCP, "Staff Recipes", STAFF_RECIPIES
DEFINE_CODE = 11-STFJOK, "Staff Jokes", STAFF_JOKESThis creates two lists called MAIL_STAFF_RECIPIES and MAIL_STAFF_JOKES. When displayed in UMP, they will be sorted and displayed under a subheading called "NWOCA Staff lists".
Restricting Types to Particular Users
Using types allows you to organize your lists into categories for presentation to the user. But it may also be useful to restrict categories of lists to particular types of users. UMP allows you to apply several types of restrictions based on the user's profile information.
Note that type restrictions do NOT affect whether or not a user can subscribe or unsubscribe from a given list. Each DEFINE_CODE line determines whether a list is user-subscribable. The type restrictions only limit whether the user can see a list or not.
Please note that the type restrictions are not intended as rigid security. Since some of the criteria is based on user modifiable fields, it is possible for a user to enter incorrect information and get assigned to the wrong lists. For example, a user might enter another district's IRN which allows them to subscribe to another districts lists. However, if the user changes the IRN back to the correct value, UMP will remove them from any incorrectly assigned lists.
To apply a restriction to a type value, use one of the following commands in the local ini file:
TYPE_RESTRICT=tt,SUBSCRIBED,tt-cccccc Restricts type tt to users who are also subscribed to list tt-ccccc. TYPE_RESTRICT=tt,IRN,nnnnnn Restrict type to users who have a district or building IRN matching nnnnnn TYPE_RESTRICT=tt,TYPE,xxxx Restrict type to users with a 'user type' field matching xxxxx. TYPE_RESTRICT=tt,COUNTY,xxxx Restrict type to users with a 'county' field matching xxxx. TYPE_RESTRICT=tt,USERNAME,wildcard Restrict type to users with a 'username' field matching wildcard mask. Multiple TYPE_RESTRICT lines may be added for a single list type. In this case, the restrictions form a logical OR operation. That is, if the user matches any one of the criteria, they will have access to the type.
For example, to restrict the type 11 lists (from the example in the previous section) to DAS staff members, the following restriction could be applied:
TYPE_RESTRICT=11, SUBSCRIBED, 01-STFThis will restrict all type 11 lists to users who are also subscribed to the standard DAS staff list.
12.9 Auto Conversion of Distribution List Codes (Optional)
Because of the features provided by the distribution list types, it may be desirable for DAS's to change their existing distribution list codes. By default, during the conversion, all distribution list codes in the LOCAL INI file are prefixed with type 10. For instance, if a DAS has defined several "staff" lists, you may wish to separate these into a separate type and restrict them to staff members only.
To help facilitate this, an optional command is available for the LOCAL INI file called CONVERT. The CONVERT command takes the following form:
CONVERT={old_code},{new_code}For example, to convert an existing code of 10-SEM (Staff EMIS) to 11-STFEMS, place the following line in the LOCAL.INI:
CONVERT=10-SEM, 11-STFEMSNote that the prefix is required even if you did not use the prefix when defining the code originally. Remember that any codes defined by the local ini file default to type 10, so if a code was defined without a type, it's type is 10.
When changing a existing code using a CONVERT line, you should change the DEFINE_CODE line to reflect the new code at the time you add the CONVERT line. You should not reuse old codes until you are certain they no longer exist in the UMDDAT file. After you are certain the old code no longer exists in the UMDDAT file, you may remove the CONVERT line from your INI file.
Adding the CONVERT line and revising the DEFINE_CODE line, is all that must be done to convert an existing list. UMP and it's utilities will automatically convert the code as needed "on-the-fly". If you look at the UMDDAT.IDX file after making a conversion, you may notice that some users have the new code and others still have the old code. This is the expected behavior. The new code will not be physically written to the file until the record is changed with UMP's Modify function.
If you are creating locally written programs to update or report on user's distribution list codes, it may be confusing to have both the old and new codes on file. In this case, you may run the UMPUPDATE program to force the conversion on all records.
12.10 Defining Local Distribution Lists
To define a local distribution list, you need to add several additional lines to the OECN$UMP_LOCAL.INI file.
You will probally need to use the ini commands:
LOCAL_LIST_PREFIX, TYPE, TYPE_RESTRICT, DEFINE_CODEExample 1
The following example illustrates how to define a local distribution list for payroll clerks.
Add the following lines to the OECN$UMP_LOCAL.INI file:
TYPE = 12,"Local Payroll Clerks" DEFINE_CODE = 12-PAYCLK,"Payroll Clerks",PAYROLL_CLERKIn order to actually subscribe to this distribution list, a user or DAS person, will have to access the user's UMP profile, bring up the list of available distribution lists, and subscribe the person.
Example 2
As another example, suppose you wish to set up a distribution list for staff jokes, restrict the list to just those users who have access to DAS staff lists, create sublists for fiscal, programming, and EMIS jokes, and set a prefix for local lists.
Add the following lines to the OECN$UMP_LOCAL.INI file:
LOCAL_LIST_PREFIX = "local_" TYPE = 11, "Local Staff Lists" TYPE_RESTRICT = 11,SUBSCRIBED,01-STF DEFINE_CODE = 11-STFJOK,"Staff Jokes",STAFF_JOKES,Y,11-STFJOK DEFINE_CODE = 11-FISJOK,"Fiscal Jokes",FISCAL_JOKES,Y,11-STFJOK DEFINE_CODE = 11-PRGJOK,"Programmer Jokes",PROGRAMMER_JOKES,Y,11-STFJOK DEFINE_CODE = 11-EMSJOK,"EMIS Jokes",EMIS_JOKES,Y,11-STFJOKThen those users who are subscribed to the 01-STF list will see the following entry when they access the table of available lists in the UMP program.
-- LOCAL STAFF LISTS --
---LOCAL_STAFF_JOKES Staff Jokes
---LOCAL_FISCAL_JOKES Fiscal Jokes
---LOCAL_PROGRAMER_JOKES Programmer Jokes
---LOCAL_EMIS_JOKES EMIS Jokes
Users who are not subscrbed to the list 01-STF would see not entries for "Local Staff Lists" including the heading itself.
Note that the three sublists point to the master list, 11-STFJOK in the DEFINE_CODE lines. This makes these sublists, so that mail addressed to one of these sublists will be delivered to anyone on this list and anyone on the master list, but not to users on any of the other sublists. Also, mail addressed to the master list will be delivered to everyone on any of the sublists.
12.11 Profile Group Management
UMP provides the ability to segregate profiles into management groups and delegate responsibility for the groups to selected individuals. Once delegated, the group manager has nearly complete control over the content of the profiles in the groups they are responsible for. They may add, change or delete profiles within their group and assign profiles to unrestricted distribution lists.
Note
Group managers may not add or remove profiles from the restricted distribution lists. These lists (MAIL_STAFF, MAIL_SUPT_PUB, etc.) are the responsibility of the DA-site and may not be delegated.User profiles are assigned to groups simply by placing a value in the 'Group' field on the UMP profile. If desired, the field may be massed changed using Datatrieve by modifying the GRP field in the UMP_HEADER domain or UMP view. This value is a protected field and may only be changed by DAS personnel or a group manager associated with the group.
A user may be granted management rights to one or more groups by entering a comma separated list of groups in the 'Management Groups' field. A limit of ten comma separated groups may be included. The following standard wildcards are supported in the management groups field:
* Any sequence of zero or more characters % Exactly one character # Exactly one numeric character @ Exactly one alphabetic character The user with any value in the 'Management Groups' field will be permitted access to the MAINTAIN option in UMP. No special security identifiers are required. The user will be able to view any profile on the system, but will only be permitted to modify or delete profiles associated with one of their groups. If a group manager adds a profile, they must enter a group which matches their group management field.
The value of the group field is entirely arbitrary. The DAS may assign the groups in any fashion desirable. Most likely, a group would be created for all users in a district and one or more group managers would be assigned to manage that district's profiles. However, groups could be further defined by building, or perhaps by classes of users (teachers, administrators, etc.). Since wildcards are supported, it is possible to devise complex hierarchies of groups which permit different users various levels of access.
Group managers should be carefully instructed regarding local conventions for the various UMP fields. In particular, if the DAS uses the USER_ALIAS.TXT to route mail to remote mailboxes, then proper use of the UMP 'Internet Host/Mailbox' field is critical to ensure proper mail delivery. Likewise, if the DAS uses the 'User Type' field to control which profiles are sent to the OECN White Pages, then the correct values must be provided to the group manager.
12.12 Export DIRECTORY DAEMON File (optional)
You have the option of exporting to a DIRECTORY DAEMON database. Executing the EXPORT_DD.COM file will produce a file suitable for loading into a PMDF DIRECTORY-DAEMON data file. The procedure only produces a DIRECTORY-DAEMON.TXT file in the OECN$UMP directory. You must execute the appropriate PMDF CRDB command to create the indexed file database and place it in the PMDF_ROOT:[DIRECTORY] with the appropriate filename for your pseudo-domain.
EXPORT_DD creates several aliases for each user. For example, the following aliases would be created for username "SMITH" and a profile name "Dave Smith":
SMITH SMITH@nwoca.org dave.smith SMITH@po.NWOCA.ORG smith.dave SMITH@po.NWOCA.ORG d.smith SMITH@po.NWOCA.ORG smith.d SMITH@po.NWOCA.ORG Notice that the first alias (the username alias) sends directly to the user's "real" address. The other aliases (dotted names) send to the username at the directory channel. Since the username should be unique, the first alias should never cause a bounce. The other addresses may cause a bounce if they are not unique (the sender is notified of the duplicates and their addresses). Since only dotted names and their addresses are returned to the sender, the sender never learns the "real" address. This helps isolate remote users from knowning the real host names of the recipient.
The directory channel for the DAS is assumed to be "po." plus the value of the SET_DOMAIN line from the OECN$UMP_LOCAL.INI file. For instance, for nwoca.org, the directory channel is assumed to be po.nwoca.org. If the DAS is using a different name for the directory channel, you may place the following line in the OECN$UMP_LOCAL.INI file:
DIRECTORY_DOMAIN=pseudo.domainSee the PMDF System Adminstrators Guide for more information about the directory daemon, channels and pseudo-domains.
12.13 Submit UMP Data to OECN CSO Database
The CSO nameserver is a public domain software system which allows a single database to be built containing name and address information. The CSO is much flexible and allows client/server access to the database anywhere on the network. Users can use GOPHER, LYNX or other web browsers to perform queries. A utility called PH is also available to perform direct queries against the central database.
To transmit UMP data for loading into the CSO database, each DAS should run the UMP_SEND_CSO.COM command procedure once per week. This command procedure will extract the UMP database into CSO format and send it to NWOCA.ORG for loading into CSO.
Unless instructed otherwise, please do not routinely run UMP_SEND_CSO more than once per week. In general, a single weekly run is sufficient to keep the OECN White Pages up to date. However, situations will arise where an extra run of UMP_SEND_CSO is necessary or desirable. For example, if you change domain names, or load a large number of new users or make significant changes to the the profiles. In these cases, feel free to make a special run of UMP_SEND_CSO.
NWOCA's system will run an update routine at approximately midnight each night to load any files submitted during the day. Therefore, the CSO data on file at the server will be updated the day after you run UMP_SEND_CSO. This schedule means that your CSO data will be at most one week behind when compared to your current UMP database.
If you are also using EXPORT_DD.COM to build a DIRECTORY-DAEMON database, you may wish to have the email addresses in the CSO database reflect your directory daemon address, rather than your user's real addresses. In this case, you may add the following line to your OECN$UMP_LOCAL.INI file:
REWRITE=*,"pseudo_domain"Where "pseudo_domain" is the domain name of your directory channel, for example, NWOCA uses the following line:
REWRITE=*,"po.nwoca.org"This line would cause all of NWOCA's users to have an email address of username@po.nwoca.org regardless of their real host. In this way, remote users will not learn the real host name (which may change).
12.14 Master List/Sub-list Handling
Starting with the 29-Aug-95 version of UMPEXPORT, the master lists are handled differently than in the past. Previously, there were master lists which pointed to the respective sub-lists. But this caused duplicate messages if the user was on more than one sub-list. With this version, the master lists will contain the actual email addresses of the users who are on the master list or any of the sub-lists.
There were also "compatibility" codes which were used for the original NM distribution list codes. This proved too cumbersome and confusing. Therefore, a new method of handling the master lists was implemented which essentially combines the master lists with the NM-compatibilty lists.
The codes PRN, SPT and TRS were previously indicated as "Obsolete-NM" codes. This is no longer the case. These codes are now "master list" codes (and indicated as such on the UMP help screen). If a user is coded as having a "master list" code, they will placed on the master list _and_ will also be placed on _all_ of the sub-lists for that code.
If a user is coded on one of the sub-lists, they will be placed on that sub-list and the corresponding master list.
These changes provides two advantages:
- It provides a simple way of placing a single user on all sub-lists using a single code. For example, if a DAS staff member wishes to be placed on all the MAIL_TREAS_xxx lists, they may simply be given the TRS master code. This will cause them to be placed on the master list and all of TRS's sub-lists.
- Users which have not yet been recoded to one of the more specific lists will automatically be placed on the master and all sub-lists. This ensures that users who have not been recoded to the appropriate list will still receive mail sent to any of the lists.
Note
This change means that it is somewhat less important to get your users migrated off of the old distribution list codes. However, if you leave users on the master list codes, they may receive mail that was not intended for them. For example, if mail is sent to mail_supt_jvsd, it will be received by all users who are on the SPT or SJV lists.12.15 UMPCHECK - Verifying UMP Profiles against SYSUAF (Optional)
UMPCHECK is a utility which reads the UMP profiles and compares the usernames to the SYSUAF file. It reports usernames which do not exist, have been disusered or dismailed. Optionally, UMPCHECK can delete profiles for such usernames. By default, UMPCHECK only checks profiles when the user's DECnet node name matches the values of the SYS$NODE or SYS$CLUSTER_NODE logicals. Other users are considered to be remote users and are not verified against the current node's SYSUAF. UMPCHECK must be run as a foreign command and accepts the following syntax:
$ UMPCHECK {CHECK|DELETE|DELETE/CONFIRM} [nodes,...]The first parameter is the function to perform:
CHECK -- Verify the UMP profiles against the SYSUAF and report usernames which are invalid, disusered or dismailed. DELETE -- Unconditionally deletes local usernames which are invalid, disusered or dismailed. DELETE/
CONFIRM-- Same as DELETE but prompts whether each username should be deleted or not.
Note
The function must be specified exactly as shown above without abbreviation and there may not be spaces between DELETE and /CONFIRM.The second parameter indicates the node names of the users to be validated against the current SYSUAF. By default, the node names used are the current values of the SYS$NODE and SYS$CLUSTER_NODE logicals.
12.16 UMP_LOGIN - To Prompt Users to Enter Profiles During Login (Optional)
UMP_LOGIN.COM may be run during login to determine if the user has ever modified their own profile. If they have not entered their profile, UMP_LOGIN will ask them if they would like to do so immediately and place them in the UMP profile.You may invoke UMP_LOGIN.COM at any point during login when appropriate for your users. For example, SYLOGIN or other procedure appropriate for your system. If you want UMP_LOGIN to be invoked automatically by OECN_LOGIN, you may create a file in OECN$CUSTOM called OECN_LOGIN_EPILOGUE.COM and execute OECN$:UMP_LOGIN from there.
If you use UMP_LOGIN.COM you may wish to use the VMS INSTALL utility to install OECN$:UMPMODIFIED.EXE as a known image to speed up the login process.
12.17 UMPID2DIS - Creating Distribution Lists from VMS Identifiers (Optional)
UMPID2DIS.EXE is an optional utility which builds PMDF style distribution lists containing all users who hold a specified identifier. This may be used by sites who wish to build distribution lists for all users of a given package. These distribution lists are not standard OECN-wide lists.
UMPID2DIS will only work correctly on your system if your UIC's are unique. That is, each user (holder of an identifier) has their own unique UIC. If two users hold the same UIC identifier, only one of them will be output to the lists.
To create a distribution list for users holding a given identifier, use the following commands:
$ ID2DIS :== $OECN$:UMPID2DIS
$ ID2DIS {identifier},... {distribution_list_file}where "identifier" is the identifier. If you specify an OECN_ identifier, users who hold the standard identifier or the _RO and _GM variants will be included in the list. You may specify multiple identifiers separated by commas (no spaces). If a user holds more than one of the identifiers, they will only be included on the list once.
"distribution_list_file" is the filename to contain the distribution list. If a device and extention are not included, the default is OECN$UMP:.DIS.Only users that meet the following criteria will be output to the list:
1) The user holds one or more of the specified identifiers. 2) The UAF flags DISUSER and DISMAIL are not set. 3) The username has a valid UMP profile. Note that UMPID2DIS does NOT create the PMDF alias to point to the distribution list. If aliases are desired for the list you must use PMDF CRDB or PMDF DB to create the PMDF aliases.
For example, NWOCA could use the following commands to create a distribution list for all NWOCA USPS users:
$ ID2DIS := $OECN$:UMPID2DIS
$
$ ID2DIS OECN_USPS NWOCA_USPS
$
$ PMDF DB
open pmdf_alias_database
override on
add "nwoca_usps" "nwoca_usps-list@reprocess.nwoca.org"
add "nwoca_usps-list" "<oecn$ump:nwoca_usps.dis,*,*,postmaster,*, USPS"
$ EXIT12.18 Example Procedure for Periodic Rebuilds
Periodically, each site should run EXPORT_LISTS.COM to update the distribution lists from the UMP data. Most likely you will want to run EXPORT_LISTS nightly. You should also run it anytime that you recreate your PMDF alias database from scratch or make significant modifications to the UMP profiles.
If you have PMDF's directory channel configured, you should run EXPORT_DD.COM and build a new directory daemon database. You may also to use UMPID2DIS to create distribution lists based on VMS identifiers.
You will most likely want to write a DCL command procedure to execute all of the appropriate steps in a single batch job, and then schedule it with DECscheduler. Attached is a sample of such a procedure which is currently in use at NWOCA. You may wish to use this as a starting point for your own procedure.
$!+ $! NWOCA_EXPORT_UMP.COM $! $! This procedure run the UMP routines to export distribution list, build $! aliases, etc. $! $! - $! $ SET PROC/PRIV=(BYPASS,SYSPRV,SYSNAM,SYSLCK) $ SET VERIFY $ SET DEFAULT OECN$UMP $!+ $! Temporarily suspend mail processing while lists are being $! created and datbases rebuilt. $!- $ STOP/QUEUE/NEXT MAIL$BATCH $!+ $! Export distribution lists and rebuild PMDF databases. $!- $ @OECN$:EXPORT_LISTS "REBUILD,USER,DEFER" STAFFR $ ! $ ! Merge aliases for mail addressed to former MAVCA users. $ ! May be removed after MAVCA.OHIO.GOV goes away. $ ! $ pmdf crdb /long/nofast/nodup/strip OECN$UMP:MAVCA_ALIASES.DAT oecn$ump:aliases.dat $ $!+ $! Create directory daemon text file. $!- $ @OECN$:EXPORT_DD $!+ $! Build new directory daemon database. Build into a temp file in case $! someone attempts to use database while in progress. $!- $ pmdf crdb/duplicate/stat oecn$ump:directory_daemon.txt - oecn$ump:directory_daemon.tmp $ copy oecn$ump:directory_daemon.tmp - pmdf_root:[directories]PO$NWOCA$ORG.DAT $ set prot=w:re pmdf_root:[directories]PO$NWOCA$ORG.DAT $ purge pmdf_root:[directories]PO$NWOCA$ORG.DAT $ delete/nolog oecn$ump:directory_daemon.tmp;* $! $! Build distribution list based on VMS identifiers $! $ ID2DIS := $OECN$:UMPID2DIS $ $ ID2DIS OECN_USPS,OECN_SYSMAN NWOCA_USPS NM_USPS.DIS $ ID2DIS OECN_PPS,OECN_SYSMAN NWOCA_PPS NM_PPS.DIS $ ID2DIS OECN_USAS,OECN_SYSMAN NWOCA_USAS NM_USAS.DIS $ ID2DIS OECN_EMIS,OECN_EMIS_STU,OECN_EMIS_STF,OECN_EMIS_SFU,OECN_EMIS_GEN,OECN_EMIS_FIN,OECN_SYSMAN NWOCA_EMIS NM_EMIS_USERS.DIS $ ID2DIS OECN_EIS,OECN_SYSMAN NWOCA_EIS NM_EIS.DIS $ ID2DIS OECN_VIS,OECN_SYSMAN NWOCA_VIS NM_VIS.DIS $ ID2DIS OECN_SECIMS,OECN_SYSMAN NWOCA_SECIMS NM_SECIMS.DIS $ ID2DIS NWOCA_INFOHIO NWOCA_INFOHIO NM_INFOHIO.DIS $ COPY OECN$UMP:nm_*.dis/sinc NM:/PROT=W:R $ $! Create aliases for NWOCA's identifier lists $ PMDF DB open oecn$ump:aliases.dat override on add "mail_hs_counselors" "mail_counselor_sec" add "nwoca_usps" "nwoca_usps-list@reprocess.nwoca.org" add "nwoca_usps-list" "<oecn$ump:nwoca_usps.dis,*,*,postmaster,*, USPS" add "nwoca_PPS" "nwoca_PPS-list@reprocess.nwoca.org" add "nwoca_PPS-list" "<oecn$ump:nwoca_PPS.dis,*,*,postmaster,*, PPS" add "nwoca_USAS" "nwoca_USAS-list@reprocess.nwoca.org" add "nwoca_USAS-list" "<oecn$ump:nwoca_USAS.dis,*,*,postmaster,*, USAS" add "nwoca_EMIS" "nwoca_EMIS-list@reprocess.nwoca.org" add "nwoca_EMIS-list" "<oecn$ump:nwoca_EMIS.dis,*,*,postmaster,*, EMIS" add "nwoca_EIS" "nwoca_EIS-list@reprocess.nwoca.org" add "nwoca_EIS-list" "<oecn$ump:nwoca_EIS.dis,*,*,postmaster,*, EIS" add "nwoca_VIS" "nwoca_VIS-list@reprocess.nwoca.org" add "nwoca_VIS-list" "<oecn$ump:nwoca_VIS.dis,*,*,postmaster,*, VIS" add "nwoca_SECIMS" "nwoca_SECIMS-list@reprocess.nwoca.org" add "nwoca_SECIMS-list" "<oecn$ump:nwoca_SECIMS.dis,*,*,postmaster,*, SECIMS" add "nwoca_INFOHIO" "nwoca_INFOHIO-list@reprocess.nwoca.org" add "nwoca_INFOHIO-list" "<oecn$ump:nwoca_INFOHIO.dis,*,*,postmaster,*, INFOhio" $ $!+ $! Create VMS Mail forwarding addresses for same aliases $!- $ mail := mail $ mail set forward/user=nwoca_usps in%nwoca_usps set forward/user=nwoca_pps in%nwoca_pps set forward/user=nwoca_usas in%nwoca_usas set forward/user=nwoca_emis in%nwoca_emis set forward/user=nwoca_eis in%nwoca_eis set forward/user=nwoca_vis in%nwoca_vis set forward/user=nwoca_secims in%nwoca_secims set forward/user=nwoca_infohio in%nwoca_infohio $ $ $!+ $! Create a MAIL_ALL distribution list. Will contain all user profiles $! which are subscribed to one or more distribution list (non-duplicated $! addresses). $!- $ delete /nolog/noconfirm mail_all.*;* $ append mail_*.dis/sinc mail_all.tmp/new $ sort/nodupli mail_all.tmp mail_all.dis $ set prot=w:r mail_all.dis;* $ $ PMDF DB open oecn$ump:aliases.dat override on add "mail_all" "mail_all-list@reprocess.nwoca.org" add "mail_all-list" "<oecn$ump:mail_all.dis,*,*,postmaster,*, All NWOCA users" $ mail := mail $ mail set forward/user=mail_all in%mail_all $ $ purge oecn$ump:*.* $ $!+ $! All local aliases have been added to databases. $! Place the new databases back into PMDF production $! directory. $!- $ copy/nolog oecn$ump:aliases.dat PMDF_ALIAS_DATABASE $ set file pmdf_alias_database/prot=w:re $ purge/keep=3/nolog pmdf_alias_database $ $ copy/nolog oecn$ump:reverse.dat PMDF_REVERSE_DATABASE $ set file pmdf_reverse_database/prot=w:re $ purge/keep=3/nolog pmdf_reverse_database $ $!+ $! All done. Restart dispatcher to ensure services open $! the fresh databases. $ PMDF RESTART DISPATCHER $ START/QUEUE MAIL$BATCH $ $ EXIT
12.19 Multiple Non-Clustered Systems
DAS's with a single VMS system, or a single VMS cluster, need not be concerned with this section.The UMP system is currently designed assuming that each A-site will have a single set of UMP files regardless of how many independent (non-VMSclustered) systems. This provides a single point of adminstration for DAS personnel and makes building the PMDF distribution lists and aliases easier. At present, there are no plans to implement multiple UMP files on multiple systems while still being able to produce a single set of distribution lists for the entire DAS. This may be added in the future if a well defined need arises.
However, it would be useful if remote users could modify their own user profiles without having to log into the system which contains the UMP files. This section describes a secure way of providing remote users access to their own UMP profiles.
Use the following procedure to establish remote access to the UMP system.
- Choose a system to contain the UMP files. This would normally be your cluster or the system primarily responsible for mail delivery. This will be called the "server" system.
- Put UMP on the server normally as described in the "Setup" section. Users on this system will use the UMP program directly from this system.
- Create a username on the server called UMP_SERVER. This should be non-prived, network-only access. The login directory for this account can be the OECN$UMP directory, or it can have a separate login directory.
- On the server define the OECN$UMP logical as normal.
- On the server use AUTHORIZE to define network proxies into the server for each remote system. For example:
UAF> ADD/PROXY node::* UMP_SERVER
Where "node" is the DECnet node name of the remote node.
This will give any user on one of your non-server nodes proxy access to the UMP_SERVER.- On each node (client) that you want to have access to the server, define OECN$UMP as follows (assuming MAIN:: is the server):
$ DEFINE OECN$UMP "MAIN""UMP_SERVER""::OECN$UMP:"
Also, copy the UMP.EXE file to the OECN$: directory on the client node. Set up the users to run the local copy of the .EXE.- Copy the *.INI files from the server to the client system. and define the following logicals:
$ DEFINE OECN$UMP_STANDARD dev:[dir]OECN$UMP_STANDARD.INI
$ DEFINE OECN$UMP_LOCAL dev:[dir]OECN$UMP_LOCAL.INI
Modify the OECN$UMP_LOCAL.INI file to contain the local system's DECnet node name and internet host. This will ensure that each user's profile is built using the local system's node names.If you do the above, each node will appear to have local access to the UMP files, and you will end up with a central DAS-wide database to build your distribution lists from. The server node will be the only one that needs to run the EXPORT_LISTS.COM to produce the mail_ and oecn_ for your DAS.
12.20 Programming Considerations
DAS programmers may wish to use DTR, COBOL or other high level language to query or manipulate the UMP data files. This section contains a brief description of the UMP data files and special considerations. DTR and COBOL definitions are provided with the software release for this purpose. The COBOL definitions are contained in UMPDAT.LIB and UMDDAT.LIB in OECN$LIB. The DTR definitions are in the domains OECN$CDD_OECN.UMP_HEADER and OECN$CDD_OECN.UMP_DIST. OECN$CDD_UMP.UMPS is a view which joins the header and distribution list code.
The UMP data is stored in two files in OECN$UMP:
UMPDAT.IDX Contains profile information. Keys:
- Primary: Group + Username
- Secondary: Username (no duplicates)
- Secondary: Alias (no duplicates)
UMDDAT.IDX Contains the distribution lists the user is subscribed to. Each record represents a single distribution list assignment. The distribution lists are stored as a code value defined by the OECN$UMP_STANDARD.INI or OECN$UMP_LOCAL.INI files. Primary key: Username + Distribution_list_code 12.20.1 Field Requirements
Some fields in UMP may display to the user differently than is physically stored in the file. Other fields have specific requirements. Please note the following:
- The ALIAS field must always contain a value. If the user does not have a specific alias, then the ALIAS must be set equal to the USERNAME field.
- A number of fields are calculated by UMP as needed and may or may not be stored physically in the field. For example, if the ORGANIZATION field is blank, but the DISTRICT_IRN is not, then UMP will calculate the ORGANIZATION name using the OEDS file. However, UMP will not necessarily store the calculated value. If you are developing programs which depend on these values being stored on the file, you may run UMPUPDATE.EXE prior to your program. UMPUPDATE will calculate the files and store them on the file.
- Distribution list codes are always stored in internal format (ttxxxx) as defined by the INI files. In order to manipulate distribution codes, you must know the lists internal value.
- The LAST_UPDATE field is a VMS quadword date.
- MODIFIED_FLAG contains "Y" if the user has modified their own profile. Any other value indicates the profile is new and has not been modified by the user.
Chapter 13
VFC2PDF - Converting Text Files to PDF FormatVFC2PDF converts VFC or plain text files into PDF (Portable Document Format) files. After a report is converted to PDF format, it can be transferred to a PC or a MAC. It can also be viewed or printed using the Adobe Acrobat viewer. By using this utility, it becomes much easier to publish documents on public Internet web sites, CDrom, etc.
accessing the program
The program may be executed by typing:
Menu>VFC2PDFat the Menu or from the $ prompt by typing:
$ VFC2PDF/[qual 1]/.../[qual n] {input_file} [output_file])By executing from the Menu, you have no control over the default formatting options.
By executing from the $ prompt, you can control the output, including the use of wildcards. By default, VFC2PDF will attempt to choose appropriate orientation, font sizes and margins based on the record length of the input file. However, these values may be controlled by using qualifiers as given below.
Note
A foreign command must be defined for VFC2PDF, such as:
($ VFC2PDF :== $OECN$:VFC2PDF).Syntax
VFC2PDF {input_file} [output_file] /ORIENTATION={PORTAIT|LANDSCAPE} /FONT_SIZE={points} /FONT_STYLE=([NORMAL],[BOLD],[ITALIC]) /VERTICAL_SPACING={points} /TOP_MARGIN={points} /LEFT_MARGIN={points} /LOG /PAGE_LENGTH={max_lines_per_page} /LINE_WIDTH={characters_per_line} (defaults to record size) /INFORMATION=([AUTHOR="author"], [CREATOR="creator (defaults to username)"], [TITLE="title (defaults to filename)"], [SUBJECT="subject"]) /[NO]COMPRESSDefaults
PORTRAIT: /FONT_SIZE=11 /VERTICAL_SPACING=11 /LEFT_MARGIN=45 /PAGE_LENGTH=66 LANDSCAPE: /FONT_SIZE=9 /VERTICAL_SPACING=9 /LEFT_MARGIN=30 /PAGE_LENGTH=66 If /LINE_WIDTH is greater than 132: /FONT_SIZE=7 /VERTICAL_SPACING=9 /LEFT_MARGIN=30Notes
- Wildcards are supported in the input specification. If wildcards are used, the output_file may be omitted or must not include a file name. Output files will be written to the default directory unless the second parameter contains an output directory. - All qualifiers are optional. If /ORIENTATION is omitted, then it will be selected automatically based on the record length of the input file. Line lengths over 80 characters will be printed in LANDSCAPE, otherwise PORTRAIT will be used. Note: Record size determination is based on the MRS (Maximum Record Size) in the RMS header. For formats where MRS is not set, VFC2PDF will assume 80 characters.transfer options
There are several methods available to transfer the PDF formated file to a PC or MAC.
One method is to use some FTP utility.
Another procedure, which seems to work well in Netscape, is to specify an FTP URL as:
ftp://username@host.org/Netscape will prompt you for a password and connect with an authenticated FTP.
A second simple method is to mail the file(s) to yourself as follows:
EMAIL>send/file/noedit/nocc/subj="PDF Files" filename.pdfor for multiple PDF files:
EMAIL>send/file/noedit/nocc/subj="PDF Files" *.pdfFor the above, "noedit" means No Edit feature, and "nocc" means No Carbon Copy desired.
Once the files are sent, the user can open the message with their browser, or WEB-Mail, or some other client, and then save it to their desktop or print from there.
Contents