Ohio Educational Computer Network System (OECN)

System Manager Manual

Revision/Update Information: May, 2001

Copyright ©1992, 1995 Ohio Department of Education

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:

• User may access an item by its item number or label.
• Abbreviations are allowed on the current menu.
• Aliases are supplied for all items. The user may enter the label name for any item on any menu in the current menu system.
• Help may be obtained for the current menu via the VMS Help utility.
• Users will only see the items on the menu that they are authorized to access.

Features for the system manager:

• May be used for CAPTIVE user accounts.
• Menus or items may be easily added or removed.
• Access to items and menus may be controlled with the standard OECN_xxxx VMS security identifiers.
• The OSA utility may be used to customize security.
• A menu system may consist of multiple menu files. This allows individual A-sites to add custom menus without modifying the menus included in the distribution.
• By default, does not spawn a subprocess when executing a command. All commands execute in the current process. This prevents the excessive overhead associated with repeatedly spawning subprocesses.
• Optionally, spawns most commands in a subprocess. Spawning commands may increase response time for larger VAX processors. This may be configured by the system manager.
• May be used from batch if the third parameter to the OECN_MENU procedure is used.
• Optional timeout feature that automatically exits the menu system if the user remains inactive for a specified period.

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.

Table 2-1 Menu System Terms

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.

2.2 How Menu Files Create a 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.

2.4 The Alias 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:

1. Users must have a PRCLM Authorize quota of at least 1. If the user executes programs that also spawn processes (e.g., TPU/EVE, WPS) they may need a higher PRCLM quota.
2. Other user quotas also may need to be increased in order for the main and subprocess to have access to sufficient resources.
3. BALCSETCNT (balance set count) in SYSGEN must be large enough to handle the addition processes.
4. Some types of options must be executed in the main process (see below).

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.

Several steps are required in order to implement the Menu Processor on your system. The steps are briefly outlined below, detailed explanations follow:

1. Install the OECN, MENU and HELP distribution packages with OECN_INSTALL.
2. Establish the necessary OECN logicals.
3. Move the menu files and VMS Help libraries from the distribution directories to the appropriate directories on your system.
4. Create the OECN_MENU symbol.
5. Use the VMS Install utility to make the Menu Processor a known, shared image.

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.

Table 3-1 Menu Logicals

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.

Table 3-2 Behavior Options

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"

3.3 Move Files to Appropriate Directories

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.

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.

Table 5-1 Menu Record Types

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.

Table 5-2 MENUEDT Main Menu Options

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.

5.1.1 Menu File Record Types

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

Table 5-3 File Header Record Fields

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.

5.1.3 Menu Header Record

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

Table 5-4 Menu Header Fields

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. A Heading contains both the file description and the menu description. B Heading contains only the menu heading description.
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.

5.1.4 Menu Item Record

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.

Table 5-5 Menu Item Types

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

Table 5-6 Menu Item Fields

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: D DCL command DP DCL in Parent process P Program to be executed M Menu item T Text Item
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:

MAIL
@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:

• Commands that change security identifiers
• Commands that modify menu logicals or modes
• Commands that spawn subprocesses with the /NOWAIT qualifier

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.

1. If a menu item has no security specified for it, then security will be inherited from the menu header record to which the item belongs.
2. If a menu header has no security, then it will inherit its security from its parent's menu header record. This occurs until a parent record is found that contains security information, or the top-level menu is found within the current menu file.
3. The top-level menu of each menu file, will inherit security from the file header record.
4. If no security is specified, after rule #3 above, then there is no security required to access the menu element.

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.

Table 5-7 Security Access Levels

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:

1. Build the Alias File
2. Simulated Menu Listing
3. Detailed Menu Report
4. Hierarchical Menu Listing

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.

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.

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.

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.

Following is the recommend procedure for modifying one or more menu files.

1. Redefine the OECN$MENU$FILES to be a search list.
2. Modify the Menu Files
3. Build a New Alias File
4. Redefine OECN$MENU$FILES permanently

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.

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.

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:

• P1 - Name of the text file to be mailed.
• P2 - VMS mail address the text file will be sent to.
• P3 - Text that is to be displayed on the Subject Line of the message.
• P4 - Y/N (yes/no) flag that indicates whether or not to delete the text file containing the message after it is sent.

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. $!-

