Mercurial > public > html2wiki

<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 &copy;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 &quot; terminate and execute &quot;
      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&gt; 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 &quot;standard&quot; 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
      &quot;standard&quot; 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 &quot;group
      manager&quot; 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&gt;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&gt;                                           |
|                                                                 |
|   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 &lt;Show All Lists&gt; 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>&nbsp;</th>
    <th align=center>Command </th>
    <th align=center>&nbsp;</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>
      &nbsp;
    </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>
      &nbsp;
    </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>
      &nbsp;
    </td>
    <td>
      CSO_REWRITE
    </td>
    <td>
      =
    </td>
    <td>
      Synonym for REWRITE
    </td>
    <td>
      &nbsp;
    </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>
      &nbsp;
    </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>
      &nbsp;
    </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>
      &nbsp;
    </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>
      &nbsp;
    </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>
      &nbsp;
    </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>
      &nbsp;
    </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>
      &nbsp;
    </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>
      &nbsp;
    </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>
      &nbsp;
    </td>
    <td>
      01
    </td>
    <td>
      OECN-wide user distribution lists
    </td>
  </tr>
  <tr>
    <td>
      &nbsp;
    </td>
    <td>
      02
    </td>
    <td>
      OECN DAS staff-only lists
    </td>
  </tr>
  <tr>
    <td>
      &nbsp;
    </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>
      &nbsp;
    </td>
    <td>
      1)
    </td>
    <td>
      The user holds one or more of the specified identifiers.
    </td>
  </tr>
  <tr>
    <td>
      &nbsp;
    </td>
    <td>
      2)
    </td>
    <td>
      The UAF flags DISUSER and DISMAIL are not set.
    </td>
  </tr>
  <tr>
    <td>
      &nbsp;
    </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" "&lt;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" "&lt;oecn$ump:nwoca_usps.dis,*,*,postmaster,*, USPS"

add "nwoca_PPS" "nwoca_PPS-list@reprocess.nwoca.org"
add "nwoca_PPS-list" "&lt;oecn$ump:nwoca_PPS.dis,*,*,postmaster,*, PPS"

add "nwoca_USAS" "nwoca_USAS-list@reprocess.nwoca.org"
add "nwoca_USAS-list" "&lt;oecn$ump:nwoca_USAS.dis,*,*,postmaster,*, USAS"

add "nwoca_EMIS" "nwoca_EMIS-list@reprocess.nwoca.org"
add "nwoca_EMIS-list" "&lt;oecn$ump:nwoca_EMIS.dis,*,*,postmaster,*, EMIS"

add "nwoca_EIS" "nwoca_EIS-list@reprocess.nwoca.org"
add "nwoca_EIS-list" "&lt;oecn$ump:nwoca_EIS.dis,*,*,postmaster,*, EIS"

add "nwoca_VIS" "nwoca_VIS-list@reprocess.nwoca.org"
add "nwoca_VIS-list" "&lt;oecn$ump:nwoca_VIS.dis,*,*,postmaster,*, VIS"

add "nwoca_SECIMS" "nwoca_SECIMS-list@reprocess.nwoca.org"
add "nwoca_SECIMS-list" "&lt;oecn$ump:nwoca_SECIMS.dis,*,*,postmaster,*, SECIMS"

add "nwoca_INFOHIO" "nwoca_INFOHIO-list@reprocess.nwoca.org"
add "nwoca_INFOHIO-list" "&lt;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" "&lt;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&gt; 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&gt;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&gt;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&gt;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>
author	smith@nwoca.org
date	Tue, 25 Jan 2011 17:06:57 -0500
parents
children	22ed6d93442c