Mercurial > public > html2wiki
diff test/resources/sysman_handbook.html @ 2:5da2e67620f9
Upgrade to Ivy configuration and begin clean up of tests. Added FreeBSD license.
| author | smith@nwoca.org |
|---|---|
| date | Tue, 25 Jan 2011 17:06:57 -0500 |
| parents | |
| children | 22ed6d93442c |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/test/resources/sysman_handbook.html Tue Jan 25 17:06:57 2011 -0500 @@ -0,0 +1,7039 @@ +<html> +<a name="first_page"></a> + +<!-- This file created using DECdocument Version V3.3h on 25-JAN-2011 16:09:07.97 --> +<!-- TAG definitions version: V3.3h --> +<!-- The SDML doctype is: SOFTWARE.REFERENCE --> +<!-- The output destination was: HTML --> +<!-- SDML file is: NWB:[SMITH.DEV.SDML]OECN10_SYSMAN_HANDBOOK.SDML --> + +<body> +<head> +<title>Ohio Educational Computer Network System (OECN)</title> +<style> +A:hover {color: green} +A:active {color: red; background-color: white} +</style> +</head> +<h1 align="center">Ohio Educational Computer Network System (OECN)</h1> +<h1 align="center">System Manager Manual</h1> +As Developed by: Ohio Department of Education, State Software +Development Team +<p align=center> +<strong>Revision/Update Information: </strong> +May, 2001 + +<p> +<hr size=5> +<h4>Copyright ©1992, 1995 Ohio Department of Education</h4> + +<p> +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. +<p> +<table border=5> + <tr> + <td width=120 align=center> +<a href="oecn10_sysman_handbook_full_contents.html"><font size=+2>Contents</font></a> + </td> + </tr> +</table> +<a name="post_contents"></a> + +<p> +<hr size=5> +<a name="menu_processor"><h1>Menu Processor Theory and Implementation</h1></a> +<br> +<br> + +<p> +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: + +<p> + Introduction +<br> + Theory +<br> + Implementation +<br> + Invoking the Menu Processor +<br> + Modifying and Creating Menu Systems +<br> + Customizing Menus from the Distribution + +<p> +<hr size=5> +<a name="menu_intro"><h1>Chapter 1<br>Introduction</h1></a> + +<p> + 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. + +<a name="menu_features_head"><h1>1.1 Features</h1></a> + +<p> + The Menu processor provides the following features: + +<ul> + <li>User may access an item by its item number or label. + <li>Abbreviations are allowed on the current menu. + <li>Aliases are supplied for all items. The user may enter the label + name for any item on any menu in the current menu system. + <li>Help may be obtained for the current menu via the VMS Help utility. + <li>Users will only see the items on the menu that they are authorized + to access. +</ul> + +<p> + Features for the system manager: + +<ul> + <li>May be used for CAPTIVE user accounts. + <li>Menus or items may be easily added or removed. + <li>Access to items and menus may be controlled with the standard + OECN_xxxx VMS security identifiers. + <li>The OSA utility may be used to customize security. + <li>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. + <li>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. + <li>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. + <li>May be used from batch if the third parameter to the OECN_MENU + procedure is used. + <li>Optional timeout feature that automatically exits the menu system + if the user remains inactive for a specified period. +</ul> + +<p> +<hr size=5> +<a name="menu_theory"><h1>Chapter 2<br>Theory</h1></a> + +<p> + 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. + +<a name="menu_terms_head"><h1>2.1 Definition of Terms</h1></a> + +<p> + First, it will be helpful to define some terms that will be used + throughout the rest of this document. <p> + +<table border=3> + <caption><a name="menu_terms_tab"><strong>Table 2-1 Menu System Terms</strong></a></caption> + <tr> + <th align=center>Term </th> + <th align=center>Meaning </th> + </tr> + <tr> + <td> + Menu Processor + </td> + <td> + The program that the user runs to enter a menu system. + </td> + </tr> + <tr> + <td> + menu + </td> + <td> + A menu consists of the menu heading and the menu items on that menu. + </td> + </tr> + <tr> + <td> + menu name + </td> + <td> + The name of the menu as defined in the MENUEDT program. + </td> + </tr> + <tr> + <td> + menu item + </td> + <td> + An item on a menu. An item belongs to a specific menu and must have a + label that is unique throughout the menu system. + </td> + </tr> + <tr> + <td> + label + </td> + <td> + 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. + </td> + </tr> + <tr> + <td> + menu file + </td> + <td> + A file created by MENUEDT that contains the menu definitions for one + for more menus. + </td> + </tr> + <tr> + <td> + menu system + </td> + <td> + A menu system is a collection of menus that the user has access to. + This is the + <strong>logical</strong> menu system as viewed by a specific user. A + system may consist of one or more physical menu files. + </td> + </tr> + <tr> + <td> + menu specification + </td> + <td> + A menu specification is the format for specifying a menu. The + specification may contain a file and/or a menu name. + </td> + </tr> + <tr> + <td> + alias + </td> + <td> + 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. + </td> + </tr> +</table> + +<a name="menu_files_theory"><h1>2.2 How Menu Files Create a Menu System</h1></a> + +<p> +<a href="oecn10_sysman_handbook_full.html#menu_system_fig">Figure 2-1</a> displays a graphical representation of a possible menu +system. +<a name="menu_system_fig"></a> +<p> +<strong>Figure 2-1 Conceptual View of a Menu system</strong> +<hr> + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> ++-----------------------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+ | | +| | | | | || | | | | | | | | | +| | +----+ +----+| | +----+ | | +----+ | | +| +--------------+ +---------+ +---------+ | ++-----------------------------------------------------+ +</pre> +</table> + +<p> + You can see from <a href="oecn10_sysman_handbook_full.html#menu_system_fig">Figure 2-1</a> 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. + +<p> + 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 <strong>local</strong> 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. + +<p> + 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. + +<p> + Each menu system has one alias file. This file is used to find an + item's location if the user enters an alias. + +<p> +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. + +<a name="menu_specs_head"><h1>2.3 Menu Specifications</h1></a> + +<p> + Throughout this document there are references to <strong>menu + specifications</strong>. Wherever a menu specification is required the + following syntax is allowed: +<table border=0> + <tr> + <td> + <br> +<pre> +@menu_file\menu_name +</pre> + </td> + </tr> +</table> +<p> + +<table border=3> + <tr> + <th align=center>Parameter </th> + <th align=center>Meaning </th> + </tr> + <tr> + <td> + @menu_file + </td> + <td> + Name of a menu file that contains menu_name. If not specified then + menu_name is assumed to exist in the current menu file. + </td> + </tr> + <tr> + <td> + menu_name + </td> + <td> + A menu within either the specified menu file or the current menu file. + </td> + </tr> +</table> + +<p> + A valid menu specification contains one or both of these components. + +<p> + 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. + +<p> + If a menu file is specified without a menu name then the default menu + of the menu file's header record is used. + +<p> + If both the menu file and menu name are specified they must be + separated by a backslash (\). + +<p> +Examples: + +<table border=3> + <tr> + <th align=center>Specification </th> + <th align=center>Result </th> + </tr> + <tr> + <td> + @BUD_MENU\USAS_PRC + </td> + <td> + Goes to the USAS_PRC menu of the BUD_MENU file. + </td> + </tr> + <tr> + <td> + @MAIN_MENU + </td> + <td> + Goes to the default menu of the MAIN_MENU file. + </td> + </tr> + <tr> + <td> + LOCAL + </td> + <td> + Goes to the LOCAL menu of the current file. + </td> + </tr> +</table> + +<a name="alias_file_head"><h1>2.4 The Alias File</h1></a> + +<p> + Each menu system may have exactly one <strong>alias file</strong>. 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. + +<p> + 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. + +<p> +The alias file is built automatically by the MENUUTL program. See +<a href="oecn10_sysman_handbook_full.html#build_alias_head">Section 5.2.1, Building the Alias File</a> for more information about creating the alias file. + +<a name="option_exec_sect"><h1>2.5 Option execution</h1></a> + +<p> +By default, the menu processor does <em>not</em> 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 +<strong>"terminate and execute"</strong> mode. This mode may provided +optimal response time for smaller VAX processors, particularly machines +with small memory configurations. + +<a name="heading_2.5.1"><h2>2.5.1 Spawning Options</h2></a> + +<p> +Another mode that may be chosen by the system manager is "spawn and +execute". In this mode, <em>most</em> 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. + +<p> +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. + +<p> +To implement menu option spawning the system manager must be aware of +the following: + +<ol start=1 > + <li>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. + <li>Other user quotas also may need to be increased in order for the + main and subprocess to have access to sufficient resources. + <li>BALCSETCNT (balance set count) in SYSGEN must be large enough to + handle the addition processes. + <li>Some types of options must be executed in the main process (see + below). +</ol> + +<p> +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. + +<p> +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. + +<a name="heading_2.5.2"><h2>2.5.2 Selecting Execution Mode</h2></a> + +<p> +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: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +$ DEFINE/SYSTEM OECN$MENU_BEHAVIOR "SPAWN" +</pre> +</table> + +<p> +This logical also can be defined at the group or process level. If the +logical is not defined, the default is "TERMINATE". + +<a name="timeout_head"><h1>2.6 Inactivity Timeout</h1></a> + +<p> +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. + +<p> +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: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +$ DEFINE/SYSTEM OECN$MENU_BEHAVIOR "TIMEOUT=n" +</pre> +</table> + +<p> + Where <em>n</em> 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. + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Note</strong></font></center><hr + size=1 noshade> +The menu processor simply exits the menu and returns to DCL it does not +log the user off the system. It is up to the local captive login +procedure or other mechanism to log the user off. </td> + </tr> +</table> +</center> + +<p> +<hr size=5> +<a name="menu_implentation_chap"><h1>Chapter 3<br>Implementation</h1></a> + +<p> + Several steps are required in order to implement the Menu Processor on + your system. The steps are briefly outlined below, detailed + explanations follow: + +<ol start=1 > + <li> Install the OECN, MENU and HELP distribution packages with + OECN_INSTALL. + <li> Establish the necessary OECN logicals. + <li> Move the menu files and VMS Help libraries from the distribution + directories to the appropriate directories on your system. + <li> Create the OECN_MENU symbol. + <li> Use the VMS Install utility to make the Menu Processor a known, + shared image. +</ol> + +<a name="installation_head"><h1>3.1 Installation</h1></a> + +<p> + 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. + +<a name="logicals_head"><h1>3.2 Establish OECN Logicals</h1></a> + +<p> + Several logicals are used by the Menu Processor to locate the menu + files and VMS Help libraries. <p> + +<table border=3> + <caption><a name="logicals_tab"><strong>Table 3-1 Menu Logicals</strong></a></caption> + <tr> + <th align=center>Logical </th> + <th align=center>Purpose </th> + </tr> + <tr> + <td> + OECN$MENU$FILES + <sup>1</sup> + </td> + <td> + Device and directory where the menu files are located. + </td> + </tr> + <tr> + <td> + OECN$MENU + <sup>2</sup> + </td> + <td> + Default menu file if none is specified by the user when the Menu + Processor is invoked. + </td> + </tr> + <tr> + <td> + OECN$ALIAS + <sup>2</sup> + </td> + <td> + Default alias file that is used if none is specified when the Menu + Processor is invoked. + </td> + </tr> + <tr> + <td> + OECN$SECUR + </td> + <td> + Local security file. Optional. Created by OSA utility to define local + security. + </td> + </tr> + <tr> + <td> + OECN$HELP + <sup>1</sup> + </td> + <td> + Device and directory where the VMS Help libraries are located. + </td> + </tr> + <tr> + <td> + OECN$MENU_HELP + <sup>2</sup> + </td> + <td> + Default menu help library. Used when the user presses + <kbd>[PF2]</kbd> or ?. + </td> + </tr> + <tr> + <td> + OECN_MENU_PROMPT + </td> + <td> + Default prompt to be used in the Menu Processor. Optional. May be + overridden by the user with a SET PROMPT command. + </td> + </tr> + <tr> + <td> + OECN_MENU_MODE + </td> + <td> + Default mode. Optional. May contain the "MENU" or "COMMAND". May be + overridden by the user with a SET MODE command. + </td> + </tr> + <tr> + <td> + OECN$MENU_BEHAVIOR + </td> + <td> + 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 <a href="oecn10_sysman_handbook_full.html#behavior_logical">3.2.1</a>. + </td> + </tr> +</table> +<hr> +<sup>2</sup> Defined by the OECN_STARTUP procedure. +<br> +<sup>1</sup>May be defined as a search list. +<br> +<hr> + +<p> + 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. + +<a name="behavior_logical"><h2>3.2.1 Specifying options with OECN$MENU_BEHAVIOR logical</h2></a> + +<p> + This section describes the commands that may be placed in the + OECN$BEHAVIOR logical. The syntax for the logical definition is: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +$ DEFINE/SYSTEM OECN$MENU_BEHAVIOR "command[,command]..." +</pre> +</table> + +<p> + Where <em>[command]</em> 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. + <p> + +<table border=3> + <caption><a name="Table_3-2"><strong>Table 3-2 Behavior Options</strong></a></caption> + <tr> + <th align=center>Command </th> + <th align=center>Description </th> + </tr> + <tr> + <td> + TERMINATE + </td> + <td> + Causes the processor to use the " terminate and execute " + method for executing options. This is the default behavior. + </td> + </tr> + <tr> + <td> + SPAWN + </td> + <td> + Causes the processor to spawn all DCL and Program type action items in + a subprocess. + </td> + </tr> + <tr> + <td> + TIMEOUT=n + </td> + <td> + Sets the inactivity timeout interval to n minutes. + </td> + </tr> + <tr> + <td> + NOTIMEOUT + </td> + <td> + Disables inactivity timeout. This is the default behavior. + </td> + </tr> +</table> + +<p> + For example, to specify the spawn option and a timeout of 30 minutes + use the following command: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +$ DEFINE/SYSTEM OECN$MENU_BEHAVIOR "SPAWN,TIMEOUT=30" +</pre> +</table> + +<a name="move_files_head"><h1>3.3 Move Files to Appropriate Directories</h1></a> + +<p> + Move the menu files (OECN$ROOT:[MENU.DIST]*.DAT) to the directory + referenced by OECN$MENU$FILES. + +<p> + Move the VMS Help libraries from the HELP package distribution + directory to the directory referenced by OECN$HELP. + +<p> + The users of the Menu Processor must have read access to the above + files. + +<p> + Also move the following files to the OECN$ directory: + +<blockquote> + OECN$ROOT:[OECN.V1P0.DIST]MENU.EXE + <br>OECN$ROOT:[OECN.V1P0.DIST]OECN_MENU.COM +</blockquote> + +<p> + The users must have execute access to these files. + +<a name="add_symbol_head"><h1>3.4 Add Global Symbol</h1></a> + +<p> + Add the following symbol to either your SYLOGIN.COM or each user's + LOGIN.COM who will be using the system: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +$ OECN_MENU :== $OECN$:MENU +</pre> +</table> + +<p> + 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 <a href="oecn10_sysman_handbook_full.html#invoking_chap">Chapter 4, Invoking the Menu Processor</a>. The OECN_MENU symbol is the only required symbol. + +<a name="install_head"><h1>3.5 Install the Menu Processor</h1></a> + +<p> + Although it is not necessary for proper execution of the Menu + Processor, it is <strong>strongly</strong> recommended that you install + the Menu Processor as a known image. + +<p> + 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. + +<p> + The recommended method of installing the image is to add the following + commands to your SYSTARTUP.COM: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +$ INSTALL :== $INSTALL/COMMAND_MODE +$ INSTALL ADD OECN$:MENU.EXE/OPEN/SHARED/HEADER +</pre> +</table> + +<p> +<hr size=5> +<a name="invoking_chap"><h1>Chapter 4<br>Invoking the Menu Processor</h1></a> + +<p> + 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. + +<p> + Additionally, the Menu Processor is invoked by the command procedure + with a foreign command. Therefore the following symbol definition is + required. See <a href="oecn10_sysman_handbook_full.html#add_symbol_head">Section 3.4, Add Global Symbol</a>. + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +$ OECN_MENU == "$OECN:MENU" +</pre> +</table> + +<p> + To invoke the menu processor the following command must be used: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +$ @OECN$:OECN_MENU [menu spec] [alias file] [menu_option] +</pre> +</table> + +<p> + The OECN_MENU.COM command procedure is provided with the distribution + and must be used to invoke the menu processor. + +<p> + 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 <a href="oecn10_sysman_handbook_full.html#menu_specs_head">Section 2.3, Menu Specifications</a> for + more information about menu specifications. + +<p> + The second optional parameter is the alias file for the menu system + being invoked. If not specified then OECN$ALIAS is used by default. + +<p> +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 +<strong>not</strong> 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. + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Note</strong></font></center><hr + size=1 noshade> +The menu processor will operate properly in batch only if the third +parameter is supplied. If the parameter is not specified the menu +processor will not function in batch. </td> + </tr> +</table> +</center> + +<p> + 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. + +<a name="invoke_example_head"><h1>4.1 Examples</h1></a> + +<p> + For most users the following symbol definition is sufficient: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +$ MENU == "@OECN$:OECN_MENU" +</pre> +</table> + +<p> + 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. + +<p> +If users will be using the third parameter (or it will be used from +batch) then the following symbol might be used: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +$ MENU == "OECN$:OECN_MENU """" """" " +</pre> +</table> + +<p> +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. + +<p> + 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: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +$ MENU == "@OECN$:OECN_MENU @PAY_MENU" +</pre> +</table> + +<p> + 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. + +<p> +<hr size=5> +<a name="modifying_menus_chap"><h1>Chapter 5<br>Modifying and Creating Menu Systems</h1></a> + +<p> + 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. <p> + +<table border=3> + <caption><a name="menu_type_tab"><strong>Table 5-1 Menu Record Types</strong></a></caption> + <tr> + <th align=center>Record Type </th> + <th align=center>Function </th> + </tr> + <tr> + <td> + File Header Record + </td> + <td> + Contains information about the entire menu file. There is only one file + header record per file. + </td> + </tr> + <tr> + <td> + Menu Header Record + </td> + <td> + 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. + </td> + </tr> + <tr> + <td> + Item Record + </td> + <td> + 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). + </td> + </tr> +</table> + +<p> + The menu files and records form a <em>loose</em> 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. + +<a name="using_edt_head"><h1>5.1 Using MENUEDT</h1></a> + +<p> + 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. <p> + +<table border=3> + <caption><a name="edt_options_tab"><strong>Table 5-2 MENUEDT Main Menu Options</strong></a></caption> + <tr> + <th align=center>Option </th> + <th align=center>Function </th> + </tr> + <tr> + <td> + Add + </td> + <td> + Adds new records of any type. + </td> + </tr> + <tr> + <td> + Change + </td> + <td> + Enters change mode for the current record. + </td> + </tr> + <tr> + <td> + Delete + </td> + <td> + Deletes the current record. + </td> + </tr> + <tr> + <td> + Top + </td> + <td> + Goes to top of file (File header record). + </td> + </tr> + <tr> + <td> + Find + </td> + <td> + Finds a record by menu or item name. + </td> + </tr> + <tr> + <td> + Next + </td> + <td> + Goes to the next record. + </td> + </tr> + <tr> + <td> + Simulate + </td> + <td> + 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. + </td> + </tr> + <tr> + <td> + Open + </td> + <td> + Closes the current menu file and prompts for a new menu file to open. + </td> + </tr> + <tr> + <td> + Exit + </td> + <td> + Exits MENUEDT. + </td> + </tr> +</table> + +<a name="menu_type_head"><h2>5.1.1 Menu File Record Types</h2></a> + +<p> + 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. + +<a name="file_header_head"><h2>5.1.2 File Header Record</h2></a> + +<p> + The first record in each menu file must be a File Header record and + each file must contain exactly one Header record. + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + + Menu File Header Record: + + 1. Desc: + 2. Default menu: + 3. Modify default security identifiers + +</pre> +</table> + +<p> + +<table border=3> + <caption><a name="file_header_fld_tab"><strong>Table 5-3 File Header Record Fields</strong></a></caption> + <tr> + <th align=center>Field </th> + <th align=center>Description </th> + </tr> + <tr> + <td> + Desc + </td> + <td> + This description is used in the heading for all menus in this file. + </td> + </tr> + <tr> + <td> + Default Menu + </td> + <td> + 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. + </td> + </tr> + <tr> + <td> + Modify default security identifiers + </td> + <td> + Enters the + <em>Security Id Maintenance</em> screen to allow default security + identifiers to be placed on the menu file. See <a href="oecn10_sysman_handbook_full.html#secur_id_screen_head">Section 5.1.5</a> for more + information about security identifiers. + </td> + </tr> +</table> + +<a name="menu_header_head"><h2>5.1.3 Menu Header Record</h2></a> + +<p> + 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. + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + + Menu header record: + + 1. Menu Name : + 2. Description : + 3. Heading Type: + 4. Help file : + 5. Help topic : + 6. Parent Menu : + 7. Modify Security Identifiers + +</pre> +</table> + +<p> + +<table border=3> + <caption><a name="menu_header_fld_tab"><strong>Table 5-4 Menu Header Fields</strong></a></caption> + <tr> + <th align=center>field </th> + <th align=center>Description </th> + </tr> + <tr> + <td> + Menu Name + </td> + <td> + Name of the menu. This is the name that will be displayed in the menu + heading. + </td> + </tr> + <tr> + <td> + Description + </td> + <td> + This description is used in the heading for this menu. + </td> + </tr> + <tr> + <td> + Heading Type + </td> + <td> + Indicates what type of menu heading to use for this menu. + <table border=3> + <tr> + <td> + A + </td> + <td> + Heading contains both the file description and the menu description. + </td> + </tr> + <tr> + <td> + B + </td> + <td> + Heading contains only the menu heading description. + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td> + Help File + </td> + <td> + The VMS Help file that will be used if the user enters HELP at this + menu. + </td> + </tr> + <tr> + <td> + Help topic + </td> + <td> + The initial topic string used when the user enters HELP. + </td> + </tr> + <tr> + <td> + Parent Menu + </td> + <td> + 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. + </td> + </tr> + <tr> + <td> + Modify security identifiers + </td> + <td> + Enters the + <em>Security Id Maintenance</em> screen to allow security identifiers + to be placed on the menu. See <a href="oecn10_sysman_handbook_full.html#secur_id_screen_head">Section 5.1.5</a> more information about + security identifiers. + </td> + </tr> +</table> + +<a name="menu_item_head"><h2>5.1.4 Menu Item Record</h2></a> + +<p> + 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. + +<p> + 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 <a href="oecn10_sysman_handbook_full.html#item_types_tab">Table 5-5</a>. + <p> + +<table border=3> + <caption><a name="item_types_tab"><strong>Table 5-5 Menu Item Types</strong></a></caption> + <tr> + <th align=center>Item Type </th> + <th align=center>Interpretation of Action Field </th> + </tr> + <tr> + <td> + D + </td> + <td> + DCL command to execute + </td> + </tr> + <tr> + <td> + DP + </td> + <td> + DCL command to execute in Parent process + </td> + </tr> + <tr> + <td> + P + </td> + <td> + Program filespec to execute + </td> + </tr> + <tr> + <td> + M + </td> + <td> + Menu specification + </td> + </tr> + <tr> + <td> + T + </td> + <td> + Ignored + </td> + </tr> +</table> + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + + Menu Item record: + + 1. Menu Name: + 2. Label : + 3. Desc : + 4. Item Type: + 5. Action : + + 6. Item order#: + 7. Modify Security Identifiers + +</pre> +</table> + +<p> + +<table border=3> + <caption><a name="menu_item_tab"><strong>Table 5-6 Menu Item Fields</strong></a></caption> + <tr> + <th align=center>Field </th> + <th align=center>Description </th> + </tr> + <tr> + <td> + Menu Name + <sup>1</sup> + </td> + <td> + Name of the menu that this item belongs to. + </td> + </tr> + <tr> + <td> + Label + <sup>1</sup> + </td> + <td> + Label of this item that the user will use to reference this item. + </td> + </tr> + <tr> + <td> + Desc + </td> + <td> + Description displayed for this item. + </td> + </tr> + <tr> + <td> + Item Type + </td> + <td> + Indicates what type of item this is: + <table border=3> + <tr> + <td> + D + </td> + <td> + DCL command + </td> + </tr> + <tr> + <td> + DP + </td> + <td> + DCL in Parent process + </td> + </tr> + <tr> + <td> + P + </td> + <td> + Program to be executed + </td> + </tr> + <tr> + <td> + M + </td> + <td> + Menu item + </td> + </tr> + <tr> + <td> + T + </td> + <td> + Text Item + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td> + Action + </td> + <td> + Contains the action to be performed when this item is selected. See + <a href="oecn10_sysman_handbook_full.html#action_values_head">Section 5.1.4.1</a> for more information. + </td> + </tr> + <tr> + <td> + Item order # + </td> + <td> + 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. + </td> + </tr> + <tr> + <td> + Modify security identifiers + </td> + <td> + Enters the + <em>Security Id Maintenance</em> screen to allow security identifiers + to be placed on the item. See section <a href="oecn10_sysman_handbook_full.html#secur_id_screen_head">Section 5.1.5</a> for more information + about security identifiers. + </td> + </tr> +</table> +<hr> +<sup>1</sup>Key fields of the menu file. However the MENUEDT program +allows these fields to be changed. +<br> +<hr> + +<a name="action_values_head"><h3>5.1.4.1 Values for Action Field</h3></a> + +<p> + 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. +<p> +<strong>Item Type D (DCL)</strong> +<br> + +<p> + 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 <a href="oecn10_sysman_handbook_full.html#option_exec_sect">Section 2.5</a>). For example, the following are + valid for Action: + +<blockquote> + MAIL + <br>@PURGE_TEXT_FILES + <br>Write sys$output "Hello there." +</blockquote> + +<p> + 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. + +<p> + 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: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +@OECN$UTL:PRINT ~ ~ +</pre> +</table> + +<p> + 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: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +Menu> PRINT MYFILE.TXT 10 +</pre> +</table> + +<p> + The DCL command that would be executed by the Menu Processor would be: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +$ @OECN$UTL:PRINT MYFILE.TXT 10 +</pre> +</table> + +<p> + 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. +<p> +<strong>Item Type DP (DCL in Parent)</strong> +<br> + +<p> + 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 <a href="oecn10_sysman_handbook_full.html#option_exec_sect">Section 2.5</a>). + +<p> +This item type should be used sparingly and only when the command +<em>must</em> 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: + +<ul> + <li>Commands that change security identifiers + <li>Commands that modify menu logicals or modes + <li>Commands that spawn subprocesses with the /NOWAIT qualifier +</ul> + +<p> +<strong>Item Type P (Program)</strong> +<br> + +<p> + 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. +<p> +<strong>Item Type M (Menu)</strong> +<br> + +<p> + 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 + <a href="oecn10_sysman_handbook_full.html#menu_specs_head">Section 2.3</a> for more information about menu specifications. +<p> +<strong>Item Type T (Text)</strong> +<br> + +<p> + 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. + +<a name="secur_id_screen_head"><h2>5.1.5 Menu Security Screen</h2></a> + +<p> + The <strong>Modify Security Identifier</strong> screen allows you to + require that the user has specific VMS identifiers before they are + allowed access to certain menu elements. + +<p> + 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. + +<p> +Three levels of access can be specified for each identifier that +appears on the Security Identifier screen: Read-only, Standard or Group +Manager. See <a href="oecn10_sysman_handbook_full.html#security_ids">Section 5.1.5.1</a> for more information about how these +identifiers are derived. + +<p> + 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. + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + 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) + +</pre> +</table> + +<p> + 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. + +<ol start=1 > + <li>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. + <li>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. + <li>The top-level menu of each menu file, will inherit security from + the file header record. + <li>If no security is specified, after rule #3 above, then there is no + security required to access the menu element. +</ol> + +<p> + 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. + +<p> + 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. + +<a name="security_ids"><h3>5.1.5.1 Security Identifiers</h3></a> + +<p> + 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. + +<p> + The following table lists the three access levels, in order of lowest + level access to the highest. <p> + +<table border=3> + <caption><a name="security_level_tbl"><strong>Table 5-7 Security Access Levels</strong></a></caption> + <tr> + <th align=center>Access Level </th> + <th align=center>Suffix </th> + <th align=center>Description </th> + </tr> + <tr> + <td> + Read-Only + </td> + <td> + _RO + </td> + <td> + 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. + </td> + </tr> + <tr> + <td> + Standard + </td> + <td> + none + </td> + <td> + 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. + </td> + </tr> + <tr> + <td> + Group Manager + </td> + <td> + _GM + </td> + <td> + Users that hold this identifier are granted access to "group + manager" functions. This user is assumed to hold special + privileges within the corresponding package. + </td> + </tr> +</table> + +<p> +For example, for the OECN_USPS identifier there are really three +identifiers that may be granted to a user. These identifiers are: + +<blockquote> + OECN_USPS_RO + <br>OECN_USPS + <br>OECN_USPS_GM +</blockquote> + +<p> +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. + +<p> +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. + +<a name="menuutl_head"><h1>5.2 Using MENUUTL</h1></a> + +<p> + The MENUUTL program provides some necessary functions for building, + maintaining and documenting a menu system. The options provided are: + +<ol start=1 > + <li>Build the Alias File + <li>Simulated Menu Listing + <li>Detailed Menu Report + <li>Hierarchical Menu Listing +</ol> + +<a name="build_alias_head"><h2>5.2.1 Building the Alias File</h2></a> + +<p> + 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. + +<p> + MENUUTL makes this process rather simple. All you have to do is run + MENUUTL and choose option 1. MENUUTL will ask the following questions: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +Physical name of top level menu file:___________ +</pre> +</table> + +<p> + Enter the physical filespec of the top-level menu file. This is the + current physical location of the top-level menu file. + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +Logical name of top level menu file:_____________ +</pre> +</table> + +<p> + 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. + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Note</strong></font></center><hr + size=1 noshade> + The physical and logical name should normally be the same. </td> + </tr> +</table> +</center> + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +Enter new alias filename: ___________________ +</pre> +</table> + +<p> + 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. + +<p> + 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. + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Important</strong></font></center><hr + size=1 noshade> + MENUUTL uses the OECN$MENU$FILES logical to search for the menu files + in the same manner as will be used by the Menu Processor. Therefore, + the runtime environment for MENUUTL must be the same as when the Menu + Processor will be invoked. </td> + </tr> +</table> +</center> + +<p> + 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. + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Note</strong></font></center><hr + size=1 noshade> + You may also use the OECN$:BUILD_ALIAS.COM command procedure to build + the alias file. This procedure will automatically build a new alias + file using the current values of OECN$MENU$FILES, OECN$MENU and + OECN$ALIAS. You can run this procedure after installing a new + distribution or customizing menu files. If you frequently modify menu + files, you could even run the procedure periodically in batch to ensure + that the alias file is always up-to-date. </td> + </tr> +</table> +</center> + +<a name="simulate_list_head"><h2>5.2.2 Simulated Menu Listing</h2></a> + +<p> + 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. + +<a name="detailed_list_head"><h2>5.2.3 Detailed Menu Listing</h2></a> + +<p> + 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. + +<a name="hier_list_head"><h2>5.2.4 Hierarchical Listing</h2></a> + +<p> + 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. + +<a name="osa_head"><h1>5.3 OSA</h1></a> + +<p> +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 <em>local security</em> 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) + +<p> +<hr size=5> +<a name="custom_chap"><h1>Chapter 6<br>Customizing Menus from the Distribution</h1></a> + +<p> + 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. + +<p> + 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 <em>local</em> 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. + +<p> + 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. + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Note</strong></font></center><hr + size=1 noshade> +Security for all menu items may be customized, even if they are part of +the distribution, without modifying the menu files. This is +accomplished by using the OECN Security Authorization (OSA) utility. +See the <em>OECN Software Security for the VMS System Manager</em> +manual for information about the OSA utility and local security. </td> + </tr> +</table> +</center> + +<a name="local_head"><h1>6.1 Modifying a Local Menu File</h1></a> + +<p> + Following is the recommend procedure for modifying one or more menu + files. + +<ol start=1 > + <li>Redefine the OECN$MENU$FILES to be a search list. + <li>Modify the Menu Files + <li>Build a New Alias File + <li>Redefine OECN$MENU$FILES permanently +</ol> + +<a name="redefine_logical_head"><h2>6.1.1 Redefine the OECN$MENU$FILES logical</h2></a> + +<p> + 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: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +$ DEFINE/SYSTEM OECN$MENU$FILES - +_$ OECN$CUSTOM,DUA0:[ODE.MENU.DIST] +</pre> +</table> + +<p> + This will cause the Menu Processor and MENUUTL to search first through + OECN$CUSTOM and then the distribution menu files. + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Note</strong></font></center><hr + size=1 noshade> + You may want to make this logical assignment in your current process, + instead of at the SYSTEM level, while changing the menu files. This + will prevent any users from getting into a half completed menu. </td> + </tr> +</table> +</center> + +<a name="heading_6.1.2"><h2>6.1.2 Modify the Menu Files</h2></a> + +<p> + 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. + +<p> + 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. + +<a name="heading_6.1.3"><h2>6.1.3 Build a New Alias File</h2></a> + +<p> + 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. + +<p> + You may build the alias file manually by running MENUUTL, or you may + use the BUILD_ALIAS.COM procedure in the OECN$ directory. + +<a name="heading_6.1.4"><h2>6.1.4 Redefine OECN$MENU$FILES Permanently</h2></a> + +<p> + If you have not already done so, define the logical OECN$MENU$FILES to + be a search list as above at the SYSTEM level. + +<p> + At this point your users should have access to the customized menus. + +<a name="heading_6.2"><h1>6.2 After a Distribution</h1></a> + +<p> + 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. + +<p> +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. + +<p> + 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: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + $ @OECN$:BUILD_ALIAS +</pre> +</table> + +<p> +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. + +<a name="intercept_head"><h1>6.3 Intercepting Menu Actions</h1></a> + +<p> + 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. + +<p> + This may be done by intercepting the action line of specific options + <em>without</em> 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. + +<p> + The logical must be defined as follows: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +$ DEFINE/SYSTEM OECN$MENU_ACTION_label filespec +</pre> +</table> + +<p> + Where <em>label</em> is the menu option label that you want to + intercept and <em>filespec</em> 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. + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Note</strong></font></center><hr + size=1 noshade> + If the logical is defined system-wide it will affect all menu systems + that you have active on your system. If you have multiple menu systems + that contain the same label then they will all be affected. If this is + not what you want you may need to define this logical at the group or + process level. </td> + </tr> +</table> +</center> + +<p> + After this logical is defined the command procedure will be executed + <em>instead of</em> the action line defined by the menu file. + +<p> + The following parameters will be passed to the command procedure : + +<table border=3> + <tr> + <td> + P1 + </td> + <td> + Menu label name that invoked the procedure + </td> + </tr> + <tr> + <td> + P2 + </td> + <td> + Original action line defined by the menu file + </td> + </tr> + <tr> + <td> + P3-P8 + </td> + <td> + Other parameters entered by the user + </td> + </tr> +</table> + +<p> + The procedure may use these parameters as it wishes or ignore them. + +<p> + 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: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +$! +$! 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 +</pre> +</table> + +<p> + The following logical definition would be made to intercept the BUDDIS + action for all users: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +$ DEFINE/SYSTEM OECN$MENU_ACTION_BUDDIS PAY:BUDDIS_ACTION +</pre> +</table> + +<p> +<hr size=5> +<a name="batch_mail_chap"><h1>Chapter 7<br>Batch Mail Message System Manager Guide</h1></a> + +<a name="heading_7.1"><h1>7.1 Overview</h1></a> + +<p> +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. + +<a name="heading_7.2"><h1>7.2 Sending a Mail Message via Batch</h1></a> + +<p> +To use the command procedure for generic mail messages: + +<p> +Create the desired mail message using a text file. + +<p> +Submit the procedure as follows supplying the necessary parameter +values: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +$ SUBMIT OECN$:BATCH_MAIL_MESSAGE/PARAMETER=("P1","P2","P3","P4") +</pre> +</table> + +<p> +Where: + +<ul> + <li>P1 - Name of the text file to be mailed. + <li>P2 - VMS mail address the text file will be sent to. + <li>P3 - Text that is to be displayed on the Subject Line of the + message. + <li>P4 - Y/N (yes/no) flag that indicates whether or not to delete the + text file containing the message after it is sent. +</ul> + +<p> + +<hr size=5> +<a name="oecn_view_chap"><h1>Chapter 8<br>OECN VIEW Utility</h1></a> + +<a name="heading_8.1"><h1>8.1 Overview</h1></a> + +<p> +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. + +<p> +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. + +<p> +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. + +<p> +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. + +<p> +Examples of the logicals are given below: + +<a name="heading_8.2"><h1>8.2 OECN_VIEW.COM</h1></a> + +<p> +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. + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + + +$!+ +$! 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. +$!- + + +</pre> +</table> + +<a name="heading_8.2.1"><h2>8.2.1 Customizing OECN VIEW</h2></a> + +<p> +The following sample command file shows how to customize the +directories and the file extensions to be viewed. + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + + +$!+ +$! 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 + + + +</pre> +</table> + +<a name="heading_8.2.2"><h2>8.2.2 Creating a DCL Command</h2></a> + +<p> +The VIEW utility works automatically from the MENU. However, you could +define a symbol to execute VIEW from DCL. + +<p> +For example, define: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + +LOOK := = @OECN$:OECN_VIEW + +</pre> +</table> + +<p> +Then use the LOOK command from the $ prompt. + +<a name="heading_8.2.3"><h2>8.2.3 OECN_EDIT</h2></a> + +<p> +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 <a href="oecn10_sysman_handbook_full.html#oecn_edit_chap">Chapter 9, OECN EDIT Utility</a>, for more +details. +<p> + +<hr size=5> +<a name="oecn_edit_chap"><h1>Chapter 9<br>OECN EDIT Utility</h1></a> + +<a name="heading_9.1"><h1>9.1 Overview</h1></a> + +<p> +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. + +<a name="heading_9.2"><h1>9.2 Using OECN_EDIT</h1></a> + +<p> +In order to use OECN_EDIT as your interface to TPU, define the +following symbol: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + +$ EDIT := = $OECN$:OECN_EDIT/TPU + +</pre> +</table> + +<p> +Note: The /TPU qualifier is required. + +<p> +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. +<p> + +<hr size=5> +<a name="oecn_keymap_chap"><h1>Chapter 10<br>OECN KEYMAP Utility</h1></a> + +<a name="heading_10.1"><h1>10.1 Overview</h1></a> + +<p> +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. + +<a name="heading_10.2"><h1>10.2 Using KEYMAP</h1></a> + +<p> +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. + +<p> +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. + +<p> +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. + +<p> +The following standard .INI files have been created: + +<ul> + <li>OECN$KEYMAP_EXCURSIONS.INI + <li>OECN$KEYMAP_PERSONA.INI + <li>OECN$KEYMAP_REFLECTIONS_MAC.INI + <li>OECN$KEYMAP_REFLECTIONS_PC.INI +</ul> + +<p> +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. +<p> + +<hr size=5> +<a name="oecn_setupenv_chap"><h1>Chapter 11<br>OECN SETUPENV Utility</h1></a> + +<a name="heading_11.1"><h1>11.1 Overview</h1></a> + +<p> +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. + +<p> +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. + +<p> +The general goals of the utility are as follows: + +<ol start=1 > + <li>To provide a single location for all configuration information. + <li>To provide a means for processes to establish a default context + during login. + <li>To provide a means for users to change contexts using an + interactive (or DCL) interface. + <li>To allow DAS personnel the ability to switch to any context using + the same rules as a user's process. + <li>To provide compatibility with BUNNY, FROG, and USE to make the + transisition to the new utility easier. + <li>To provide DCL and API interfaces which allow other utilities the + ability to find and establish contexts. + <li>To provide support for common OpenVMS configuration methods in use + by DA Sites, including group tables and shared logical tables. +</ol> + +<a name="heading_11.2"><h1>11.2 Getting Started</h1></a> + +<p> +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. + +<p> +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. + +<a name="heading_11.2.1"><h2>11.2.1 Entity Types</h2></a> + +<p> +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: + +<ul> + <li>DISTRICT + <li>BUILDING + <li>LIBRARY + <li>OTHER +</ul> + +<p> +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. + +<p> +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. +<p> + +<a name="heading_11.2.2"><h2>11.2.2 DCL Command Syntax</h2></a> +<br> + +<p> +SETUPENV must be defined as a foreign command: +<br> + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + +$ SETUPENV :== $OECN$:SETUPENV + +</pre> +</table> + +<p> +Syntax: +<br> + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + +$ 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] + + +</pre> +</table> + +<ul> + <li><strong>ENTRY_CODE</strong> 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. + <li><strong>/MENU</strong> 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. + <li><strong>/RESET</strong> 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. + <li><strong>/LOGIN</strong> 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: + + <ul> + <li><strong>SIS</strong> searches the process' rightslist for + identifiers in the format SIS_x. For the first such identifier "x" is + used as the default entry. + <li><strong>INFOHIO</strong> 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. + <li><strong>BY_ACCESS</strong> 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. + <li><strong>USERNAME=n</strong> 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. + </ul> + <br>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. + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Note</strong></font></center><hr + size=1 noshade> +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. </td> + </tr> +</table> +</center> + <li><strong>/NEXT</strong> 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. + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Note</strong></font></center><hr + size=1 noshade> +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. </td> + </tr> +</table> +</center> + <li><strong>/TYPE</strong> 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. + <li><strong>/CATEGORIES</strong> may be used with /NEXT or /MENU to + select only entries where the CATEGORIES attribute matches the + specified wildcard. + <li><strong>/APPLICATION</strong> 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. + <li><strong>/[NO]PROMPT</strong> 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. + <li><strong>/LOG</strong> 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. + <li><strong>/ARCHIVE[=archive_code]</strong> 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. + <li><strong>/RESTRICT_IRNS</strong> 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. + <li><strong>/PRINT</strong> 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. + <li><strong>/EMIS</strong> 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: + + <ul> + <li>/NEXT + <li>/RESET + <li>/MENU + <li>/CATEGORIES + <li>/LOG + </ul> + <br>See the "EMIS_SELECT Compatibility" section for more information. + <li><strong>/USE, /BUNNY, /FROG</strong> 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. +</ul> + +<h2>Usage Notes</h2> + +<p> +When /NEXT is used, if the specified or next entry cannot be found +SETUPENV exits with an error severity. + +<p> +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. + +<p> +Likewise, when /EMIS is specified, EMIS_SELECT_EPILOGUE and +EMIS_SWITCH_FY will be invoked after successfully selecting a database. + +<a name="heading_11.3"><h1>11.3 Logicals Created By SETUPENV</h1></a> + +<p> +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). + +<p> +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. + +<p> +The logical OECN$SETUP_ARCHIVE contains the archive code if one was +selected using /ARCHIVE or the menu. + +<p> +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: + +<ul> + <li>OECN$SETUP_CURRENT_DISTRICT + <li>OECN$SETUP_CURRENT_BUILDING + <li>OECN$SETUP_CURRENT_LIBRARY + <li>OECN$SETUP_CURRENT_OTHER +</ul> + +<p> +The logical will not exist for types that have not been selected. + +<p> +The value of the OECN$SETUP_CURRENT_* logicals is a string that +describes the selected entry. The format for the string entry is: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + + "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 + +</pre> +</table> + +<p> +This string is formatted in a manner that is easily parsed using the +F$ELEMENT lexical function. + +<p> +The following logicals may also be defined depending on the selected +entries relationship with other entries: + +<ul> + <li><strong>OECN$SETUP_PARENT</strong>---Contains the PARENT entry for + the current entry + <li><strong>OECN$SETUP_CHILDREN</strong>---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. + <li><strong>OECN$SETUP_SIBLINGS</strong>---Contains a list, separated + by commas, of "siblings" (excluding the current entry). That is, a list + of entries that share the same parent entry. +</ul> + +<p> +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). + +<a name="heading_11.4"><h1>11.4 OECN$SETUP.INI</h1></a> + +<p> +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. + +<p> +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. + +<p> +The parameters and formats for each section are as follows: + +<ul> + <li><strong>SECTION={entity_code}</strong> <br>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). + <li><strong>DESCRIPTION="text"</strong> <br>Text description for menu + <li><strong>TYPE={DISTRICT|BUILDING|LIBRARY|OTHER}</strong> + <br>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. + <li><strong>CATEGORIES="string"</strong> <br>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. + <li><strong>APPLICATIONS={app}[,...]</strong> <br>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. + <br><strong>Note:</strong> 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: + + <blockquote> + USPS + <br> USAS + <br> EMIS + <br> EIS + <br> VIS + <br> SIS (McSIS) + <br> INFOHIO + </blockquote> + <li><strong>IRN={irn}</strong> <br>Optional IRN for the entry. Returned + to DCL via the OECN$SETUP_CURRENT logical and optionally used in the + OECN$EMIS_RESTRICT_IRNS logical. + <li><strong>PROMPT="prompt string"</strong> <br>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. + <li><strong>ARCHIVE={archive_code},[description],[table]...</strong> + <br> 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. <br>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. <br>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. + <li><strong>LOGICAL={logical_name[@archive_code]}[,CONCEALED] + [,IF_EXISTS],[values]...</strong> <br> 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. <br> If the CONCEALED keyword is included, then the logical + will be concealed. <br><strong>Conditional Logicals</strong> <br>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: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + + LOGICAL=OECN$EMIS_STU_SEARCH,IF_EXISTS,OECN$EMIS$DTA:EMSALT.IDX + LOGICAL=OECN$EMIS$DTA,CONCEALED,EMIS_ROOT:[LIVE] +</pre> +</table> + + <br> In this case, OECN$EMIS_STU_SEARCH will only be defined if the + OECN$EMIS$DTA:EMSALT.IDX file exists. + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Note</strong></font></center><hr + size=1 noshade> +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. </td> + </tr> +</table> +</center> + <br><strong>Archive Logicals</strong> <br>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. <br> 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. + <li><strong>SYMBOL={symbol_name}[,symbol_value]</strong> <br>Sets a + global symbol. If a value is not specified, then the symbol is deleted. + <strong>Note:</strong> The symbol and value must be made up of + printable characters. Non-printable values may not be included (in the + current version of SETUPENV). + <li><strong>PARENT={entry}</strong> <br>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. + <br>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. + <li><strong>GROUP_TABLE={octal_group_number}</strong> <br>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. + <li><strong>TABLE={logical_name_table},...</strong> <br>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. + <li><strong>IDENTIFIER={ident_specification}</strong> <br>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. <br>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: + + <blockquote> + IDENTIFIER="[101,*]" + <br>IDENTIFIER=SIS_BLDA + <br>IDENTIFIER="OECN_USAS+ARCHBOLD_FISCAL" + </blockquote> + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Note</strong></font></center><hr + size=1 noshade> +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. </td> + </tr> +</table> +</center> +</ul> + +<a name="heading_11.4.1"><h2>11.4.1 Special "Reset" Entries</h2></a> + +<p> +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. + +<p> +The following reset sections may be specified: + +<ul> + <li>$RESET_DISTRICT + <li>$RESET_BUILDING + <li>$RESET_LIBRARY + <li>$RESET_OTHER +</ul> + +<p> +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. + +<p> +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. + +<p> +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: + +<blockquote> + SECTION=$RESET_DISTRICT + <br>LOGICAL=OECN$DTA + <br>LOGICAL=OECN$OUT,"SYS$DISK:[]" +</blockquote> + +<p> +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. + +<a name="heading_11.4.2"><h2>11.4.2 Sample OECN$SETUP File</h2></a> + +<p> +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. + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + + 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 +</pre> +</table> + +<p> +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. + +<p> +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. + +<p> +The special $RESET_DISTRICT section is provided to ensure that the +district logical get reset appropriately prior to setting an entry. + +<a name="heading_11.4.3"><h2>11.4.3 Special "APPLICATION" Entries</h2></a> + +<p> +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: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + 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] +</pre> +</table> + +<p> +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. + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Note</strong></font></center><hr + size=1 noshade> +Note: The above is for example only. In practice, OECN$DTA might be +more efficiently defined as a system logical. </td> + </tr> +</table> +</center> + +<p> +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. + +<a name="heading_11.4.4"><h2>11.4.4 Special "INCLUDE" Section</h2></a> + +<p> +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. + +<p> +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: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + SECTION=$INCLUDE + FILE=OECN$CUSTOM:DISTRICT_A.INI + FILE=OECN$CUSTOM:DISTRICT_B.INI + FILE=OECN$CUSTOM:DISTRICT_C.INI +</pre> +</table> + +<p> +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. + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Note</strong></font></center><hr + size=1 noshade> +There is a performance penalty incurred for splitting INI files into +many parts. SETUPENV must read the primary and all included files each +time it is invoked. </td> + </tr> +</table> +</center> + +<p> +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. + +<p> +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. + +<a name="heading_11.4.5"><h2>11.4.5 Limits</h2></a> + +<p> +Certain limits which apply to the OECN$SETUP.INI file are shown in the +table below. Limits are 'per entry' unless otherwise noted. <p> + +<table border=3> + <caption><a name="Table_11-1"><strong>Table 11-1 wide</strong></a></caption> + <tr> + <th align=center>Attribute </th> + <th align=center>Maximum Length </th> + <th align=center>Limit </th> + </tr> + <tr> + <td> + FILE (in $INCLUDE section) + </td> + <td> + 50 + </td> + <td> + 100 total in all files + </td> + </tr> + <tr> + <td> + SECTION + </td> + <td> + 12 + </td> + <td> + 500 total in all files + </td> + </tr> + <tr> + <td> + DESC + </td> + <td> + 40 + </td> + <td> + 1 + </td> + </tr> + <tr> + <td> + TYPE + </td> + <td> + 12 + </td> + <td> + 1 + </td> + </tr> + <tr> + <td> + IRN + </td> + <td> + 6 + </td> + <td> + 1 + </td> + </tr> + <tr> + <td> + CATEGORIES + </td> + <td> + 40 + </td> + <td> + 1 + </td> + </tr> + <tr> + <td> + APPLICATIONS + </td> + <td> + 10 + </td> + <td> + 15 (five per line) + </td> + </tr> + <tr> + <td> + ARCHIVE + </td> + <td> + 6 + </td> + <td> + 20 + </td> + </tr> + <tr> + <td> + ARCHIVE (tables) + </td> + <td> + 32 + </td> + <td> + 3 per archive + </td> + </tr> + <tr> + <td> + PROMPT + </td> + <td> + 40 + </td> + <td> + 1 + </td> + </tr> + <tr> + <td> + IDENTIFIERS + </td> + <td> + 80 + </td> + <td> + unlimited * + </td> + </tr> + <tr> + <td> + LOGICAL (name) + </td> + <td> + 50 + </td> + <td> + unlimited * + </td> + </tr> + <tr> + <td> + LOGCIAL (value) + </td> + <td> + 80 + </td> + <td> + 4 per logical + </td> + </tr> + <tr> + <td> + SYMBOL (name) + </td> + <td> + 24 + </td> + <td> + unlimited * + </td> + </tr> + <tr> + <td> + SYMBOL (value) + </td> + <td> + 50 + </td> + <td> + 1 per symbol + </td> + </tr> + <tr> + <td> + TABLE + </td> + <td> + 50 + </td> + <td> + unlimited * + </td> + </tr> + <tr> + <td> + GROUP + </td> + <td> + Octal Value + </td> + <td> + 1 + </td> + </tr> + <tr> + <td> + PARENT + </td> + <td> + 12 + </td> + <td> + 1 + </td> + </tr> +</table> + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Note</strong></font></center><hr + size=1 noshade> +* = Attributes which are "unlimited" are limited by virtual memory +available to the user. Very large INI files with large numbers of +logicals or symbols may exhaust virtual memory. </td> + </tr> +</table> +</center> + +<a name="heading_11.5"><h1>11.5 EMIS_SELECT Compatibility</h1></a> + +<p> +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. + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Note</strong></font></center><hr + size=1 noshade> +SETUPENV/EMIS can be used even if the DAS has not created an +OECN$SETUP.INI file. </td> + </tr> +</table> +</center> + +<p> +When SETUPENV/EMIS reads the OECN$EMIS_DBS, it creates a special entry +which is equavalent to: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + 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" +</pre> +</table> + +<p> +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. + +<p> +One implication of the above is that the /CATEGORIES qualifier can be +used to select specific reporting periods. For example: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + $ SETUPENV/EMIS/NEXT/CATEGORIES="*RP_N*" +</pre> +</table> + +<p> +Would select the next EMIS database for reporting period N. + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Note</strong></font></center><hr + size=1 noshade> + SETUPENV will invoke the DA Site's EMIS_SELECT_EPILOGUE procedure if it + exists. However, the EMIS_SELECT_PROLOGUE is not supported. DA Sites + that depend on the prologue procedure should contact the SSDT for a + work around. </td> + </tr> +</table> +</center> + +<a name="heading_11.5.1"><h2>11.5.1 Converting OECN$EMIS_DBS to OECN$SETUP</h2></a> + +<p> +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. + +<p> +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. + +<p> +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. + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Note</strong></font></center><hr + size=1 noshade> + At the time of this writing, the original EMIS_SELECT.COM procedure is + still invoked by the EMIS_SELECT menu option. Therefore, if you wish to + switch to SETUPENV immediately, you would have to modify the EMIS menu + or customize the EMIS_SELECT.COM procedure. In the future, + EMIS_SELECT.COM will be modified by the SSDT to use SETUPENV/EMIS + instead of the current DCL procedure. </td> + </tr> +</table> +</center> + +<a name="heading_11.6"><h1>11.6 NOACSC Compatiblity</h1></a> + +<p> +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. + +<p> +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. + +<p> +Symbols may be established for each of the utilities to invoke SETUPENV +in the appropriate compatibility mode: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + USE :== $OECN$:SETUPENV/USE + BUNNY :== $OECN$:SETUPENV/BUNNY + FROG :== $OECN$:SETUPENV/FROG +</pre> +</table> + +<p> +This should allow SETUPENV to be used without modifying any existing +command procedures. + +<a name="heading_11.6.1"><h2>11.6.1 USE Compatibliity</h2></a> + +<p> +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. + +<p> +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. + +<table border=3> + <tr> + <th align=center>Qualifier </th> + <th align=center>SETUPENV Implementation </th> + </tr> + <tr> + <td> + /OUTPUT + </td> + <td> + Not implemented + </td> + </tr> + <tr> + <td> + /ARCHIVE=nnnn + </td> + <td> + /ARCHIVE=nnnn + </td> + </tr> + <tr> + <td> + /HOME + </td> + <td> + /RESET + </td> + </tr> + <tr> + <td> + /PRIMARY_RUN + </td> + <td> + /LOGIN=(SIS,INFOHIO,USERNAME=2)/NOPROMPT + </td> + </tr> +</table> + +<h2>Notable Differences:</h2> + +<ul> + <li>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. + <li>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. + <li>SETUPENV does not set PMDF_SIGNATURE. Sites depending on this + should add the following line to SYLOGIN: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + + $ if f$search("SYS$LOGIN:PMDF_SIGNATURE.DOC").nes."" - + then define PMDF_SIGNATURE "@SYS$LOGIN:PMDF_SIGNATURE.DOC" + +</pre> +</table> + +</ul> + +<a name="heading_11.6.2"><h2>11.6.2 BUNNY Compatibility</h2></a> + +<p> +If /BUNNY is specified as the first qualifier to SETUPENV, then the +original BUNNY qualifiers are accepted. + +<p> +The SETUPENV defaults when /BUNNY is specified are: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + $ SETUPENV/BUNNY/PROMPT/EMIS=NORESTRICT_IRNS +</pre> +</table> + +<p> +These defaults are affected by the original BUNNY qualifiers per the +following table. +<p> + +<table border=3> + <tr> + <th align=center>Qualifier </th> + <th align=center>SETUPENV Implementation </th> + </tr> + <tr> + <td> + /ARCHIVE=nnnn + </td> + <td> + /ARCHIVE=nnnn + </td> + </tr> + <tr> + <td> + /CURRENT_BUILDING + </td> + <td> + not implemented + </td> + </tr> + <tr> + <td> + /EMIS + </td> + <td> + not implemented (logicals defined by entry) + </td> + </tr> + <tr> + <td> + /INFOHIO + </td> + <td> + /LOGIN=INFOHIO + </td> + </tr> + <tr> + <td> + /PRIMARY_RUN + </td> + <td> + /LOGIN=(SIS,INFOHIO)/NOPROMPT + </td> + </tr> + <tr> + <td> + /LOGICAL_ONLY + </td> + <td> + /NOPROMPT + </td> + </tr> + <tr> + <td> + /RESTRICT_IRNS + </td> + <td> + EMIS=RESTRICT_IRNS + </td> + </tr> + <tr> + <td> + /SCHEDULE_BUILDER + </td> + <td> + Chains to SIS$EXE:SISMENU_CMSB.EXE + </td> + </tr> +</table> + +<p> +For interactive processes, if neither /PRIMARY_RUN nor /LOGICALS_ONLY +is specified then SETUPENV/BUNNY chains to SISMENU.EXE, unless +overridden by /SCHEDULE_BUILDER. + +<h2>Notable Differences:</h2> + +<ul> + <li>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. + <li>/CURRENT_BUILDING is not supported. SETUPENV does not have ability + to set an entry based on the value of an existing logical. + <li>If /ARCHIVE is specified without a value, the default is the first + ARCHIVE attribute for the selected entry. +</ul> + +<a name="heading_11.6.3"><h2>11.6.3 FROG Compatibility</h2></a> + +<p> +If /FROG is specified as the first qualifier to SETUPENV, then the +original FROG qualifiers are accepted. + +<p> +The SETUPENV defaults when /BUNNY is specified are: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + $ SETUPENV/FROG/PROMPT +</pre> +</table> + +<p> +These defaults are affected by the original BUNNY qualifiers per the +following table. + +<table border=3> + <tr> + <th align=center>Qualifier </th> + <th align=center>SETUPENV Implementation </th> + </tr> + <tr> + <td> + /CURRENT_BUILDING + </td> + <td> + Not implemeneted + </td> + </tr> + <tr> + <td> + /LOGICALS_ONLY + </td> + <td> + /NOPROMPT + </td> + </tr> + <tr> + <td> + /PRIMARY_RUN + </td> + <td> + LOGIN=INFOHIO + </td> + </tr> + <tr> + <td> + /PRINTER + </td> + <td> + /PRINTER (see below) + </td> + </tr> + <tr> + <td> + /OPAC=RESTRICTED + </td> + <td> + Chains to "@LIS_MGR:OPAC" + </td> + </tr> + <tr> + <td> + /OPAC=UNRESTRICTED + </td> + <td> + Chains to "@LIS_MGR:OPAC R" + </td> + </tr> +</table> + +<p> +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 + +<h2>Notable Differences:</h2> + +<ul> + <li>/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. + <li>For non-DAS staff, SYS$PRINT is unconditionally assigned to + LCL$PRINT as a job logical (which might be occluded). + <li>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. +</ul> + +<p> + +<a name="heading_11.7"><h1>11.7 OECN$SETUPENV API</h1></a> +SETUPENV provides a callable API which can be used by programs to +select entries. The API parallels the qualifier functions and syntax. + +<a name="heading_11.7.1"><h2>11.7.1 Working Storage Field(s)</h2></a> + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Note</strong></font></center><hr + size=1 noshade> + Picture for string field are maximum sizes that will be used by + OECN$SETUPENV. The string fields are based by descriptor, so the field + sizes are not required to be the exact size. </td> + </tr> +</table> +</center> + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + + 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). +</pre> +</table> + +<p> + +<a name="heading_11.7.2"><h2>11.7.2 COBOL Call Arguments</h2></a> + +<table border=0> + <tr> + <td> + <br> +<pre> + 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. +</pre> +</table> + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Note</strong></font></center><hr + size=1 noshade> + The arguments passed by descriptor may be OMITTED if the return value + is not desired. However, the argument list must not be shortened, that + is, the caller should explictly include the OMITTED keyword. </td> + </tr> +</table> +</center> + +<a name="heading_11.7.3"><h2>11.7.3 Argument Descriptions:</h2></a> + +<blockquote> +<strong>WS-FUNCTION (read)</strong> + + <blockquote> + Indicates the function to perform. Behavior matches the corresponding + DCL qualifiers. + <br>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. + </blockquote> +<br> + <br><strong>WS-FLAGS</strong> + + <blockquote> + 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. + <br>The following flags are applicable when the LOGIN-DEFAULTS function + is requested: + </blockquote> + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + 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 +</pre> +</table> + +<br> + <br><strong>WS-SELECT-DB (modify, by descriptor)</strong> + + <blockquote> + 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. + </blockquote> +<br> + <br><strong>WS-SEL-TYPE (read, by descriptor)</strong> +<br> + <br><strong>WS-SEL-CATEGORIES (read, by descriptor)</strong> + + <blockquote> + Values to restrict entries by type and/or categories. + <br>Same as /TYPE and /CATEGORIES qualifiers. + </blockquote> +<br> + <br><strong>WS-SEL-APPLICATION (read, by descriptor)</strong> + + <blockquote> + Value to select by application. Same as /APPLICATION qualifier. + </blockquote> +<br> + <br><strong>WS-TYPE (write, by descriptor)</strong> +<br> + <br><strong>WS-DESC (write, by descriptor)</strong> +<br> + <br><strong>WS-IRN (write, by descriptor)</strong> +<br> + <br><strong>WS-CATEGORIES (write, by descriptor)</strong> + + <blockquote> + Return values which describe the entry. Same values that are also + placed in the OECN$SETUP_CURRENT Logical. + </blockquote> +<br> + <br><strong>WS-APPLICATIONS (write, by descriptor)</strong> + + <blockquote> + Space delimited list of appliations associated with the current entry. + </blockquote> +<br> + <br><strong>WS-PROMPT-STRING (write, by descriptor)</strong> + + <blockquote> + 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. + </blockquote> +<br> + <br><strong>WS-RELATIONSHIPS (write, by descriptor)</strong> + + <blockquote> + 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. + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Note</strong></font></center><hr + size=1 noshade> + Calling routines should not assume that only these three types of + relationships exist. Future versions of the API may return other + relationships. </td> + </tr> +</table> +</center> +<br> + <br><strong>WS-ARCHIVE</strong> + + <blockquote> + Contains code of archive if one was selected. + </blockquote> +</blockquote> + +<a name="heading_11.7.4"><h2>11.7.4 Return Status</h2></a> + +<p> +OECN$SETUP returns one of the following conditions: + +<table border=3> + <tr> + <td> + OECN__NORMAL + </td> + <td> + = + </td> + <td> + Function completed successfully (Item selected or reset) + </td> + </tr> + <tr> + <td> + OECN__NOMORE + </td> + <td> + = + </td> + <td> + When using "next" function, no more matching entries were found. + </td> + </tr> + <tr> + <td> + OECN__NOTFOUND + </td> + <td> + = + </td> + <td> + Specified entry was not found. + </td> + </tr> + <tr> + <td> + OECN__INVNEXT + </td> + <td> + = + </td> + <td> + Invalid combination of TYPE and current entry for NEXT function. Must + specify a starting entry or valid select type. + </td> + </tr> +</table> + +<a name="heading_11.7.5"><h2>11.7.5 Description</h2></a> + +<p> +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: + +<ol start=1 > + <li>Does not simulate /USE, /BUNNY or /FROG behaviors. Those qualifiers + are handled by the SETUPENV utility and are not exposed to the callable + interface. + <li>Does not modify the Menu or DCL prompts (a string is returned for + setting the prompt if desired). + <li>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). + <li>Does not implement the function of /PRINTER +</ol> + +<p> + +<hr size=5> +<a name="sysman_ump_chap"><h1>Chapter 12<br>Installing and Using UMP - User Mail Profile System</h1></a> + +<a name="heading_12.1"><h1>12.1 Overview</h1></a> + +<p> + 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. + +<a name="heading_12.1.1"><h2>12.1.1 Feature List</h2></a> + +<p> +UMP provides the following features: + +<ul> + <li>Ability to add/modify user profiles. + <li>Allows end-user to modify their own profile. + <li>Permits 'group managers' to manage other user profiles within their + group + <li>Imports an existing distribution list and creates a basic user + profile (NM or PMDF style distribution lists). + <li>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. + <li>Exports user profiles into the following formats: + + <blockquote> + - NM + <br>- PMDF style distribution lists + <br>- PMDF DIRECTORY DAEMON format + </blockquote> + <li>Handles OECN standard distribution lists and allows local + distribution lists to be added. + <li>Includes a utility to create distribution lists based on VMS + identifiers. + <li>Includes a utility to check UMP profiles against SYSUAF. + <li>Includes a utility to run during login to determine if user has + modified their own profile. + <li>Includes a utility to transmit UMP data into the CSO white pages + directory. + <li>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. +</ul> + +<a name="heading_12.1.2"><h2>12.1.2 Web Attachments for OECN state-wide mail</h2></a> + +<p> +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. + +<p> + 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. + +<p> + 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. + +<p> + 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. + +<a name="heading_12.1.2.1"><h3>12.1.2.1 Enabling Web Attachments</h3></a> + +<p> +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. + +<p> + 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. + +<a name="heading_12.1.3"><h2>12.1.3 Files</h2></a> + +<p> +The following sections describe the files used and produced by the UMP +system. +<p> +<strong>Files and Procedures Used</strong> +<br> + +<table border=3> + <tr> + <th align=center>File/Procedure </th> + <th align=center>Use </th> + </tr> + <tr> + <td> + OECN$UMP_LOCAL.INI + </td> + <td> + Contains A-site specific information and list codes. + </td> + </tr> + <tr> + <td> + OECN$UMP_STANDARD.INI + </td> + <td> + Contains OECN_wide list codes and definitions. + </td> + </tr> + <tr> + <td> + IMPORT_NM_LISTS.COM + </td> + <td> + Used to import data from NM style distribution lists into user profiles. + </td> + </tr> + <tr> + <td> + IMPORT_PMDF_LISTS.COM + </td> + <td> + Used to import data from PMDF style distribution lists into user + profiles. + </td> + </tr> + <tr> + <td> + EXPORT_LISTS.COM + </td> + <td> + Used to generate both NM and PMDF style distribution lists. + </td> + </tr> + <tr> + <td> + EXPORT_DD.COM + </td> + <td> + Used to generate a file suitable for loading into a PMDF DIRECTORY + DAEMON database. + </td> + </tr> + <tr> + <td> + UMP_SEND_CSO.COM + </td> + <td> + Used to transmit UMP data to the CSO white pages directory. + </td> + </tr> +</table> +<p> +<strong>Files Created</strong> +<br> + +<p> + The table below describes the files created by UMP. Unless otherwise + specified, the files are created in OECN$UMP:. + +<table border=3> + <tr> + <th align=center>File </th> + <th align=center>Description </th> + </tr> + <tr> + <td> + MAIL_*_A.DIS + </td> + <td> + One file for each distribution list. This file contains addresses of + users who have requested to receive original attachments sent to an + OECN list.. + </td> + </tr> + <tr> + <td> + MAIL_*_W.DIR + </td> + <td> + 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. + </td> + </tr> + <tr> + <td> + MAIL_ALIASES.DAT + </td> + <td> + 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. + </td> + </tr> + <tr> + <td> + USER_ALIASES.TXT + </td> + <td> + Alias file defining aliases for UMP remote users to create centralized + naming. This file is intended to be loaded into the PMDF alias database. + </td> + </tr> + <tr> + <td> + USER_RESERVE.TXT + </td> + <td> + File containing reversing entries for users to create centralized + naming. This file is intended to be loaded into the PMDF reverse + database. + </td> + </tr> +</table> + +<a name="heading_12.2"><h1>12.2 UMP Menu and Profile Screen</h1></a> + +<p> +The program may be executed by typing: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +$RUN OECN$:UMP +</pre> +</table> + +<p> +at the $ prompt or from the menu system, type: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +Menu>UMP +</pre> +</table> + +<p> +<strong>The Main UMP Menu</strong> +<br> + +<p> +The following menu will appear: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + + +___________________________________________________________________ +| | +| 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 | +|_________________________________________________________________| + + + +</pre> +</table> + +<p> +<strong>Profile Screen</strong> +<br> + +<p> +When you execute the UMP program and select the MAINTAIN option, a User +Mail Profile screen similar to the following will appear: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + + +___________________________________________________________________________ +| | +| 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 | +|_________________________________________________________________________| + + +</pre> +</table> + +<p> +<strong>EMAIL Lists</strong> +<br> + +<p> +In order to view the Email lists you currently subscribe to, press the +<kbd>[Email Lists]</kbd> key. A screen similar to the following will +appear giving both OECN statewide and local distribution lists. + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + +___________________________________________________________________________ +| 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 | +| | +|_________________________________________________________________________| + +</pre> +</table> + +<p> + 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. + +<p> +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 <kbd>[Accept]</kbd> key. +<p> +<strong>Table of Email Distribution Lists</strong> +<br> + +<p> +In order to see the available distribution lists, press the <kbd>[Show +All Lists]</kbd> key. A set of screens such as the following will +appear: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + + +___________________________________________________________________________ +| | +| 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 | +|_________________________________________________________________________| + + +</pre> +</table> + +<a name="heading_12.3"><h1>12.3 Startup Procedure</h1></a> + +<p> + Follow the steps below to install UMP on your system: + +<ol start=1 > + <li>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. + <li>Use OECN_INSTALL and INSTALL PACKAGE as usual to install the OECN + package. + <li>If installing for the first time, copy OECN$UMP_LOCAL.INI to + OECN$UMP with world:read protection. +<br> + <br> 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. + <li>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. +</ol> + +<p> + +<a name="heading_12.4"><h1>12.4 Loading Initial Data</h1></a> + Load existing distribution lists. If using NM style distribution lists, + then use: +<br> +$ @OECN$:IMPORT_NM_LISTS + +<p> + If using PMDF style lists created by SWOCA's PUBDOM OECNMAIL utilities, + then use: +<br> +$ @OECN$:IMPORT_PMDF_LISTS + +<p> + 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. + +<p> + After running the import, the protection on the UMP*.IDX files should + be set to W:RW. + +<p> + 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. + +<a name="heading_12.5"><h1>12.5 Importing Other Lists</h1></a> + +<p> + 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. + +<p> + 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: +<br> + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +$ UMPIMPORT :== $OECN$:UMPIMPORT +$ UMPIMPORT {NM|PMDF} {code} {file} +</pre> +</table> + +<p> + 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. +<p> + +<a name="heading_12.6"><h1>12.6 INI File Commands</h1></a> +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. <p> + +<table border=3> + <caption><a name="Table_12-1"><strong>Table 12-1 Table of INI File Commands</strong></a></caption> + <tr> + <th align=center> </th> + <th align=center>Command </th> + <th align=center> </th> + <th align=center>Fields </th> + <th align=center>Explanation </th> + </tr> + <tr> + <td> + * + </td> + <td> + SET_ASITE + </td> + <td> + = + </td> + <td> + "{Asite}" + </td> + <td> + A-site acronym. Required field. + </td> + </tr> + <tr> + <td> + * + </td> + <td> + SET_NODE + </td> + <td> + = + </td> + <td> + "{Node}" + </td> + <td> + Default DECnet node, cluster prefered. Required field. + </td> + </tr> + <tr> + <td> + * + </td> + <td> + SET_DOMAIN + </td> + <td> + = + </td> + <td> + "{Domain}" + </td> + <td> + Default domain. Used as default for user profile and PMDF aliases. For + example, SET_DOMAIN = "NWOCA.ORG". Required field. + </td> + </tr> + <tr> + <td> + * + </td> + <td> + SET_USER_TYPE + </td> + <td> + = + </td> + <td> + "{Code}" + </td> + <td> + Default for "User Type" field. + </td> + </tr> + <tr> + <td> + * + </td> + <td> + LOCAL_LIST_PREFIX + </td> + <td> + = + </td> + <td> + "{Prefix}" + </td> + <td> + Alias prefix for local distribution lists. Example, LOCAL_LIST_PREFIX = + "Local_". May be null if local lists are not to be prefixed. + </td> + </tr> + <tr> + <td> + + </td> + <td> + LOCAL_HOST + </td> + <td> + = + </td> + <td> + "{hostname}" + </td> + <td> + 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. + </td> + </tr> + <tr> + <td> + * + </td> + <td> + PROCESS_CHANNEL + </td> + <td> + = + </td> + <td> + "{process_channel_name}" + </td> + <td> + 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. + </td> + </tr> + <tr> + <td> + * + </td> + <td> + DIRECTORY_DOMAIN + </td> + <td> + = + </td> + <td> + "{directory_daemon_domain}" + </td> + <td> + 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. + </td> + </tr> + <tr> + <td> + + </td> + <td> + REWRITE + </td> + <td> + = + </td> + <td> + "{user@host}","{To_Domain}" + </td> + <td> + 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 + </td> + </tr> + <tr> + <td> + + </td> + <td> + CSO_REWRITE + </td> + <td> + = + </td> + <td> + Synonym for REWRITE + </td> + <td> + + </td> + </tr> + <tr> + <td> + * + </td> + <td> + ERRORS_TO + </td> + <td> + = + </td> + <td> + "{Email_Address}" + </td> + <td> + Address for "errors-to" parameter on mailing lists. If not preset, the + "errors_to" address defaults to "postmaster". + </td> + </tr> + <tr> + <td> + * + </td> + <td> + EMPTY_ADDRESS + </td> + <td> + = + </td> + <td> + "{Email_Address}" + </td> + <td> + 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. + </td> + </tr> + <tr> + <td> + * + </td> + <td> + ENABLE_OECN_WEBATTACH + </td> + <td> + = + </td> + <td> + {YES|NO} + </td> + <td> + 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. + </td> + </tr> + <tr> + <td> + * + </td> + <td> + OECN_WEBATTACH_DEFAULT + </td> + <td> + = + </td> + <td> + {YES|NO} + </td> + <td> + 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. + </td> + </tr> + <tr> + <td> + * + </td> + <td> + ALLOW_USER_ALIAS + </td> + <td> + = + </td> + <td> + {YES|NO} + </td> + <td> + 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. + </td> + </tr> + <tr> + <td> + + </td> + <td> + LISTPARMS + </td> + <td> + = + </td> + <td> + "{named parameter}" + </td> + <td> + 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. + </td> + </tr> + <tr> + <td> + * + </td> + <td> + PROTECT_SITE_INFO + </td> + <td> + = + </td> + <td> + [YES|NO] + </td> + <td> + Protect "Site Info" field in UMP. The default is "YES". + </td> + </tr> + <tr> + <td> + + </td> + <td> + TYPE + </td> + <td> + = + </td> + <td> + {Type},"{Description}" + </td> + <td> + 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. + </td> + </tr> + <tr> + <td> + + </td> + <td> + DEFINE_CODE + </td> + <td> + = + </td> + <td> + [Type-],{Code},"{Description}", {List_Name},[User_Modifiable], + [Master_Code] + </td> + <td> + 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. + <p>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,... + <p>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. + </td> + </tr> + <tr> + <td> + + </td> + <td> + TYPE_RESTRICT + </td> + <td> + = + </td> + <td> + {Type},{Method},{Value} + </td> + <td> + 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. + </td> + </tr> + <tr> + <td> + + </td> + <td> + CONVERT + </td> + <td> + = + </td> + <td> + {From_Code},{To_Code} + </td> + <td> + 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. + </td> + </tr> + <tr> + <td> + + </td> + <td> + NM_MAP + </td> + <td> + = + </td> + <td> + {From_Code},{To_Code} + </td> + <td> + The command causes codes to be mapped to produce a single old-style NM + distribution list for compatibility with NM_SEARCH. + </td> + </tr> + <tr> + <td> + + </td> + <td> + SITE + </td> + <td> + = + </td> + <td> + "{Domain}",{CSO_ID} + </td> + <td> + 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. + </td> + </tr> +</table> +<hr> +<blockquote> +* This command can appear at most one time in the Local INI file. +</blockquote> +<hr> +<p> + +<a name="heading_12.7"><h1>12.7 Export NM and PMDF Style Lists</h1></a> + 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 <a href="oecn10_sysman_handbook_full.html#exam_build_proc">Section 12.18</a> for an + example procedure which takes advantage of most of UMP's features. + +<p> + To run the procedure: +<br> + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +$ @OECN$:EXPORT_LISTS "{options}" +</pre> +</table> + +<p> + The P1 parameter should specify one or more of the following options + separated by commas: + +<table border=3> + <tr> + <th align=center>Option </th> + <th align=center>Description </th> + </tr> + <tr> + <td> + REBUILD + </td> + <td> + 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. + </td> + </tr> + <tr> + <td> + MERGE + </td> + <td> + (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. + </td> + </tr> + <tr> + <td> + + </td> + <td> + Note: REBUILD and MERGE are mutually exclusive. + </td> + </tr> + <tr> + <td> + USER + </td> + <td> + 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. + </td> + </tr> + <tr> + <td> + DEFER + </td> + <td> + 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). + </td> + </tr> +</table> + +<p> + 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. + +<p> + 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. + +<p> + 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: + +<ul> + <li>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. + <li>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:. +</ul> + +<a name="heading_12.7.1"><h2>12.7.1 Centralized Naming</h2></a> + +<p> + 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. + +<a name="heading_12.7.1.1"><h3>12.7.1.1 Remote Mail Boxes</h3></a> + +<p> + 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. + +<p> + Examples of "remote" users include: + +<ul> + <li>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) + <li>Users who's mailbox exists on a school district mail server or + another DAS mail server. + <li>Users who's mailbox is in PMDF popstore +</ul> + +<p> +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. + +<p> + 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. + +<p> + 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. + +<p> + 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. + +<p> + 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). + +<a name="heading_12.7.1.2"><h3>12.7.1.2 User Aliases</h3></a> + +<p> + 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. + +<p> + 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. + +<p> + 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. + +<p> +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. + +<p> + 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. + +<a name="heading_12.7.1.2.1"><h4>12.7.1.2.1 Implementing User Aliases</h4></a> + +<p> + The following steps must be performed in order to activate the user + alias and address reversal using UMP: + +<ol start=1 > + <li>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. + <li>Set ALLOW_USER_ALIAS to YES in OECN$UMP_LOCAL.INI. This flag + enables the 'Alias' and 'From' fields in UMP. + <li>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 <a href="oecn10_sysman_handbook_full.html#exam_build_proc">Section 12.18, Example Procedure for Periodic Rebuilds</a> for an example procedure which + invokes EXPORT_LISTS.COM. +</ol> + +<a name="heading_12.8"><h1>12.8 Distribution List Codes</h1></a> + +<p> + 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. + +<p> + This version uses an 8 character code in the following format: +<br> +TT-CCCCCC + +<p> + Where TT is the distribution list "type" (or category) and CCCCCC is + the distribution list code. The following types are predefined by UMP: + +<table border=3> + <tr> + <td> + + </td> + <td> + 01 + </td> + <td> + OECN-wide user distribution lists + </td> + </tr> + <tr> + <td> + + </td> + <td> + 02 + </td> + <td> + OECN DAS staff-only lists + </td> + </tr> + <tr> + <td> + + </td> + <td> + 10 + </td> + <td> + Default type for lists defined by DAS + </td> + </tr> +</table> + +<p> + 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. + +<p> + Type 10 is predefined and available for DAS use. To add additional + types add a line to the local ini file, like: +<br> +TYPE=tt,"description" + +<p> + For example: +<br> +TYPE=11,"NWOCA Staff Lists" + +<p> + Once a type has been defined, you may use the type in subsequent + DEFINE_CODE lines, for example: +<br> +DEFINE_CODE = 11-STFRCP, "Staff Recipes", STAFF_RECIPIES +<br> +DEFINE_CODE = 11-STFJOK, "Staff Jokes", STAFF_JOKES + +<p> + 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". +<p> +<strong>Restricting Types to Particular Users</strong> +<br> + +<p> + 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. + +<p> + 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. + +<p> + 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. + +<p> + To apply a restriction to a type value, use one of the following + commands in the local ini file: +<br> + +<table border=3> + <tr> + <td> + TYPE_RESTRICT=tt,SUBSCRIBED,tt-cccccc + </td> + <td> + Restricts type tt to users who are also subscribed to list tt-ccccc. + </td> + </tr> + <tr> + <td> + TYPE_RESTRICT=tt,IRN,nnnnnn + </td> + <td> + Restrict type to users who have a district or building IRN matching + nnnnnn + </td> + </tr> + <tr> + <td> + TYPE_RESTRICT=tt,TYPE,xxxx + </td> + <td> + Restrict type to users with a 'user type' field matching xxxxx. + </td> + </tr> + <tr> + <td> + TYPE_RESTRICT=tt,COUNTY,xxxx + </td> + <td> + Restrict type to users with a 'county' field matching xxxx. + </td> + </tr> + <tr> + <td> + TYPE_RESTRICT=tt,USERNAME,wildcard + </td> + <td> + Restrict type to users with a 'username' field matching wildcard mask. + </td> + </tr> +</table> + +<p> + 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. + +<p> + 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: +<br> + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +TYPE_RESTRICT=11, SUBSCRIBED, 01-STF +</pre> +</table> + +<p> + This will restrict all type 11 lists to users who are also subscribed + to the standard DAS staff list. + +<a name="heading_12.9"><h1>12.9 Auto Conversion of Distribution List Codes (Optional)</h1></a> + +<p> + 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. + +<p> + To help facilitate this, an optional command is available for the LOCAL + INI file called CONVERT. The CONVERT command takes the following form: +<br> +<em>CONVERT={old_code},{new_code}</em> + +<p> + For example, to convert an existing code of 10-SEM (Staff EMIS) to + 11-STFEMS, place the following line in the LOCAL.INI: +<br> +CONVERT=10-SEM, 11-STFEMS + +<p> + 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. + +<p> + 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. + +<p> + 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. + +<p> + 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. + +<a name="heading_12.10"><h1>12.10 Defining Local Distribution Lists</h1></a> + +<p> +To define a local distribution list, you need to add several additional +lines to the OECN$UMP_LOCAL.INI file. + +<p> +You will probally need to use the ini commands: +<br> +LOCAL_LIST_PREFIX, TYPE, TYPE_RESTRICT, DEFINE_CODE +<p> +<strong>Example 1</strong> +<br> + +<p> +The following example illustrates how to define a local distribution +list for payroll clerks. + +<p> +Add the following lines to the OECN$UMP_LOCAL.INI file: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +TYPE = 12,"Local Payroll Clerks" +DEFINE_CODE = 12-PAYCLK,"Payroll Clerks",PAYROLL_CLERK +</pre> +</table> + +<p> +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. +<p> +<strong>Example 2</strong> +<br> + +<p> +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. + +<p> +Add the following lines to the OECN$UMP_LOCAL.INI file: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + +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 +</pre> +</table> + +<p> +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. +<br> +-- LOCAL STAFF LISTS -- +<br> +---LOCAL_STAFF_JOKES Staff Jokes +<br> +---LOCAL_FISCAL_JOKES Fiscal Jokes +<br> +---LOCAL_PROGRAMER_JOKES Programmer Jokes +<br> +---LOCAL_EMIS_JOKES EMIS Jokes +<br> + +<p> +Users who are not subscrbed to the list 01-STF would see not entries +for "Local Staff Lists" including the heading itself. + +<p> +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. + +<a name="heading_12.11"><h1>12.11 Profile Group Management</h1></a> + +<p> + UMP provides the ability to segregate profiles into <strong>management + groups</strong> 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. + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Note</strong></font></center><hr + size=1 noshade> + 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. </td> + </tr> +</table> +</center> + +<p> + 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. + +<p> + 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: + +<table border=3> + <tr> + <td> + * + </td> + <td> + Any sequence of zero or more characters + </td> + </tr> + <tr> + <td> + % + </td> + <td> + Exactly one character + </td> + </tr> + <tr> + <td> + # + </td> + <td> + Exactly one numeric character + </td> + </tr> + <tr> + <td> + @ + </td> + <td> + Exactly one alphabetic character + </td> + </tr> +</table> + +<p> + 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. + +<p> + 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. + +<p> + 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. + +<a name="heading_12.12"><h1>12.12 Export DIRECTORY DAEMON File (optional)</h1></a> + +<p> + 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. + +<p> + 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": + +<table border=3> + <tr> + <td> + SMITH + </td> + <td> + SMITH@nwoca.org + </td> + </tr> + <tr> + <td> + dave.smith + </td> + <td> + SMITH@po.NWOCA.ORG + </td> + </tr> + <tr> + <td> + smith.dave + </td> + <td> + SMITH@po.NWOCA.ORG + </td> + </tr> + <tr> + <td> + d.smith + </td> + <td> + SMITH@po.NWOCA.ORG + </td> + </tr> + <tr> + <td> + smith.d + </td> + <td> + SMITH@po.NWOCA.ORG + </td> + </tr> +</table> + +<p> + 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. + +<p> + 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: +<br> +<em>DIRECTORY_DOMAIN=pseudo.domain</em> + +<p> + See the PMDF System Adminstrators Guide for more information about the + directory daemon, channels and pseudo-domains. + +<a name="heading_12.13"><h1>12.13 Submit UMP Data to OECN CSO Database</h1></a> + +<p> + 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. + +<p> + 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. + +<p> + 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. + +<p> + 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. + +<p> + 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: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + REWRITE=*,"pseudo_domain" +</pre> +</table> + +<p> + Where "pseudo_domain" is the domain name of your directory channel, for + example, NWOCA uses the following line: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + REWRITE=*,"po.nwoca.org" +</pre> +</table> + +<p> + 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). + +<a name="heading_12.14"><h1>12.14 Master List/Sub-list Handling</h1></a> + +<p> + 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. + +<p> + 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. + +<p> + 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. + +<p> + If a user is coded on one of the sub-lists, they will be placed on that + sub-list and the corresponding master list. + +<p> + These changes provides two advantages: + +<ol start=1 > + <li>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. + <li>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. +</ol> + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Note</strong></font></center><hr + size=1 noshade> +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. </td> + </tr> +</table> +</center> + +<a name="heading_12.15"><h1>12.15 UMPCHECK - Verifying UMP Profiles against SYSUAF (Optional)</h1></a> + +<p> + 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: +<br> +<em>$ UMPCHECK {CHECK|DELETE|DELETE/CONFIRM} [nodes,...]</em> + +<p> + The first parameter is the function to perform: + +<table border=3> + <tr> + <td> + CHECK + </td> + <td> + -- + </td> + <td> + Verify the UMP profiles against the SYSUAF and report usernames which + are invalid, disusered or dismailed. + </td> + </tr> + <tr> + <td> + DELETE + </td> + <td> + -- + </td> + <td> + Unconditionally deletes local usernames which are invalid, disusered or + dismailed. + </td> + </tr> + <tr> + <td> + DELETE/ + <br> CONFIRM + </td> + <td> + -- + </td> + <td> + Same as DELETE but prompts whether each username should be deleted or + not. + </td> + </tr> +</table> + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Note</strong></font></center><hr + size=1 noshade> + The function must be specified exactly as shown above without + abbreviation and there may not be spaces between DELETE and /CONFIRM. + </td> + </tr> +</table> +</center> + +<p> + 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. +<p> + +<a name="heading_12.16"><h1>12.16 UMP_LOGIN - To Prompt Users to Enter Profiles During Login (Optional)</h1></a> + 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. + +<p> + 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. + +<p> + 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. + +<a name="heading_12.17"><h1>12.17 UMPID2DIS - Creating Distribution Lists from VMS Identifiers (Optional)</h1></a> + +<p> + 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. + +<p> + 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. + +<p> + To create a distribution list for users holding a given identifier, use + the following commands: +<br> +$ ID2DIS :== $OECN$:UMPID2DIS +<br> +$ ID2DIS {identifier},... {distribution_list_file} + +<blockquote> + 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. +<br> + <br> "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. +</blockquote> + +<p> + Only users that meet the following criteria will be output to the list: + +<table border=3> + <tr> + <td> + + </td> + <td> + 1) + </td> + <td> + The user holds one or more of the specified identifiers. + </td> + </tr> + <tr> + <td> + + </td> + <td> + 2) + </td> + <td> + The UAF flags DISUSER and DISMAIL are not set. + </td> + </tr> + <tr> + <td> + + </td> + <td> + 3) + </td> + <td> + The username has a valid UMP profile. + </td> + </tr> +</table> + +<p> + 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. + +<p> + For example, NWOCA could use the following commands to create a + distribution list for all NWOCA USPS users: +<br> +$ ID2DIS := $OECN$:UMPID2DIS +<br> +$ +<br> +$ ID2DIS OECN_USPS NWOCA_USPS +<br> +$ +<br> +$ PMDF DB +<br> + open pmdf_alias_database +<br> + override on +<br> + add "nwoca_usps" "nwoca_usps-list@reprocess.nwoca.org" +<br> + add "nwoca_usps-list" "<oecn$ump:nwoca_usps.dis,*,*,postmaster,*, + USPS" +<br> +$ EXIT + +<a name="exam_build_proc"><h1>12.18 Example Procedure for Periodic Rebuilds</h1></a> + +<p> + 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. + +<p> + 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. + +<p> + 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. + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + + +$!+ +$! 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 + + +</pre> +</table> + +<p> + +<a name="heading_12.19"><h1>12.19 Multiple Non-Clustered Systems</h1></a> + DAS's with a single VMS system, or a single VMS cluster, need not be + concerned with this section. + +<p> + 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. + +<p> + 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. + +<p> + Use the following procedure to establish remote access to the UMP + system. + +<ol start=1 > + <li>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. + <li>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. + <li>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. + <li>On the server define the OECN$UMP logical as normal. + <li>On the server use AUTHORIZE to define network proxies into the + server for each remote system. For example: +<br> +UAF> ADD/PROXY node::* UMP_SERVER <br> Where "node" is the DECnet +node name of the remote node. <br> This will give any user on one of +your non-server nodes proxy access to the UMP_SERVER. + <li>On each node (client) that you want to have access to the server, + define OECN$UMP as follows (assuming MAIN:: is the server): +<br> +$ DEFINE OECN$UMP "MAIN""UMP_SERVER""::OECN$UMP:" <br> 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. + <li>Copy the *.INI files from the server to the client system. and + define the following logicals: +<br> +$ DEFINE OECN$UMP_STANDARD dev:[dir]OECN$UMP_STANDARD.INI +<br> +$ DEFINE OECN$UMP_LOCAL dev:[dir]OECN$UMP_LOCAL.INI <br> 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. +</ol> + +<p> + 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. + +<a name="heading_12.20"><h1>12.20 Programming Considerations</h1></a> + +<p> + 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. + +<p> + The UMP data is stored in two files in OECN$UMP: + +<table border=3> + <tr> + <td> + UMPDAT.IDX + </td> + <td> + Contains profile information. Keys: + <ul> + <li>Primary: Group + Username + <li>Secondary: Username (no duplicates) + <li>Secondary: Alias (no duplicates) + </ul> + </td> + </tr> + <tr> + <td> + UMDDAT.IDX + </td> + <td> + 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 + </td> + </tr> +</table> + +<a name="heading_12.20.1"><h2>12.20.1 Field Requirements</h2></a> + +<p> +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: + +<ul> + <li>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. + <li>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. + <li>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. + <li>The LAST_UPDATE field is a VMS quadword date. + <li>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. +</ul> + +<p> + +<hr size=5> +<a name="vfc2pdf_chap"><h1>Chapter 13<br>VFC2PDF - Converting Text Files to PDF Format</h1></a> + +<p> +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. +<h3>accessing the program</h3> +<blockquote> +<br> +<br> + +<p> +The program may be executed by typing: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +Menu>VFC2PDF + +</pre> +</table> + +<p> +at the Menu or from the $ prompt by typing: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> +$ VFC2PDF/[qual 1]/.../[qual n] {input_file} [output_file]) + +</pre> +</table> + +</blockquote> + +<p> +By executing from the Menu, you have no control over the default +formatting options. + +<p> +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. + +<p> +<center> +<table border=0 width=75%> +<tr> + <td><center><font size=+2><strong>Note</strong></font></center><hr + size=1 noshade> + A foreign command must be defined for VFC2PDF, such as: +<br> + ($ VFC2PDF :== $OECN$:VFC2PDF). </td> + </tr> +</table> +</center> +<p> +<strong>Syntax</strong> +<br> + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + + + 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 + + +</pre> +</table> + +<p> +<strong>Defaults</strong> +<br> + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + + + 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 + + +</pre> +</table> + +<p> +<strong>Notes</strong> +<br> + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + + + - 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. + + +</pre> +</table> + +<h3>transfer options</h3> +<blockquote> +<br> + +<p> +There are several methods available to transfer the PDF formated file +to a PC or MAC. + +<p> +One method is to use some FTP utility. + +<p> +Another procedure, which seems to work well in Netscape, is to specify +an FTP URL as: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + + ftp://username@host.org/ + + +</pre> +</table> + +<p> +Netscape will prompt you for a password and connect with an +authenticated FTP. + +<p> +A second simple method is to mail the file(s) to yourself as follows: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + +EMAIL>send/file/noedit/nocc/subj="PDF Files" filename.pdf + + +</pre> +</table> + +<p> +or for multiple PDF files: + +<p> +<table border=0> + <tr> + <td> + <br> +<pre> + +EMAIL>send/file/noedit/nocc/subj="PDF Files" *.pdf + + +</pre> +</table> + +<p> +For the above, "noedit" means No Edit feature, and "nocc" means No +Carbon Copy desired. + +<p> +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. +</blockquote> +<p> +<table border=2> + <tr> + <td width=150 align=center><a href="oecn10_sysman_handbook_full_contents.html">Contents</a></td> + </tr> +</table> +</body> +</html>