8.2.1 Customizing OECN VIEW

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

8.2.2 Creating a DCL Command

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:

• OECN$KEYMAP_EXCURSIONS.INI
• OECN$KEYMAP_PERSONA.INI
• OECN$KEYMAP_REFLECTIONS_MAC.INI
• OECN$KEYMAP_REFLECTIONS_PC.INI

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:

1. To provide a single location for all configuration information.
2. To provide a means for processes to establish a default context during login.
3. To provide a means for users to change contexts using an interactive (or DCL) interface.
4. To allow DAS personnel the ability to switch to any context using the same rules as a user's process.
5. To provide compatibility with BUNNY, FROG, and USE to make the transisition to the new utility easier.
6. To provide DCL and API interfaces which allow other utilities the ability to find and establish contexts.
7. To provide support for common OpenVMS configuration methods in use by DA Sites, including group tables and shared logical tables.

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:

• DISTRICT
• BUILDING
• LIBRARY
• OTHER

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.

11.2.2 DCL Command Syntax

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]

• ENTRY_CODE indicates the entry(s) to be selected from the OECN$SETUP.INI file. The INI file indicates the environment to be established for each entry. Multiple entries may be set by enclosing the entry codes in quotes separated by commas. When setting multiple entries, the first entry is considered to be the primary entry.
• /MENU indicates the user should be presented a menu to select an entry based on their process security. /MENU is the default for interactive processes when there are no other qualifiers and no parameter specified.
• /RESET attempts to reset the current process to it's original state. Any "reset" entries existing on the INI file are used to determine which logicals should be reset. If there are no reset entries on the INI file, the LNM$FILE_DEV logical will be the only one returned to it's original state.
• /LOGIN instructs SETUPENV to attempt to determine the user's default login context. If a specific entry code(s) is specified with /LOGIN, the specified entry will override the defaults. The following flags may be included to control how SETUPENV/LOGIN determines the default entries:
  • SIS searches the process' rightslist for identifiers in the format SIS_x. For the first such identifier "x" is used as the default entry.
  • INFOHIO searches the process' rightslist for identifiers in the format INFOHIO_x. For the first such identifier "x" is used as the default entry. In order to avoid potential conflicts with SIS entry codes, SETUPENV will first look for an entry named "x_LIB". If and x_LIB entry is found, it will be used as the default InfOhio entry, otherwise just "x" will be used.
  • BY_ACCESS indicates that SETUPENV should determine the user's default entry by checking security access to the entries. SETUPENV will scan OECN$SETUP file and find the first entry of each type (DISTRICT, BUILDING, LIBRARY, OTHER) to which the user has access making this the default. BY_ACCESS should only be used by DA Sites who have carefully placed proper identifiers on entries to allow access to appropriate users.
  • USERNAME=n uses the first "n" characters of the username as the entry code. This is useful for sites who use a username prefix to indicate districts and who have set up matching entry codes in the OECN$SETUP file.
  
  SETUPENV/LOGIN will also (unconditionally) search for an identifier called "SETUPENV_xxx". If the user has such an identifier, then it is always used as the default entry, superceding the default provided by the above flags. This serves as a means to provide a specific default for users who may have access to multiple entries.

  Note 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.

• /NEXT indicates that the next entry should be selected based on the current or specified entry. If an entry is specified as a parameter, then the entry selected will be the one immediately following it. Otherwise, the values of the OECN$SETUP_CURRENT_* logicals are used to determine the current entry. The primary purpose of /NEXT is to allow DCL procedures to process all or selected entries sequentially.

  Note 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.

