Mercurial > public > html2wiki
view test/resources/sysman_handbook.html @ 11:8f23347884c0
Deal with double dashes surrounded by words. ReplaceTransformer can now replace specific group.
| author | smith@nwoca.org |
|---|---|
| date | Fri, 28 Jan 2011 13:57:25 -0500 |
| parents | 22ed6d93442c |
| children |
line wrap: on
line source
<html> <a name="first_page"></a> <!-- This file created using DECdocument Version V3.3h on 25-JAN-2011 20:18:10.51 --> <!-- TAG definitions version: V3.3h --> <!-- The SDML doctype is: SOFTWARE.REFERENCE --> <!-- The output destination was: HTML --> <!-- SDML file is: NWB:[SMITH.DEV.SDML]OECN10_SYSMAN_HANDBOOK.SDML --> <body> <head> <title>Ohio Educational Computer Network System (OECN)</title> <style> A:hover {color: green} A:active {color: red; background-color: white} </style> </head> <h1 align="center">Ohio Educational Computer Network System (OECN)</h1> <h1 align="center">System Manager Manual</h1> As Developed by: Ohio Department of Education, State Software Development Team <p align=center> <strong>Revision/Update Information: </strong> May, 2001 <p> <hr size=5> <h4>Copyright ©1992, 1995 Ohio Department of Education</h4> <p> Permission to reproduce this document is hereby granted, provided that all such reproductions include all of this document (including this copyright notice), and are not distributed for profit or resale. <p> <table border=5> <tr> <td width=120 align=center> <a href="oecn10_sysman_handbook_full_contents.html"><font size=+2>Contents</font></a> </td> </tr> </table> <a name="post_contents"></a> <p> <hr size=5> <a name="menu_processor"><h1>Menu Processor Theory and Implementation</h1></a> <br> <br> <p> This section contains 6 chapters which describe the OECN Menu Processor for the system manager. It includes a complete description of the theory and implementation of the menu processor on a VAX/VMS system. The 6 chapters are: <p> Introduction <br> Theory <br> Implementation <br> Invoking the Menu Processor <br> Modifying and Creating Menu Systems <br> Customizing Menus from the Distribution <p> <hr size=5> <a name="menu_intro"><h1>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>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>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>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> 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>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>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>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>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>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>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>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>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>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>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>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> 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>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> Behavior Options</strong></a></caption> <tr> <th align=center>Command </th> <th align=center>Description </th> </tr> <tr> <td> TERMINATE </td> <td> Causes the processor to use the " terminate and execute " method for executing options. This is the default behavior. </td> </tr> <tr> <td> SPAWN </td> <td> Causes the processor to spawn all DCL and Program type action items in a subprocess. </td> </tr> <tr> <td> TIMEOUT=n </td> <td> Sets the inactivity timeout interval to n minutes. </td> </tr> <tr> <td> NOTIMEOUT </td> <td> Disables inactivity timeout. This is the default behavior. </td> </tr> </table> <p> For example, to specify the spawn option and a timeout of 30 minutes use the following command: <p> <table border=0> <tr> <td> <br> <pre> $ DEFINE/SYSTEM OECN$MENU_BEHAVIOR "SPAWN,TIMEOUT=30" </pre> </table> <a name="move_files_head"><h1>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>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>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>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>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>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> 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>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> 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>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>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> 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>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> 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>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> 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> 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>Values for Action Field</h3></a> <p> Much of the Menu Processor's flexibility is provided by the values that may be placed in the Action field. The Action field and the Item Type field together determine what will happen when the user chooses an item from a menu. <p> <strong>Item Type D (DCL)</strong> <br> <p> If Type = "D" then Action must contain a valid DCL command. Any DCL command may be specified, including command procedures. These commands may be executed in subprocess depending on the setting of OECN$MENU_BEHAVIOR (See <a href="oecn10_sysman_handbook_full.html#option_exec_sect">Section 2.5</a>). For example, the following are valid for Action: <blockquote> MAIL <br>@PURGE_TEXT_FILES <br>Write sys$output "Hello there." </blockquote> <p> If the DCL command requires or allows parameters to be specified you may place a tilde (~) at the location where the parameters should be placed. <p> As a simple example, assume that you have a print procedure that allows the filename and the number of copies as parameters. Item Label is PRINT and the name of the command procedure is OECN$UTL:PRINT.COM. On the PRINT item record you would put the following in the Action field: <p> <table border=0> <tr> <td> <br> <pre> @OECN$UTL:PRINT ~ ~ </pre> </table> <p> When the user enters the PRINT item from the Menu Processor they may specify the parameters on one line. For example, the user could enter: <p> <table border=0> <tr> <td> <br> <pre> Menu> PRINT MYFILE.TXT 10 </pre> </table> <p> The DCL command that would be executed by the Menu Processor would be: <p> <table border=0> <tr> <td> <br> <pre> $ @OECN$UTL:PRINT MYFILE.TXT 10 </pre> </table> <p> Up to 8 parameters may be specified. Parameters containing spaces must be enclosed in quotes. (Parameters may not contain quotes.) Lowercase characters are preserved inside of quotes. Parameters are replaced from left to right. No other parsing of the parameters is done. Parameters are always considered to be optional, if the user does not specify a parameter then the tilde (~) will be replaced by a space. <p> <strong>Item Type DP (DCL in Parent)</strong> <br> <p> Type "DP" is identical to type "D" except that the Action line is always executed in the parent process. This only has an effect if the menu processor is in "spawn and execute" mode (See <a href="oecn10_sysman_handbook_full.html#option_exec_sect">Section 2.5</a>). <p> This item type should be used sparingly and only when the command <em>must</em> be executed in the parent process. This is only necessary when the commands being executed must affect both the parent and subprocess. Examples of such commands are: <ul> <li>Commands that change security identifiers <li>Commands that modify menu logicals or modes <li>Commands that spawn subprocesses with the /NOWAIT qualifier </ul> <p> <strong>Item Type P (Program)</strong> <br> <p> If Type = "P" then the Action field contains the full VMS file specification for an executable image to be executed by the DCL RUN command. The distinction between programs and DCL commands is made primarily for compatibility with the HP version of the Menu Processor. However, future VAX releases may take advantage of this distinction. <p> <strong>Item Type M (Menu)</strong> <br> <p> If Type = "M" then the Action field must contain a valid menu specification. This type of item allows the user to move from one menu to another at a lower level. The menu specified may be in the current menu file or may specify a completely different menu file. See <a href="oecn10_sysman_handbook_full.html#menu_specs_head">Section 2.3</a> for more information about menu specifications. <p> <strong>Item Type T (Text)</strong> <br> <p> If Type = "T" then the action line is ignored. Text items are used to put information or subheadings on a menu. For text items, the Description field is simply displayed on the menu without a label or an option number. <a name="secur_id_screen_head"><h2>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>Security Identifiers</h3></a> <p> The security identifiers that appear on the Security Identifier screen are the "standard" identifiers. Three possible identifiers exist for each standard identifier, which are used to specify three levels of access. These alternate identifiers are derived by adding a suffix to the standard identifier. <p> The following table lists the three access levels, in order of lowest level access to the highest. <p> <table border=3> <caption><a name="security_level_tbl"><strong> Security Access Levels</strong></a></caption> <tr> <th align=center>Access Level </th> <th align=center>Suffix </th> <th align=center>Description </th> </tr> <tr> <td> Read-Only </td> <td> _RO </td> <td> If a user holds the identifier then read-only access is granted. This user may execute read-only programs or have access to read-only functions within programs. </td> </tr> <tr> <td> Standard </td> <td> none </td> <td> If a user holds this identifier then the user is granted "standard" access to the identifier. This user is assumed to be a standard read-write user of the corresponding package. </td> </tr> <tr> <td> Group Manager </td> <td> _GM </td> <td> Users that hold this identifier are granted access to "group manager" functions. This user is assumed to hold special privileges within the corresponding package. </td> </tr> </table> <p> For example, for the OECN_USPS identifier there are really three identifiers that may be granted to a user. These identifiers are: <blockquote> OECN_USPS_RO <br>OECN_USPS <br>OECN_USPS_GM </blockquote> <p> All these access levels, and therefore all the identifiers, exist for all packages, even if the package itself does not implement the identifiers. In other words, the Menu Processor will test for all the identifiers, even if the individual package does not. <p> It also should be noted that the access levels will be applied to the A-site specific identifiers. That is, there will also be OECN_USER1_RO and OECN_USER1_GM identifiers available for use at the A-site level. <a name="menuutl_head"><h1>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>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>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>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>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>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>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>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>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>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>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>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>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>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>Batch Mail Message System Manager Guide</h1></a> <a name="heading_7.1"><h1>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>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>OECN VIEW Utility</h1></a> <a name="heading_8.1"><h1>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>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>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>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>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>OECN EDIT Utility</h1></a> <a name="heading_9.1"><h1>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>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>OECN KEYMAP Utility</h1></a> <a name="heading_10.1"><h1>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>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>OECN SETUPENV Utility</h1></a> <a name="heading_11.1"><h1>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>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>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>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>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>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>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>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.