• /TYPE may be used in conjunction with /NEXT or /MENU to determine the type of entry that may be considered. For example, if /TYPE=DISTRICT is specified with /NEXT, then only district entries will be considered. The default for /NEXT is DISTRICT. The default for /MENU is ALL.
• /CATEGORIES may be used with /NEXT or /MENU to select only entries where the CATEGORIES attribute matches the specified wildcard.
• /APPLICATION may be used with /NEXT to select only entries containing the specified application. Only one application may be specified and it must exactly match an application specified on the entries APPLICATION attribute.
• /[NO]PROMPT causes the user's DCL prompt and OECN Menu prompt to be set to a value representing the entry(s) selected. /NOPROMPT is the default.
• /LOG indicates an informational message should be displayed indicating the entry selected. If multiple entries are set as a result of the command, only the primary entry is displayed.
• /ARCHIVE[=archive_code] indicates which archive is to be selected. If a specific archive is provided and it exists for the entry, then the logical and table definitions for the archive will be set. If no archive is specified, then the first archive for the selected entry will be used. If /ARCHIVE is specifed with /MENU, the archvives will be presented to the user as seperate choices on the menu.
• /RESTRICT_IRNS determines if SETUPENV should attempt to define the OECN$EMIS_RESTRICT_IRNS logical. This logical is set by checking all the entries which have a relationship (parent, child, or sibling) based on the PARENT attributes. For each such entry, the users access to the entries is checked (based on the IDENTIFIER attributes). If the user has access to the entry, then the IRN of the entry is added to the OECN$EMIS_RESTRIC_IRNS logical.
• /PRINT attempts to determine the user's default printer using a convention from NOACSC. The "owner" field for the current user is retrieved from SYSUAF. If the owner field contains a slash (/) the characters after the slash are tested to see if it contains a valid queue name. If not, "$PRINT" is appended to the string from the owner field and is again tested as a queue. If either value translates to a valid queue name (other than SYS$PRINT), then SYS$PRINT is defined as a logical to point to the queue. The OECN_PRT symbol is also defined to print to the queue.
• /EMIS places SETUPENV in "EMIS" mode. In this mode, SETUPENV simulates the behavior of EMIS_SELECT.COM. The OECN$EMIS_DBS file is read and handled in the same manner as EMIS_SELECT. In this mode, the meaning of the "entry code" parameter is the DBS code of the EMIS database, instead of a SETUPENV entry code. The following qualifiers are valid with /EMIS:
  • /NEXT
  • /RESET
  • /MENU
  • /CATEGORIES
  • /LOG
  
  See the "EMIS_SELECT Compatibility" section for more information.
• /USE, /BUNNY, /FROG provide compatibility with the corresponding NOACSC's utilities. When one of these qualifiers is specified, the utility accepts the corresponding utilitie's qualifiers and converts them to the nearest SETUPENV equivalent. See the "NOACSC Compatibility" section for more information.

Usage Notes

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:

• OECN$SETUP_CURRENT_DISTRICT
• OECN$SETUP_CURRENT_BUILDING
• OECN$SETUP_CURRENT_LIBRARY
• OECN$SETUP_CURRENT_OTHER

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:

• OECN$SETUP_PARENT---Contains the PARENT entry for the current entry
• OECN$SETUP_CHILDREN---Contains a list, separated by commas, of the children for the current entry. That is, a list of entries which contain a PARENT pointing to the current entry.
• OECN$SETUP_SIBLINGS---Contains a list, separated by commas, of "siblings" (excluding the current entry). That is, a list of entries that share the same parent entry.

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:

• SECTION={entity_code}
  The SECTION statement begins a new entity definition. The entity code may be up to 12 alphanumeric digits. This is the code used to select the entry and is seen on the menu. This code must uniquely identify each entity regardless of type (i.e. You must not specify a district and building entity with the same code).
• DESCRIPTION="text"
  Text description for menu
• TYPE={DISTRICT|BUILDING|LIBRARY|OTHER}
  Indicates the type of entity. If TYPE is not specified, the default is DISTRICT. A user can have context in each of these types at one time.
• CATEGORIES="string"
  An unformatted string that may further define the entry. Except where otherwise indicated, the categories are site defined. It might be used as flags to indicate processes that may be run against the entry. Entries may be selected by category using the /CATEGORIES qualifer. The categories for each selected type is also returned to DCL via the OECN$SETUP_CURRENT_* logicals.
• APPLICATIONS={app}[,...]
  List of applications used by the entry. Each application is a site defined code of up to 10 characters. Five applications may be specified on each APPLICATIONS line. Multiple APPLICATIONS lines may be specified if needed.
  Note: Although the applications are site defined, the SSDT and other software providers may require specific application codes. It is recommended that you use these codes for established applications:

  USPS
  USAS
  EMIS
  EIS
  VIS
  SIS (McSIS)
  INFOHIO

• IRN={irn}
  Optional IRN for the entry. Returned to DCL via the OECN$SETUP_CURRENT logical and optionally used in the OECN$EMIS_RESTRICT_IRNS logical.
• PROMPT="prompt string"
  Optionally specifies the prompt string to be used if this entry is selected. This value overrides the default prompt. The default prompt is the list of entry codes currently selected.
• ARCHIVE={archive_code},[description],[table]...
  Declares this entity to have an "archive". Archives can be selected using the /ARCHIVE qualifier. If a code is specified on the /ARCHIVE qualifier, then the corresponding archive items are also processed when the entry is selected. When /ARCHIVE is used with /MENU, then the archive definitions are listed on the menu as separate items which the user can select.
  The optional table parameter indicates additional table(s) which should be placed in the LNM$FILE_DEV search path. If specified, they will be placed on the path before the other shared tables (TABLE and GROUP_TABLE). This permits definitions for archive logicals to be placed in special shared logical tables for use as an archive.
  A multiple ARCHIVE attributes might be included for each fiscal year, or it may be a generic archive setting which requires an additional step (outside of SETUPENV) to complete establishing the archive environment. The usefulness of this attribute depends largely on how the DAS currently has archives defined and whether/how they are user selectable.
• LOGICAL={logical_name[@archive_code]}[,CONCEALED] [,IF_EXISTS],[values]...
  Specifies a process logical to define. Multiple values may be included to define a search list. If a logical name is specified without any values, then the logical will be deassigned.
  If the CONCEALED keyword is included, then the logical will be concealed.
  Conditional Logicals
  The IF_EXISTS keyword causes the logical to be defined conditionally based on the presence of the file specified in the value. The logical will only be created if the file specified in the first value exists. In this case, the value should contain a complete filespec. For example an EMIS entry might specify:

  LOGICAL=OECN$EMIS_STU_SEARCH,IF_EXISTS,OECN$EMIS$DTA:EMSALT.IDX LOGICAL=OECN$EMIS$DTA,CONCEALED,EMIS_ROOT:[LIVE]

  
  In this case, OECN$EMIS_STU_SEARCH will only be defined if the OECN$EMIS$DTA:EMSALT.IDX file exists.

  Note 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.

  
  Archive Logicals
  If an optional archive code is included after the logical name (by specifying the archive code after an "@") then the logical will only be defined if the corresponding ARCHIVE code is selected (via the /ARCHIVE qualifier or the menu). Logicals which contain the archive code will be processed after any normal logicals and therefore will supercede any previous definition of the same logical.
  The archive code on each logical should match an archive code specified in an ARCHIVE attribute. The ARCHIVE attribute will provide the description for the menu when the archive is displayed.
• SYMBOL={symbol_name}[,symbol_value]
  Sets a global symbol. If a value is not specified, then the symbol is deleted. Note: The symbol and value must be made up of printable characters. Non-printable values may not be included (in the current version of SETUPENV).
• PARENT={entry}
  Indicates a parent entry of this entry. Parent entries may be nested (i.e. parents of an entry may themselves have a parent). This facility allows multiple entries to share another entry as a parent. For example, if all buildings share the district definition of EMIS_ROOT, then EMIS_ROOT can be defined in the district entry and each building specify the district as PARENT.
  When the user selects an entry which contains the PARENT attribute, then settings for the parent will be set prior to the logicals for the selected entry. Therefore, selecting a building entry will also automatically select the corresponding district (parent) entry.
• GROUP_TABLE={octal_group_number}
  Specifies this entry uses a GROUP logical name table for some of it's logical definitions. This setting only applies if someone outside the group attempts to set this entry. If so, the entry's group table will be added to the process' LNM$FILE_DEV path. Otherwise, if the user is in the specified group, it's assumed that the default definition of LNM$FILE_DEV already includes LNM$GROUP.
• TABLE={logical_name_table},...
  Indicates that this entry uses a sharable logical name table(s) (other than a group table) for some of its logicals. When this entry is selected, the logical table will be added to the processes LNM$FILE_DEV logical path. Up to four tables may be specified.
• IDENTIFIER={ident_specification}
  Indicates an ACE entry used to control access to the entry. This is used when /MENU is specified to control which entries the user is allowed to see. It is also used when determining which entry to select as default when /LOGIN=BY_ACCESS is specified.
  The format of the identifier specification is the same as the "IDENTIFIER=" portion of a standard identifier ACE entry. If the specification includes a comma then the specification must be enclosed in quotes. Multiple IDENTIFIER lines may be included for an entry. If so, standard ACL processing applies for determining access. Examples:

  IDENTIFIER="[101,*]"
  IDENTIFIER=SIS_BLDA
  IDENTIFIER="OECN_USAS+ARCHBOLD_FISCAL"

  Note 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:

• $RESET_DISTRICT
• $RESET_BUILDING
• $RESET_LIBRARY
• $RESET_OTHER

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.

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.

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.

Table 11-1 wide

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

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.

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.

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.

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

Notable Differences:

• The USE default for /ARCHIVE is provided by the .CLD file (which is changed annually to provide a new default). SETUPENV's default is the first ARCHIVE for the entry. Therefore, to remain compatible with USE, archives should be placed with the most recent year first in the entry's section.
• USE determines which logicals to set based on the security identfiers held by the user (e.g. OECN$EIS$DTA is only set if OECN_EIS is held). SETUPENV sets all logicals specified for the entry regardless of security identifiers.
• SETUPENV does not set PMDF_SIGNATURE. Sites depending on this should add the following line to SYLOGIN:

  $ 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.

Notable Differences:

• SETUPENV does not define the ESC, PROFF or T80. These symbols cannot be placed in the OECN$SETUP SYMBOL attributes because they contain non-printable characters (not supported). Therefore, these symbols must be placed in a SYLOGIN procedure.
• /CURRENT_BUILDING is not supported. SETUPENV does not have ability to set an entry based on the value of an existing logical.
• If /ARCHIVE is specified without a value, the default is the first ARCHIVE attribute for the selected entry.

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

Notable Differences:

• /PRINTER behaves the same as SETUPENV's /PRINT qualifier, except that /FROG/PRINTER attempts to find a queue named entry$PRINT where "entry" is the selected entry. If found, entry$PRINT is assigned to SYS$PRINT. If the user has a queue definition in their SYSUAF Owner field, it overrides the entry$PRINT queue.
• For non-DAS staff, SYS$PRINT is unconditionally assigned to LCL$PRINT as a job logical (which might be occluded).
• SETUPENV/FROG does not attempt to define the large number of symbols created by FROG. These should either be placed in an $APP_INFOHIO entry, or moved to a global login procedure. Symbols containing non-printable characters (e.g. CLEAR) must be moved to a global procedure.

11.7 OECN$SETUPENV API

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).

11.7.2 COBOL Call Arguments

      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. 

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-FLAGS

List 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-ARCHIVE

Contains 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:

1. Does not simulate /USE, /BUNNY or /FROG behaviors. Those qualifiers are handled by the SETUPENV utility and are not exposed to the callable interface.
2. Does not modify the Menu or DCL prompts (a string is returned for setting the prompt if desired).
3. 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).
4. Does not implement the function of /PRINTER

---

Chapter 12
Installing and Using UMP - User Mail Profile System

12.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$:UMP

at the $ prompt or from the menu system, type:

Menu>UMP

The 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:

1. 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.
2. Use OECN_INSTALL and INSTALL PACKAGE as usual to install the OECN package.
3. 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.
4. 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_LISTS

If using PMDF style lists created by SWOCA's PUBDOM OECNMAIL utilities, then use:
$ @OECN$:IMPORT_PMDF_LISTS

Then 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:

1. 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.
2. Set ALLOW_USER_ALIAS to YES in OECN$UMP_LOCAL.INI. This flag enables the 'Alias' and 'From' fields in UMP.
3. 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-CCCCCC

Where 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_JOKES

This 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-STF

This 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-STFEMS

Note 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_CODE

Example 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_CLERK

In 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-STFJOK

Then 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.domain

See 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:

1. 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.
2. 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"
$ EXIT

12.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.

1. 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.
2. 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.
3. 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.
4. On the server define the OECN$UMP logical as normal.
5. 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.
6. 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.
7. 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 Format

VFC2PDF 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>VFC2PDF

at 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]COMPRESS

Defaults

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=30

Notes

- 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.pdf

or for multiple PDF files:

EMAIL>send/file/noedit/nocc/subj="PDF Files" *.pdf

For 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