# HG changeset patch # User smith@nwoca.org # Date 1295993217 18000 # Node ID 5da2e67620f9419ccc4d892bc08f7bf27c06505d # Parent b6e94d49a9a9eb12d91d2434614768f72ae68517 Upgrade to Ivy configuration and begin clean up of tests. Added FreeBSD license. diff -r b6e94d49a9a9 -r 5da2e67620f9 LICENSE --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/LICENSE Tue Jan 25 17:06:57 2011 -0500 @@ -0,0 +1,26 @@ +Copyright 2010 Northwest Ohio Computer Association/SSDT. All rights reserved. + +Redistribution and use in source and binary forms, with or without modification, +are permitted provided that the following conditions are met: + + 1. Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + + 2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +THIS SOFTWARE IS PROVIDED BY NORTHWEST OHIO COMPUTER ASSOCIATION ``AS IS'' AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +IN NO EVENT SHALL NORTHWEST OHIO COMPUTER ASSOCATION OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON +ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +The views and conclusions contained in the software and documentation are those of the +authors and should not be interpreted as representing official policies, either expressed +or implied, of NORTHWEST OHIO COMPUTER ASSOCIATION. diff -r b6e94d49a9a9 -r 5da2e67620f9 build.xml --- a/build.xml Thu Jun 08 18:11:12 2006 -0400 +++ b/build.xml Tue Jan 25 17:06:57 2011 -0500 @@ -1,88 +1,23 @@ - - - - + Builds, tests, and runs the project html2wiki. - - - - - - - - - - - - - - - - - - + diff -r b6e94d49a9a9 -r 5da2e67620f9 ivy.xml --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/ivy.xml Tue Jan 25 17:06:57 2011 -0500 @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + diff -r b6e94d49a9a9 -r 5da2e67620f9 ivysettings.xml --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/ivysettings.xml Tue Jan 25 17:06:57 2011 -0500 @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff -r b6e94d49a9a9 -r 5da2e67620f9 nbproject/build-impl.xml --- a/nbproject/build-impl.xml Thu Jun 08 18:11:12 2006 -0400 +++ b/nbproject/build-impl.xml Tue Jan 25 17:06:57 2011 -0500 @@ -1,541 +1,806 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Must set src.dir - Must set test.src.dir - Must set build.dir - Must set dist.dir - Must set build.classes.dir - Must set dist.javadoc.dir - Must set build.test.classes.dir - Must set build.test.results.dir - Must set build.classes.excludes - Must set dist.jar - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Must select some files in the IDE or set javac.includes - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - To run this application from the command line without Ant, try: - - - - - - - java -cp "${run.classpath.with.dist.jar}" ${main.class} - - - - - - - - - - - - - - - - - - - - - - - To run this application from the command line without Ant, try: - - java -jar "${dist.jar.resolved}" - - - - - - - - - - - - - - - - Must select one file in the IDE or set run.class - - - - - - - - - - - - - - - - - - - - Must select one file in the IDE or set debug.class - - - - - Must set fix.includes - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Must select some files in the IDE or set javac.includes - - - - - - - - - - - - - - - - - - - - - - - Some tests failed; see details above. - - - - - - - - - Must select some files in the IDE or set test.includes - - - - Some tests failed; see details above. - - - - - Must select one file in the IDE or set test.class - - - - - - - - - - - - - - - - - Must select one file in the IDE or set applet.url - - - - - - - - - Must select one file in the IDE or set applet.url - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Must set src.dir + Must set test.src.dir + Must set build.dir + Must set dist.dir + Must set build.classes.dir + Must set dist.javadoc.dir + Must set build.test.classes.dir + Must set build.test.results.dir + Must set build.classes.excludes + Must set dist.jar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Must set javac.includes + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Must select some files in the IDE or set javac.includes + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + To run this application from the command line without Ant, try: + + + + + + + java -cp "${run.classpath.with.dist.jar}" ${main.class} + + + + + + + + + + + + + + + + + + + + + + + To run this application from the command line without Ant, try: + + java -jar "${dist.jar.resolved}" + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Must select one file in the IDE or set run.class + + + + Must select one file in the IDE or set run.class + + + + + + + + + + + + + + + + + + + + + + + Must select one file in the IDE or set debug.class + + + + + Must select one file in the IDE or set debug.class + + + + + Must set fix.includes + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Must select some files in the IDE or set javac.includes + + + + + + + + + + + + + + + + + + + + Some tests failed; see details above. + + + + + + + + + Must select some files in the IDE or set test.includes + + + + Some tests failed; see details above. + + + + + Must select one file in the IDE or set test.class + + + + + + + + + + + + + + + + + + + + + + + + + + + Must select one file in the IDE or set applet.url + + + + + + + + + Must select one file in the IDE or set applet.url + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff -r b6e94d49a9a9 -r 5da2e67620f9 nbproject/genfiles.properties --- a/nbproject/genfiles.properties Thu Jun 08 18:11:12 2006 -0400 +++ b/nbproject/genfiles.properties Tue Jan 25 17:06:57 2011 -0500 @@ -1,8 +1,8 @@ -build.xml.data.CRC32=9d118728 -build.xml.script.CRC32=867757ba -build.xml.stylesheet.CRC32=d5b6853a -# This file is used by a NetBeans-based IDE to track changes in generated files such as build-impl.xml. -# Do not edit this file. You may delete it but then the IDE will never regenerate such files for you. -nbproject/build-impl.xml.data.CRC32=9d118728 -nbproject/build-impl.xml.script.CRC32=22ed648d -nbproject/build-impl.xml.stylesheet.CRC32=99b91518 +build.xml.data.CRC32=9d118728 +build.xml.script.CRC32=867757ba +build.xml.stylesheet.CRC32=d5b6853a +# This file is used by a NetBeans-based IDE to track changes in generated files such as build-impl.xml. +# Do not edit this file. You may delete it but then the IDE will never regenerate such files for you. +nbproject/build-impl.xml.data.CRC32=4b98d2cf +nbproject/build-impl.xml.script.CRC32=4bfa927d +nbproject/build-impl.xml.stylesheet.CRC32=576378a2@1.32.1.45 diff -r b6e94d49a9a9 -r 5da2e67620f9 nbproject/ivy-impl.xml --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/nbproject/ivy-impl.xml Tue Jan 25 17:06:57 2011 -0500 @@ -0,0 +1,141 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff -r b6e94d49a9a9 -r 5da2e67620f9 nbproject/project.properties --- a/nbproject/project.properties Thu Jun 08 18:11:12 2006 -0400 +++ b/nbproject/project.properties Tue Jan 25 17:06:57 2011 -0500 @@ -1,60 +1,61 @@ -application.args= -build.classes.dir=${build.dir}/classes -build.classes.excludes=**/*.java,**/*.form -# This directory is removed when the project is cleaned: -build.dir=build -build.generated.dir=${build.dir}/generated -# Only compile against the classpath explicitly listed here: -build.sysclasspath=ignore -build.test.classes.dir=${build.dir}/test/classes -build.test.results.dir=${build.dir}/test/results -debug.classpath=\ - ${run.classpath} -debug.test.classpath=\ - ${run.test.classpath} -# This directory is removed when the project is cleaned: -dist.dir=dist -dist.jar=${dist.dir}/html2wiki.jar -dist.javadoc.dir=${dist.dir}/javadoc -jar.compress=false -javac.classpath=\ - ${libs.commons-io-1.2.classpath} -# Space-separated list of extra javac options -javac.compilerargs=-Xlint:unchecked -javac.deprecation=false -javac.source=1.5 -javac.target=1.5 -javac.test.classpath=\ - ${javac.classpath}:\ - ${build.classes.dir}:\ - ${libs.junit.classpath} -javadoc.additionalparam= -javadoc.author=false -javadoc.encoding= -javadoc.noindex=false -javadoc.nonavbar=false -javadoc.notree=false -javadoc.private=false -javadoc.splitindex=true -javadoc.use=true -javadoc.version=false -javadoc.windowtitle= -# Property libs.commons-io-1.2.classpath is set here just to make sharing of project simpler. -# The library definition has always preference over this property. -libs.commons-io-1.2.classpath=../shared/commons-io-1.2/commons-io-1.2.jar -main.class=org.nwoca.ssdt.tools.html2wiki.Html2Wiki -manifest.file=manifest.mf -meta.inf.dir=${src.dir}/META-INF -platform.active=default_platform -run.classpath=\ - ${javac.classpath}:\ - ${build.classes.dir} -# Space-separated list of JVM arguments used when running the project -# (you may also define separate properties like run-sys-prop.name=value instead of -Dname=value -# or test-sys-prop.name=value to set system properties for unit tests): -run.jvmargs= -run.test.classpath=\ - ${javac.test.classpath}:\ - ${build.test.classes.dir} -src.dir=src -test.src.dir=test +application.args= +application.title=html2wiki +application.vendor=SMITH +build.classes.dir=${build.dir}/classes +build.classes.excludes=**/*.java,**/*.form +# This directory is removed when the project is cleaned: +build.dir=build +build.generated.dir=${build.dir}/generated +build.generated.sources.dir=${build.dir}/generated-sources +# Only compile against the classpath explicitly listed here: +build.sysclasspath=ignore +build.test.classes.dir=${build.dir}/test/classes +build.test.results.dir=${build.dir}/test/results +debug.classpath=\ + ${run.classpath} +debug.test.classpath=\ + ${run.test.classpath} +# This directory is removed when the project is cleaned: +dist.dir=dist +dist.jar=${dist.dir}/html2wiki.jar +dist.javadoc.dir=${dist.dir}/javadoc +endorsed.classpath= +excludes= +includes=** +jar.compress=false +javac.classpath= +# Space-separated list of extra javac options +javac.compilerargs=-Xlint:unchecked +javac.deprecation=false +javac.source=1.5 +javac.target=1.5 +javac.test.classpath=\ + ${javac.classpath}:\ + ${build.classes.dir} +javadoc.additionalparam= +javadoc.author=false +javadoc.encoding= +javadoc.noindex=false +javadoc.nonavbar=false +javadoc.notree=false +javadoc.private=false +javadoc.splitindex=true +javadoc.use=true +javadoc.version=false +javadoc.windowtitle= +main.class=org.nwoca.ssdt.tools.html2wiki.Html2Wiki +manifest.file=manifest.mf +meta.inf.dir=${src.dir}/META-INF +platform.active=default_platform +run.classpath=\ + ${javac.classpath}:\ + ${build.classes.dir} +# Space-separated list of JVM arguments used when running the project +# (you may also define separate properties like run-sys-prop.name=value instead of -Dname=value +# or test-sys-prop.name=value to set system properties for unit tests): +run.jvmargs= +run.test.classpath=\ + ${javac.test.classpath}:\ + ${build.test.classes.dir} +src.dir=src +test.src.dir=test diff -r b6e94d49a9a9 -r 5da2e67620f9 nbproject/project.xml --- a/nbproject/project.xml Thu Jun 08 18:11:12 2006 -0400 +++ b/nbproject/project.xml Tue Jan 25 17:06:57 2011 -0500 @@ -1,16 +1,33 @@ - - - org.netbeans.modules.java.j2seproject - - - html2wiki - 1.6.5 - - - - - - - - - + + + org.netbeans.modules.java.j2seproject + + + + + + + + + + html2wiki + 1.6.5 + + + + + + + + + ivy.xml + ivysettings.xml + + + + + + + + + diff -r b6e94d49a9a9 -r 5da2e67620f9 src/org/nwoca/ssdt/tools/html2wiki/Html2Wiki.java --- a/src/org/nwoca/ssdt/tools/html2wiki/Html2Wiki.java Thu Jun 08 18:11:12 2006 -0400 +++ b/src/org/nwoca/ssdt/tools/html2wiki/Html2Wiki.java Tue Jan 25 17:06:57 2011 -0500 @@ -100,8 +100,7 @@ System.out.println(input.getAbsoluteFile()); Html2Wiki converter = new Html2Wiki(FileUtils.readFileToString(input,null)); - - + WikiChapter[] chapters = converter.getWikiChapters(); System.out.format("Writing %d wiki files...\n",chapters.length); @@ -181,7 +180,7 @@ } } - private static class WikiChapter { + protected static class WikiChapter { private String chapterName; private CharSequence contents; @@ -200,7 +199,7 @@ } public String toString() { - return "Chapter: " + chapterName + "\nContents: " + contents; + return "Chapter: " + chapterName + " Content length: " + contents.length(); } } diff -r b6e94d49a9a9 -r 5da2e67620f9 test/org/nwoca/ssdt/tools/html2wiki/Html2WikiTest.java --- a/test/org/nwoca/ssdt/tools/html2wiki/Html2WikiTest.java Thu Jun 08 18:11:12 2006 -0400 +++ b/test/org/nwoca/ssdt/tools/html2wiki/Html2WikiTest.java Tue Jan 25 17:06:57 2011 -0500 @@ -4,24 +4,27 @@ * * Created on May 9, 2006, 4:16 PM */ - package org.nwoca.ssdt.tools.html2wiki; +import java.io.File; +import java.net.URL; import junit.framework.*; -import java.io.*; - +import org.apache.commons.io.FileUtils; /** * * @author SMITH */ public class Html2WikiTest extends TestCase { - + + File path; + public Html2WikiTest(String testName) { super(testName); } protected void setUp() throws Exception { + path = new File(Html2WikiTest.class.getResource("/resources").toURI()); } protected void tearDown() throws Exception { @@ -29,26 +32,33 @@ public static Test suite() { TestSuite suite = new TestSuite(Html2WikiTest.class); - + return suite; } + public void testChapterParsing() throws Exception { + + File f = new File(path, "sysman_handbook.html"); + + Html2Wiki converter = new Html2Wiki(FileUtils.readFileToString(f, null)); + + Html2Wiki.WikiChapter[] chapters = converter.getWikiChapters(); + + assertTrue( chapters.length > 0); + for (Html2Wiki.WikiChapter c : chapters) { + System.out.println(c); + } + } + /** * Test of main method, of class org.nwoca.ssdt.tools.html2wiki.Html2Wiki. - */ - public void testMain() throws Exception { - System.out.println("main"); - - - Html2Wiki.main(new String[] {"\\C:\\temp\\", "EMIS System Managers Manual"}); - - } - -// public void testHtml2Wiki() throws Exception { -// -// File testFile = new File("\\C:\\temp\\test.html"); -// Html2Wiki.process(testFile); -// +// */ +// public void testMain() throws Exception { +// System.out.println("main"); +// +// File path = new File(Html2WikiTest.class.getResource("/resources").toURI()); +// System.out.println(path); +// Html2Wiki.main(new String[]{path.toString(), "OECN System Managers Handbook"}); +// // } - } diff -r b6e94d49a9a9 -r 5da2e67620f9 test/resources/sysman_handbook.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/test/resources/sysman_handbook.html Tue Jan 25 17:06:57 2011 -0500 @@ -0,0 +1,7039 @@ + + + + + + + + + + + +Ohio Educational Computer Network System (OECN) + + +

Ohio Educational Computer Network System (OECN)

+

System Manager Manual

+As Developed by: Ohio Department of Education, State Software +Development Team +

+Revision/Update Information: +May, 2001 + +

+

+

Copyright ©1992, 1995 Ohio Department of Education

+ +

+Permission to reproduce this document is hereby granted, provided that +all such reproductions include all of this document (including this +copyright notice), and are not distributed for profit or resale. +

+ + + + +
+Contents +
+ + +

+

+

Menu Processor Theory and Implementation

 +
+
+ +

+This section contains 6 chapters which describe the OECN Menu Processor +for the system manager. It includes a complete description of the +theory and implementation of the menu processor on a VAX/VMS system. +The 6 chapters are: + +

+ Introduction +
+ Theory +
+ Implementation +
+ Invoking the Menu Processor +
+ Modifying and Creating Menu Systems +
+ Customizing Menus from the Distribution + +

+

+

Chapter 1
Introduction

 + +

+ The OECN Menu processor provides a flexible user menu interface to + State Software programs. It also can be used to create menus for DCL + commands, and other layered products. Menu definitions will be provided + for all state software programs. Individual A-sites will be able to add + customized menus to the default menu system provided. + +

1.1 Features

+ +

+ The Menu processor provides the following features: + +

+ +

+ Features for the system manager: + +

+ +

+

+

Chapter 2
Theory

 + +

+ The basic theory behind the Menu processor is fairly simple. The menu + definitions are stored in an RMS indexed file. The menu definitions are + flexible enough to allow creation of menus containing any combination + of DCL commands, programs and information. + +

2.1 Definition of Terms

+ +

+ First, it will be helpful to define some terms that will be used + throughout the rest of this document.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 2-1 Menu System Terms
Term Meaning
+ Menu Processor + + The program that the user runs to enter a menu system. +
+ menu + + A menu consists of the menu heading and the menu items on that menu. +
+ menu name + + The name of the menu as defined in the MENUEDT program. +
+ menu item + + An item on a menu. An item belongs to a specific menu and must have a + label that is unique throughout the menu system. +
+ label + + A label is the unique name for an item. It is defined in the MENUEDT + program and is the label the user will see on the actual menu. +
+ menu file + + A file created by MENUEDT that contains the menu definitions for one + for more menus. +
+ menu system + + A menu system is a collection of menus that the user has access to. + This is the + logical menu system as viewed by a specific user. A + system may consist of one or more physical menu files. +
+ menu specification + + A menu specification is the format for specifying a menu. The + specification may contain a file and/or a menu name. +
+ alias + + For each item in the menu system an alias is created. It has the same + name as the item's label. The alias is global to the entire menu + system, i.e., it crosses all menu file boundaries. The alias must be + unique within each menu system. +
+ +

2.2 How Menu Files Create a Menu System

+ +

+Figure 2-1 displays a graphical representation of a possible menu +system. + +

+Figure 2-1 Conceptual View of a Menu system +

+ +

+ + +
+
+
++-----------------------Menu-System-------------------+ 
+|            +Menu-File+                              | 
+|            |         |                +-Alias-File-+| 
+|            | +Menu+  |                |            || 
+|            | |    |  |                |            || 
+|            | +----+  |                |            || 
+|            +----+----+                |            || 
+|         +-------+------------+        +------------+| 
+| +---Menu+File--+        +Menu+File-+  +-Secur-File-+| 
+| | +Menu+       |        |          |  |            || 
+| | |    |       |        | +Menu+   |  |            || 
+| | +-+--+       |        | |    |   |  |            || 
+| |   +------+   |        | +----+   |  |            || 
+| | +Menu+ +Menu+|        +----+-----+  +------------+| 
+| | |    | |    ||        +----+------+               | 
+| | +----+ +-+--+|        |           |               | 
+| |   +------+   |   +Menu+File+ +Menu+File+          | 
+| | +Menu+ +Menu+|   | +Menu+  | | +Menu+  |          | 
+| | |    | |    ||   | |    |  | | |    |  |          | 
+| | +----+ +----+|   | +----+  | | +----+  |          | 
+| +--------------+   +---------+ +---------+          | 
++-----------------------------------------------------+ 
+
+
+ +

+ You can see from Figure 2-1 that a menu system as seen by the user may + consist of multiple menu files, and a menu file may contain multiple + menus. This provides considerable flexibility for designing and + modifying a menu system. + +

+ The menu system that is included with the distribution will have a + separate menu file for each OECN state software package. Additionally, + each major package will have a local menu. This local + menu will be in a separate menu file and left blank. You will be able + to customize this local menu without disturbing the other menus. + +

+ A more detailed description of how to modify and create menus will + follow later in this document. The method used to customize local menus + will be discussed. + +

+ Each menu system has one alias file. This file is used to find an + item's location if the user enters an alias. + +

+Also, the menu system may have one local security file. This file is +optional and created by the OSA utility. See the OECN Software Security +for VAX/VMS System Manager manual for more information about security +and the OSA utility. + +

2.3 Menu Specifications

+ +

+ Throughout this document there are references to menu + specifications. Wherever a menu specification is required the + following syntax is allowed: + + + + +
+
+
+@menu_file\menu_name 
+
+
+

+ + + + + + + + + + + + + + +
Parameter Meaning
+ @menu_file + + Name of a menu file that contains menu_name. If not specified then + menu_name is assumed to exist in the current menu file. +
+ menu_name + + A menu within either the specified menu file or the current menu file. +
+ +

+ A valid menu specification contains one or both of these components. + +

+ If a menu name is specified without a menu file then the menu is + assumed to exist in the current menu file. If there is no current menu + file then OECN$MENU is used. + +

+ If a menu file is specified without a menu name then the default menu + of the menu file's header record is used. + +

+ If both the menu file and menu name are specified they must be + separated by a backslash (\). + +

+Examples: + + + + + + + + + + + + + + + + + + +
Specification Result
+ @BUD_MENU\USAS_PRC + + Goes to the USAS_PRC menu of the BUD_MENU file. +
+ @MAIN_MENU + + Goes to the default menu of the MAIN_MENU file. +
+ LOCAL + + Goes to the LOCAL menu of the current file. +
+ +

2.4 The Alias File

+ +

+ Each menu system may have exactly one alias file. An + alias file contains a record for each menu item in the menu system. + This alias record contains a pointer to the proper menu file that + contains the item. + +

+ When the user enters a label name that is not on the current menu, the + alias file is checked for the label. If found then the item is located + in the appropriate menu file, and, assuming the user has access to the + item, it is executed. This allows the user to get to any item or menu + in the menu system without navigating through the intervening menus. + +

+The alias file is built automatically by the MENUUTL program. See +Section 5.2.1, Building the Alias File for more information about creating the alias file. + +

2.5 Option execution

+ +

+By default, the menu processor does not spawn subprocesses to +execute user options. All commands are executed in the user's current +process. This implies that menu processor image must exit and restart +(activate) after each option has completed. This is called +"terminate and execute" mode. This mode may provided +optimal response time for smaller VAX processors, particularly machines +with small memory configurations. + +

2.5.1 Spawning Options

+ +

+Another mode that may be chosen by the system manager is "spawn and +execute". In this mode, most commands are executed in a +subprocess. The menu processor remains running in the main process and +does not terminate. Spawning options may reduce response time for +larger VAX machines with excess physical memory. + +

+No firm guidelines can be provided to suggest which mode will provide +optimal response time and resource utilization for a given system. +Response time in both modes is determined by machine size, available +memory, tuning, typical load on the system, etc. Trial and error under +a typical work load is the only way to determine the best mode. If the +time required to spawn a process is less than the time required to +activate the menu image, then spawning is preferable. + +

+To implement menu option spawning the system manager must be aware of +the following: + +

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

+Prior to implementing spawning you must carefully consider whether any +custom menu files contain any options that fall under #4 above. The +subprocess that is created by the menu processor is temporary (i.e., +the subprocess logs out as soon as the option has completed). This +means that any commands performed in the subprocess will not be +permanent. If you have options that change user logicals, create +processes, etc. or anything that must affect both the main process and +the subprocess, you must modify your custom menu files. + +

+The MENUEDT program will allow you to define an item type "DP" (DCL +command in Parent). These types of items will always be executed in the +main process using "terminate and execute". These means that any +commands executed in this way will affect both the main process and +subprocess. These types of items should be used sparingly and will +seldom be necessary. The only item in the menu files distributed by +SSDT that need the "DP" item type was the DETPRT option of the LOCAL +menu. All other SSDT menu items may be executed in a subprocess. + +

2.5.2 Selecting Execution Mode

+ +

+To select either "terminate and execute" or "spawn and execute" mode, +the system manager needs only define a single logical. The logical name +is OECN$MENU_BEHAVIOR and may be defined in the SYSTARTUP procedure. +The valid values are: TERMINATE or SPAWN. For example, if you want to +use "spawn and execute", add the following line the SYSTARTUP procedure: + +

+ + +
+
+
+$ DEFINE/SYSTEM OECN$MENU_BEHAVIOR "SPAWN" 
+
+
+ +

+This logical also can be defined at the group or process level. If the +logical is not defined, the default is "TERMINATE". + +

2.6 Inactivity Timeout

+ +

+The menu processor has an optional feature that will cause it to +automatically exit if the user does not enter a command after a +specified period of time. This might be a useful security feature for +user users who remain idle in the menu for long periods of time or +forget to logout. + +

+The system manager may add a command to the OECN$MENU_BEHAVIOR logical +that will enable the timeout feature. The following syntax may be used: + +

+ + +
+
+
+$ DEFINE/SYSTEM OECN$MENU_BEHAVIOR "TIMEOUT=n" 
+
+
+ +

+ Where n is the number minutes to wait with no activity. After + the timeout period expires without any options being entered, the menu + processor will exit automatically. + +

+

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

+

+

Chapter 3
Implementation

 + +

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

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

3.1 Installation

 + +

+ The Menu Processor uses files from the OECN, MENU and HELP packages. + Install these packages as usual using OECN_INSTALL. For further + information about OECN_INSTALL see OECN_INSTALL.DOC in the VAX manager + documentation directory. + +

3.2 Establish OECN Logicals

+ +

+ Several logicals are used by the Menu Processor to locate the menu + files and VMS Help libraries.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3-1 Menu Logicals
Logical Purpose
+ OECN$MENU$FILES + 1 + + Device and directory where the menu files are located. +
+ OECN$MENU + 2 + + Default menu file if none is specified by the user when the Menu + Processor is invoked. +
+ OECN$ALIAS + 2 + + Default alias file that is used if none is specified when the Menu + Processor is invoked. +
+ OECN$SECUR + + Local security file. Optional. Created by OSA utility to define local + security. +
+ OECN$HELP + 1 + + Device and directory where the VMS Help libraries are located. +
+ OECN$MENU_HELP + 2 + + Default menu help library. Used when the user presses + [PF2] or ?. +
+ OECN_MENU_PROMPT + + Default prompt to be used in the Menu Processor. Optional. May be + overridden by the user with a SET PROMPT command. +
+ OECN_MENU_MODE + + Default mode. Optional. May contain the "MENU" or "COMMAND". May be + overridden by the user with a SET MODE command. +
+ OECN$MENU_BEHAVIOR + + Optional logical that may contain commands to control how the menu + processor behaves at run-time. This logical is defined by the system + manager. See 3.2.1. +
+

+2 Defined by the OECN_STARTUP procedure. +
+1May be defined as a search list. +
+
+ +

+ OECN$MENU$FILES and OECN$HELP must be defined in either the SYSTARTUP + or individual LOGIN.COM files. These logicals may be defined at the + system, group or process level. For example, the OECN$MENU logical may + be defined for each user to provide a different default menu. + +

3.2.1 Specifying options with OECN$MENU_BEHAVIOR logical

+ +

+ This section describes the commands that may be placed in the + OECN$BEHAVIOR logical. The syntax for the logical definition is: + +

+ + +
+
+
+$ DEFINE/SYSTEM OECN$MENU_BEHAVIOR "command[,command]..." 
+
+
+ +

+ Where [command] is one of the commands in the following table. + The command(s) must be enclosed in quotes and be in uppercase. When + multiple commands are specified they must be separated by commas (,). + This logical can be defined at the system, group, job or process level. +

+ + + + + + + + + + + + + + + + + + + + + + + +
Table 3-2 Behavior Options
Command Description
+ TERMINATE + + Causes the processor to use the " terminate and execute " + method for executing options. This is the default behavior. +
+ SPAWN + + Causes the processor to spawn all DCL and Program type action items in + a subprocess. +
+ TIMEOUT=n + + Sets the inactivity timeout interval to n minutes. +
+ NOTIMEOUT + + Disables inactivity timeout. This is the default behavior. +
+ +

+ For example, to specify the spawn option and a timeout of 30 minutes + use the following command: + +

+ + +
+
+
+$ DEFINE/SYSTEM OECN$MENU_BEHAVIOR "SPAWN,TIMEOUT=30" 
+
+
+ +

3.3 Move Files to Appropriate Directories

+ +

+ Move the menu files (OECN$ROOT:[MENU.DIST]*.DAT) to the directory + referenced by OECN$MENU$FILES. + +

+ Move the VMS Help libraries from the HELP package distribution + directory to the directory referenced by OECN$HELP. + +

+ The users of the Menu Processor must have read access to the above + files. + +

+ Also move the following files to the OECN$ directory: + +

+ OECN$ROOT:[OECN.V1P0.DIST]MENU.EXE +
OECN$ROOT:[OECN.V1P0.DIST]OECN_MENU.COM +
+ +

+ The users must have execute access to these files. + +

3.4 Add Global Symbol

+ +

+ Add the following symbol to either your SYLOGIN.COM or each user's + LOGIN.COM who will be using the system: + +

+ + +
+
+
+$ OECN_MENU :== $OECN$:MENU 
+
+
+ +

+ This creates a foreign command that the OECN_MENU.COM procedure uses to + invoke the Menu Processor. Other symbols may be necessary to make it + easier for your users to invoke a menu. These symbols will be discussed + in the Chapter 4, Invoking the Menu Processor. The OECN_MENU symbol is the only required symbol. + +

3.5 Install the Menu Processor

+ +

+ Although it is not necessary for proper execution of the Menu + Processor, it is strongly recommended that you install + the Menu Processor as a known image. + +

+ Because the Menu Processor does not spawn a subprocess it must be + reactivated after each time the user selects a menu item. If the image + is not installed, image activation will cause a noticeable delay in the + Menu Processor. + +

+ The recommended method of installing the image is to add the following + commands to your SYSTARTUP.COM: + +

+ + +
+
+
+$ INSTALL :== $INSTALL/COMMAND_MODE 
+$ INSTALL ADD OECN$:MENU.EXE/OPEN/SHARED/HEADER 
+
+
+ +

+

+

Chapter 4
Invoking the Menu Processor

 + +

+ The Menu Processor must be invoked via a command procedure that is + provided as part of the OECN package. The Menu Processor depends on + this command procedure to perform several vital functions and to + actually execute any items selected by the user. Absolutely nothing + useful will happen if the Menu Processor is invoked directly. + +

+ Additionally, the Menu Processor is invoked by the command procedure + with a foreign command. Therefore the following symbol definition is + required. See Section 3.4, Add Global Symbol. + +

+ + +
+
+
+$ OECN_MENU == "$OECN:MENU" 
+
+
+ +

+ To invoke the menu processor the following command must be used: + +

+ + +
+
+
+$ @OECN$:OECN_MENU [menu spec] [alias file] [menu_option] 
+
+
+ +

+ The OECN_MENU.COM command procedure is provided with the distribution + and must be used to invoke the menu processor. + +

+ The first parameter is an optional menu specification that specifies + the default menu file and menu to be used. If the menu specification is + not supplied then OECN$MENU is used by default. See Section 2.3, Menu Specifications for + more information about menu specifications. + +

+ The second optional parameter is the alias file for the menu system + being invoked. If not specified then OECN$ALIAS is used by default. + +

+The third optional parameter is a menu command, option or alias to be +executed. If this parameter is specified then the menu processor will +execute the option and return to DCL, the user will +not be left in the menus after the option has finished +executing. This could be used as a replacement for the DCL RUN command, +particularly for batch procedures. This would insure that batch +procedures do the same security checking as interactive processes. + +

+

+ + + + +
Note
+The menu processor will operate properly in batch only if the third +parameter is supplied. If the parameter is not specified the menu +processor will not function in batch.
+
+ +

+ This command may be defined in a global symbol, invoked from a captive + login procedure or from inside another procedure. No restrictions are + placed on the method of invoking the Menu Processor. + +

4.1 Examples

+ +

+ For most users the following symbol definition is sufficient: + +

+ + +
+
+
+$ MENU == "@OECN$:OECN_MENU" 
+
+
+ +

+ This will invoke the Menu Processor with the default menu and alias + file. This will normally, unless changed by you, be the MAIN_MENU file, + which contains menu items for all state software packages. + +

+If users will be using the third parameter (or it will be used from +batch) then the following symbol might be used: + +

+ + +
+
+
+$ MENU == "OECN$:OECN_MENU """" """" " 
+
+
+ +

+This will leave the first two parameters as null (accepting the default +menu and alias files) and allow the third parameter to be specified +after the MENU symbol. + +

+ As another possibility, suppose that you have a payroll user that would + rather be started out in the USPS menu. In this case put this symbol in + that user's LOGIN procedure: + +

+ + +
+
+
+$ MENU == "@OECN$:OECN_MENU @PAY_MENU" 
+
+
+ +

+ This will put the user in the PAY_MENU directly. Note that this does + not restrict the user to the PAY_MENU, it just starts them out in that + menu. + +

+

+

Chapter 5
Modifying and Creating Menu Systems

 + +

+ The MENUEDT program is a fully functional maintenance program for + modifying and creating menu files. Another program, MENUUTL, provides + several necessary and useful utilities when manipulating the files, + such as building the alias file and reporting functions.

+ + + + + + + + + + + + + + + + + + + +
Table 5-1 Menu Record Types
Record Type Function
+ File Header Record + + Contains information about the entire menu file. There is only one file + header record per file. +
+ Menu Header Record + + Contains information specific to one menu. There is no structural or + logical limit to the number of menus that may exist in a menu file. +
+ Item Record + + Contains the actual item that appears on a menu. Each item record + belongs to one and only one menu. The number of items is limited by the + Menu Processor to 50 items (about 4 screens). +
+ +

+ The menu files and records form a loose hierarchy. That is, + the hierarchy is created by the person developing the menu system. The + hierarchy is not enforced by the MENUEDT program or even the Menu + Processor. The menus can be connected in an almost limitless number of + combinations. It is impossible for the MENUEDT program to know exactly + what the runtime environment will be for the menu file. Thus, very + little error checking is performed or even attempted. This means that + menus that you modify or create should be tested thoroughly before + being made available to your users. + +

5.1 Using MENUEDT

+ +

+ When you first run the MENUEDT program it will prompt you for the name + of the menu file to modify. If the file does not exist it will be + created.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5-2 MENUEDT Main Menu Options
Option Function
+ Add + + Adds new records of any type. +
+ Change + + Enters change mode for the current record. +
+ Delete + + Deletes the current record. +
+ Top + + Goes to top of file (File header record). +
+ Find + + Finds a record by menu or item name. +
+ Next + + Goes to the next record. +
+ Simulate + + Simulates how the menu will look to the user. The simulation is + approximate since the MENUEDT upper window is smaller than in the Menu + Processor. +
+ Open + + Closes the current menu file and prompts for a new menu file to open. +
+ Exit + + Exits MENUEDT. +
+ +

5.1.1 Menu File Record Types

+ +

+ This section and the following sections show sample screens that are + used by MENUEDT to modify the various record types. After each screen + is a detailed explanation of each field and its purpose. + +

5.1.2 File Header Record

+ +

+ The first record in each menu file must be a File Header record and + each file must contain exactly one Header record. + +

+ + +
+
+
+ 
+              Menu File Header Record:   
+                                                               
+               1. Desc:  
+               2. Default menu:  
+               3. Modify default security identifiers                  
+                                                               
+
+
+ +

+ + + + + + + + + + + + + + + + + + + +
Table 5-3 File Header Record Fields
Field Description
+ Desc + + This description is used in the heading for all menus in this file. +
+ Default Menu + + Is the default menu for this file if the user does not specify a menu + when the file is invoked. This menu will normally be the top-level menu + for this file. +
+ Modify default security identifiers + + Enters the + Security Id Maintenance screen to allow default security + identifiers to be placed on the menu file. See Section 5.1.5 for more + information about security identifiers. +
+ +

5.1.3 Menu Header Record

+ +

+ The Menu Header record contains information about each menu in the + file. There must be exactly one Header record for each menu contained + in the file. + +

+ + +
+
+
+ 
+               Menu header record:                             
+                                                               
+                1. Menu Name   :  
+                2. Description :  
+                3. Heading Type:  
+                4. Help file   :                               
+                5. Help topic  :                               
+                6. Parent Menu :                               
+                7. Modify Security Identifiers                 
+    
+
+
+ +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5-4 Menu Header Fields
field Description
+ Menu Name + + Name of the menu. This is the name that will be displayed in the menu + heading. +
+ Description + + This description is used in the heading for this menu. +
+ Heading Type + + Indicates what type of menu heading to use for this menu. + + + + + + + + + +
+ A + + Heading contains both the file description and the menu description. +
+ B + + Heading contains only the menu heading description. +
+
+ Help File + + The VMS Help file that will be used if the user enters HELP at this + menu. +
+ Help topic + + The initial topic string used when the user enters HELP. +
+ Parent Menu + + Must contain the parent menu specification for this menu. This is the + menu that the user will return to when they enter /EXIT or ^. If this + field is blank then the menu is assumed to be the top level menu of the + menu system. +
+ Modify security identifiers + + Enters the + Security Id Maintenance screen to allow security identifiers + to be placed on the menu. See Section 5.1.5 more information about + security identifiers. +
+ +

5.1.4 Menu Item Record

+ +

+ One menu item record must be specified for each desired item on a menu. + A menu can contain a maximum of 50 item records. If there are less than + 8 items then the menu will be double spaced, otherwise the menu will be + single spaced. If there are more items than will fit on one screen then + the menu will be divided into multiple screens. + +

+ An item may be of one of four types, the value and meaning of the + Action field is determined by the Item Type field. The four possible + types and the meaning of the Action field are defined in Table 5-5. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5-5 Menu Item Types
Item Type Interpretation of Action Field
+ D + + DCL command to execute +
+ DP + + DCL command to execute in Parent process +
+ P + + Program filespec to execute +
+ M + + Menu specification +
+ T + + Ignored +
+ +

+ + +
+
+
+ 
+      Menu Item record: 
+                       
+         1. Menu Name: 
+         2. Label    : 
+         3. Desc     : 
+         4. Item Type: 
+         5. Action   : 
+                             
+         6. Item order#: 
+         7. Modify Security Identifiers 
+ 
+
+
+ +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5-6 Menu Item Fields
Field Description
+ Menu Name + 1 + + Name of the menu that this item belongs to. +
+ Label + 1 + + Label of this item that the user will use to reference this item. +
+ Desc + + Description displayed for this item. +
+ Item Type + + Indicates what type of item this is: + + + + + + + + + + + + + + + + + + + + + +
+ D + + DCL command +
+ DP + + DCL in Parent process +
+ P + + Program to be executed +
+ M + + Menu item +
+ T + + Text Item +
+
+ Action + + Contains the action to be performed when this item is selected. See + Section 5.1.4.1 for more information. +
+ Item order # + + This field is used to order the items on the menu. By default the items + are in alphabetical order by Item Label. If you want to change the + order of the items then you may put a number in the Item Order# field. + This number does not affect the number that the user will use to invoke + the item, it only affects the physical order of the items on the menu. +
+ Modify security identifiers + + Enters the + Security Id Maintenance screen to allow security identifiers + to be placed on the item. See section Section 5.1.5 for more information + about security identifiers. +
+

+1Key fields of the menu file. However the MENUEDT program +allows these fields to be changed. +
+
+ +

5.1.4.1 Values for Action Field

 + +

+ Much of the Menu Processor's flexibility is provided by the values that + may be placed in the Action field. The Action field and the Item Type + field together determine what will happen when the user chooses an item + from a menu. +

+Item Type D (DCL) +
+ +

+ If Type = "D" then Action must contain a valid DCL command. Any DCL + command may be specified, including command procedures. These commands + may be executed in subprocess depending on the setting of + OECN$MENU_BEHAVIOR (See Section 2.5). For example, the following are + valid for Action: + +

+ MAIL +
@PURGE_TEXT_FILES +
Write sys$output "Hello there." +
+ +

+ If the DCL command requires or allows parameters to be specified you + may place a tilde (~) at the location where the parameters should be + placed. + +

+ As a simple example, assume that you have a print procedure that allows + the filename and the number of copies as parameters. Item Label is + PRINT and the name of the command procedure is OECN$UTL:PRINT.COM. On + the PRINT item record you would put the following in the Action field: + +

+ + +
+
+
+@OECN$UTL:PRINT ~ ~ 
+
+
+ +

+ When the user enters the PRINT item from the Menu Processor they may + specify the parameters on one line. For example, the user could enter: + +

+ + +
+
+
+Menu> PRINT MYFILE.TXT 10
+
+
+ +

+ The DCL command that would be executed by the Menu Processor would be: + +

+ + +
+
+
+$ @OECN$UTL:PRINT MYFILE.TXT 10
+
+
+ +

+ Up to 8 parameters may be specified. Parameters containing spaces must + be enclosed in quotes. (Parameters may not contain quotes.) Lowercase + characters are preserved inside of quotes. Parameters are replaced from + left to right. No other parsing of the parameters is done. Parameters + are always considered to be optional, if the user does not specify a + parameter then the tilde (~) will be replaced by a space. +

+Item Type DP (DCL in Parent) +
+ +

+ Type "DP" is identical to type "D" except that the Action line is + always executed in the parent process. This only has an effect if the + menu processor is in "spawn and execute" mode (See Section 2.5). + +

+This item type should be used sparingly and only when the command +must be executed in the parent process. This is only necessary +when the commands being executed must affect both the parent and +subprocess. Examples of such commands are: + +

+ +

+Item Type P (Program) +
+ +

+ If Type = "P" then the Action field contains the full VMS file + specification for an executable image to be executed by the DCL RUN + command. The distinction between programs and DCL commands is made + primarily for compatibility with the HP version of the Menu Processor. + However, future VAX releases may take advantage of this distinction. +

+Item Type M (Menu) +
+ +

+ If Type = "M" then the Action field must contain a valid menu + specification. This type of item allows the user to move from one menu + to another at a lower level. The menu specified may be in the current + menu file or may specify a completely different menu file. See + Section 2.3 for more information about menu specifications. +

+Item Type T (Text) +
+ +

+ If Type = "T" then the action line is ignored. Text items are used to + put information or subheadings on a menu. For text items, the + Description field is simply displayed on the menu without a label or an + option number. + +

5.1.5 Menu Security Screen

+ +

+ The Modify Security Identifier screen allows you to + require that the user has specific VMS identifiers before they are + allowed access to certain menu elements. + +

+ Security may be placed on any level: File, Menu or Item. If the user + does not have access to a menu item, it will not appear on the menu. + +

+Three levels of access can be specified for each identifier that +appears on the Security Identifier screen: Read-only, Standard or Group +Manager. See Section 5.1.5.1 for more information about how these +identifiers are derived. + +

+ The following screen shows an example of a menu element that requires + the user to have read-only access to the OECN_PPS identifier or + standard access to the OECN_SALSIM identifier. Note that the user must + only have one of the selected identifiers. Of course, users with + OECN_SYSMAN access have access to all menu elements regardless of these + identifiers. + +

+ + +
+
+
+    1) OECN_EDCIMS                9) OECN_SYSMAN 
+    2) OECN_EIS                   10) OECN_USAS  
+    3) OECN_OECN                  11) OECN_USPS  
+  R 4) OECN_PPS                   12) OECN_VIS   
+    5) OECN_PVS                   13) OECN_USER1 
+  S 6) OECN_SALSIM                14) OECN_USER2 
+    7) OECN_SECIMS                15) OECN_USER3 
+    8) OECN_SECIMS_GRPMAN         16) OECN_USER4 
+                                                        
+(R = Read-Only,  S = Standard, G = Group Manager)       
+ 
+
+
+ +

+ Security will be propagated through the menu structure. If security is + not specified for a menu element, then security will be inherited from + the level above it. The following list details the rules that are used + to determine how security is inherited. + +

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

+ The identifiers OECN_USER1 through OECN_USER4 are for use locally at + the A-sites. You may assign these identifiers in any manner you wish. + For example, you may want to allow specific users to access VMS Mail. + You could use OECN_USER1 to restrict a MAIL menu item to those users. + These identifiers will not be used by SSDT in any State Software + programs. + +

+ If four identifiers are not enough for your site, you may add new ones. + Up to 16 identifier positions have been reserved for use at the A-site + level. See OECN_IDS.LIB in OECN$LIB: for instructions. + +

5.1.5.1 Security Identifiers

+ +

+ The security identifiers that appear on the Security Identifier screen + are the "standard" identifiers. Three possible identifiers + exist for each standard identifier, which are used to specify three + levels of access. These alternate identifiers are derived by adding a + suffix to the standard identifier. + +

+ The following table lists the three access levels, in order of lowest + level access to the highest.

+ + + + + + + + + + + + + + + + + + + + + + + +
Table 5-7 Security Access Levels
Access Level Suffix Description
+ Read-Only + + _RO + + If a user holds the identifier then read-only access is granted. This + user may execute read-only programs or have access to read-only + functions within programs. +
+ Standard + + none + + If a user holds this identifier then the user is granted + "standard" access to the identifier. This user is assumed to + be a standard read-write user of the corresponding package. +
+ Group Manager + + _GM + + Users that hold this identifier are granted access to "group + manager" functions. This user is assumed to hold special + privileges within the corresponding package. +
+ +

+For example, for the OECN_USPS identifier there are really three +identifiers that may be granted to a user. These identifiers are: + +

+ OECN_USPS_RO +
OECN_USPS +
OECN_USPS_GM +
+ +

+All these access levels, and therefore all the identifiers, exist for +all packages, even if the package itself does not implement the +identifiers. In other words, the Menu Processor will test for all the +identifiers, even if the individual package does not. + +

+It also should be noted that the access levels will be applied to the +A-site specific identifiers. That is, there will also be OECN_USER1_RO +and OECN_USER1_GM identifiers available for use at the A-site level. + +

5.2 Using MENUUTL

+ +

+ The MENUUTL program provides some necessary functions for building, + maintaining and documenting a menu system. The options provided are: + +

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

5.2.1 Building the Alias File

 + +

+ The first and the most important option of MENUUTL is the alias file + build option. The alias file contains a pointer for each menu item in + the system. Therefore, whenever you add or remove menu items from a + menu file you must rebuild the alias file. + +

+ MENUUTL makes this process rather simple. All you have to do is run + MENUUTL and choose option 1. MENUUTL will ask the following questions: + +

+ + +
+
+
+Physical name of top level menu file:___________
+
+
+ +

+ Enter the physical filespec of the top-level menu file. This is the + current physical location of the top-level menu file. + +

+ + +
+
+
+Logical name of top level menu file:_____________
+
+
+ +

+ Enter the logical filespec of the top level menu file. This should be + the logical name of the file that will be used when the user accesses + the menu system. + +

+

+ + + + +
Note
+ The physical and logical name should normally be the same.
+
+ +

+ + +
+
+
+Enter new alias filename: ___________________
+
+
+ +

+ Enter the name of the new alias file to be built. The alias file is + always rebuilt from scratch and a new version is created. + +

+ After prompting for these values, MENUUTL will begin reading through + the specified menu file and add an alias for each item found. It will + also search for references to other menu files. If such references are + found, MENUUTL will search those files for menu items and add aliases + for each one. + +

+

+ + + + +
Important
+ MENUUTL uses the OECN$MENU$FILES logical to search for the menu files + in the same manner as will be used by the Menu Processor. Therefore, + the runtime environment for MENUUTL must be the same as when the Menu + Processor will be invoked.
+
+ +

+ As stated earlier, all aliases must be unique across the entire menu + system. If MENUUTL finds a duplicate alias name, an error message will + displayed and the duplicate will not be added. Processing will continue + and the alias file will be usable, but the alias for the duplicate item + will not exist. + +

+

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

5.2.2 Simulated Menu Listing

 + +

+ This option will read through the specified menu file and create a + simulated menu listing. The listing will display the menu in as close + an approximation as possible on a hardcopy printer. The option will + only report on one menu file at a time and will be sorted in + alphabetical order by menu name. + +

5.2.3 Detailed Menu Listing

+ +

+ The detailed menu report lists all available information about the + specified menu file. This report is particularly useful for double + checking the action fields and security. + +

5.2.4 Hierarchical Listing

+ +

+ This report will display the structure of the menu system. The menus + are listed in the proper order as they appear on the menu. This option + will prompt for the top level menu file and menu where the listing is + to start. You need not necessarily start at the top of the entire menu + system. + +

5.3 OSA

+ +

+The OSA, OECN Security Authorization, Utility may be used in +conjunction with the OECN Menu Processor to fine tune security access. +OSA can be used to enable user's access to individual programs to be +granted or denied. This local security is defined by each +A-site and is maintained separately from the menu system included on +the OECN distribution. (See also VMS Manager's Guide) + +

+

+

Chapter 6
Customizing Menus from the Distribution

 + +

+ This chapter describes the recommended procedure for customizing the + menu files from the distribution. Following this procedure will ensure + that you can install future releases with minimum effort and maintain a + consistent user interface across the state. + +

+ Each major package has its own menu file. The file name for the primary + menu file ends with _MENU and has an extension of .DAT. For example, + the USAS menu file is named BUD_MENU.DAT. On the main menu of each + package there is an item that links to a local menu file. This + local menu file is an empty menu file that you may customize as you + wish. The local menu filenames end with _LCL. Therefore, the USAS local + menu is named: BUD_LCL.DAT. + +

+ It is recommended that you only modify the *_LCL menu files. If you + modify the other primary menu files, you will not be able to install + updated menu files in the future without making all of your + modifications over again. + +

+

+ + + + +
Note
+Security for all menu items may be customized, even if they are part of +the distribution, without modifying the menu files. This is +accomplished by using the OECN Security Authorization (OSA) utility. +See the OECN Software Security for the VMS System Manager +manual for information about the OSA utility and local security.
+
+ +

6.1 Modifying a Local Menu File

 + +

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

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

6.1.1 Redefine the OECN$MENU$FILES logical

 + +

+ The first step is to redefine OECN$MENU$FILES as a search list. For + consistency with other customized files, it is recommended that you use + OECN$CUSTOM. However, you may use any directory that you wish. The rest + of this chapter assumes that you are placing the customized menu files + in OECN$CUSTOM. For example: + +

+ + +
+
+
+$ DEFINE/SYSTEM OECN$MENU$FILES -
+_$ OECN$CUSTOM,DUA0:[ODE.MENU.DIST]
+
+
+ +

+ This will cause the Menu Processor and MENUUTL to search first through + OECN$CUSTOM and then the distribution menu files. + +

+

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

6.1.2 Modify the Menu Files

 + +

+ Copy the *_LCL.DAT menu files that you want to modify from the + distribution into OECN$CUSTOM. Then use MENUEDT to make the desired + modifications. By making all modifications in OECN$CUSTOM: will insure + that installing future releases will not overlay your customized local + menus. + +

+ Use the Menu Processor and MENUUTL to test the new menus as needed. If + you're creating new menus, be sure that the users have read access to + the new files. + +

6.1.3 Build a New Alias File

+ +

+ After all desired changes have been made, use MENUUTL to rebuild the + alias file. You may put the alias file in OECN$CUSTOM or simply replace + the current alias file in OECN$ALIAS. If you change the location of the + alias file be sure to redefine the OECN$ALIAS logical. + +

+ You may build the alias file manually by running MENUUTL, or you may + use the BUILD_ALIAS.COM procedure in the OECN$ directory. + +

6.1.4 Redefine OECN$MENU$FILES Permanently

+ +

+ If you have not already done so, define the logical OECN$MENU$FILES to + be a search list as above at the SYSTEM level. + +

+ At this point your users should have access to the customized menus. + +

6.2 After a Distribution

+ +

+ If you modify the local menu files in this way, your changes will not + be affected by any future releases. Changes made by SSDT will + automatically be installed when you copy the distribution menu files to + the OECN$MENU$FILES directory. + +

+However, you will have to rebuild the alias file after installing each +distribution. After a package has been installed and the menu files +moved to thier proper location, you must rebuild the alias file. + +

+ You may build the alias file manually by running MENUUTL, or you may + use the BUILD_ALIAS.COM procedure in the OECN$ directory. The + BUILD_ALIAS.COM procedure will automatically build a new alias file + using the files in OECN$MENU$FILES. You can run the procedure + interactvely by typing: + +

+ + +
+
+
+    $ @OECN$:BUILD_ALIAS 
+
+
+ +

+Or you can submit it for batch processing using DCL SUBMIT. By default, +BUILD_ALIAS will rebuild the default menu system based on the current +values of OECN$MENU$FILES, OECN$MENU and OECN$ALIAS logicals. If you +have other menu systems on your system, you can pass parameters to +BUILD_ALIAS to indicate the location and names of the menu and alias +files. See the comments in BUILD_ALIAS.COM for more information about +using this procedure. + +

6.3 Intercepting Menu Actions

+ +

+ Sometimes it is desirable, or necessary, to redefine the action + associated with a menu item. For instance, you may want to force + certain actions prior to running a particular program or force certain + options to run in batch. + +

+ This may be done by intercepting the action line of specific options + without modifying the menu files supplied by SSDT. You must + write a DCL command procedure that will replace the action line you are + going to intercept. Then assign a special logical to point to this + command procedure. + +

+ The logical must be defined as follows: + +

+ + +
+
+
+$ DEFINE/SYSTEM OECN$MENU_ACTION_label filespec 
+
+
+ +

+ Where label is the menu option label that you want to + intercept and filespec is the full filespec of the DCL command + procedure. The logical may be defined at the system, group or process + level, so you may intercept the action line for different classes of + users. + +

+

+ + + + +
Note
+ If the logical is defined system-wide it will affect all menu systems + that you have active on your system. If you have multiple menu systems + that contain the same label then they will all be affected. If this is + not what you want you may need to define this logical at the group or + process level.
+
+ +

+ After this logical is defined the command procedure will be executed + instead of the action line defined by the menu file. + +

+ The following parameters will be passed to the command procedure : + + + + + + + + + + + + + + +
+ P1 + + Menu label name that invoked the procedure +
+ P2 + + Original action line defined by the menu file +
+ P3-P8 + + Other parameters entered by the user +
+ +

+ The procedure may use these parameters as it wishes or ignore them. + +

+ For example, suppose that you want to automatically execute a backup of + the USPS files prior to the user running BUDDIS. The following + procedure, called PAY:BUDDIS_ACTION, might be used: + +

+ + +
+
+
+$! 
+$! PAY:BUDDIS_ACTION.COM -- Procedure used by the BUDDIS menu option 
+$! 
+$ on error then exit 
+$ 
+$ @PAY:SAVEPAY    ! A-site procedure to perform disk backup set of 
+$                 ! USPS files. 
+$ 
+$ DEFINE/USER SYS$INPUT SYS$COMMAND 
+$ RUN OECN$PAY:BUDDIS 
+$ 
+$ EXIT 
+
+
+ +

+ The following logical definition would be made to intercept the BUDDIS + action for all users: + +

+ + +
+
+
+$ DEFINE/SYSTEM OECN$MENU_ACTION_BUDDIS PAY:BUDDIS_ACTION 
+
+
+ +

+

+

Chapter 7
Batch Mail Message System Manager Guide

 + +

7.1 Overview

 + +

+The command procedure BATCH_MAIL_MESSAGE.COM can be used to send a VMS +mail message via a batch job. This is useful for messages with large +audiences where the user does not wish to tie up their terminal for an +extended period of time. + +

7.2 Sending a Mail Message via Batch

+ +

+To use the command procedure for generic mail messages: + +

+Create the desired mail message using a text file. + +

+Submit the procedure as follows supplying the necessary parameter +values: + +

+ + +
+
+
+$ SUBMIT OECN$:BATCH_MAIL_MESSAGE/PARAMETER=("P1","P2","P3","P4")
+
+
+ +

+Where: + +

+ +

+ +

+

Chapter 8
OECN VIEW Utility

 + +

8.1 Overview

 + +

+The OECN_VIEW utility allows users to view text files on the screen. It +can be used for report files produced by OECN state software or other +text documents. OECN_VIEW is a TPU based product, layered on DEC/EVE. + +

+By default, OECN_VIEW will search for files in OECN$OUT which have the +following extensions: *.TXT, *.LIS, *.DOC, *.RPT, *.LPT, *.RPT. These +are the only files that OECN_VIEW will show to the user when they use +the "Go_File" function or invoke VIEW without a file name. + +

+However, A-sites may customize both the directory and/or the extension +if desired. Define the OECN_VIEW_DIRECTORY logical to define the +directory(ies) to be searched. It may be a search-list. The default for +OECN_VIEW_DIRECTORY is OECN$OUT. + +

+In order to change the file extensions, define the logical +OECN_VIEW_FILES to be a search list containing the filespecs to search. +Each entry in the search list must refer to OECN_VIEW_DIRECTORY. + +

+Examples of the logicals are given below: + +

8.2 OECN_VIEW.COM

+ +

+The OECN_VIEW.COM command procedure is found in OECN$. It is used to +define the two logicals, OECN_VIEW_DIRECTORY and OECN_VIEW_FILES. +Observe the following notes from this procedure. + +

+ + +
+
+
+ 
+ 
+$!+ 
+$! Notes: 
+$! 
+$!  This procedure is a shell for the OECN_VIEW utility.  It provides 
+$!  defaults for the file directory and file types that the user may view. 
+$! 
+$!  A-sites can configure VIEW to behave differently if desired by defining 
+$!  the following logicals: 
+$! 
+$!   OECN_VIEW_DIRECTORY =  Defines the directory OECN_VIEW will search 
+$!       when user uses the 'Go File' command or invokes 
+$!       VIEW without a file name.  This logical may 
+$!       be a search list.  The default is OECN$OUT. 
+$! 
+$!   OECN_VIEW_FILES = Filespecs which user can see when the use 
+$!     'Go file'.  The logical should be a searchlist 
+$!     containing wildcard specfications for the files 
+$!     names or types the user can view.  Each 
+$!     equivalence string must refer to OECN_VIEW_DIRECTORY 
+$!     for the device/directory.  That is, OECN_VIEW_FILES 
+$!     should specify just the wildcard filename and type. 
+$!- 
+ 
+ 
+
+
+ +

8.2.1 Customizing OECN VIEW

+ +

+The following sample command file shows how to customize the +directories and the file extensions to be viewed. + +

+ + +
+
+
+ 
+ 
+$!+ 
+$! VIEW_EXAMPLES.com 
+$! 
+$!  Example of using OECN_VIEW to view shared documents.  This 
+$!  command procedure may be added to a local menu to allow 
+$!  users to view documents on-line. 
+$! 
+$!  In this example, users are given the ability to view internet documents. 
+$!  Allows users to view *.TXT and *.DOC files in the directory 
+$!  PUB:[INTERNET_DOCS]. 
+$! 
+$! - 
+$ set noon 
+$ set noverify 
+$ 
+$ define/user  OECN_VIEW_DIRECTORY PUB:[PUBDOM.NWOCA.INTERNET_DOCS] 
+$ 
+$ define/user  OECN_VIEW_FILES  OECN_VIEW_DIRECTORY:*.TXT,- 
+     OECN_VIEW_DIRECTORY:*.DOC 
+$ 
+$ @oecn$:oecn_view 
+$ 
+$exit 
+ 
+ 
+ 
+
+
+ +

8.2.2 Creating a DCL Command

+ +

+The VIEW utility works automatically from the MENU. However, you could +define a symbol to execute VIEW from DCL. + +

+For example, define: + +

+ + +
+
+
+ 
+LOOK := = @OECN$:OECN_VIEW
+ 
+
+
+ +

+Then use the LOOK command from the $ prompt. + +

8.2.3 OECN_EDIT

+ +

+The OECN_VIEW utility uses a special editor called OECN_EDIT. Its +purpose is to provide I/O routines to allow TPU to automatically read +and translate VFC files into text. Please see Chapter 9, OECN EDIT Utility, for more +details. +

+ +

+

Chapter 9
OECN EDIT Utility

 + +

9.1 Overview

 + +

+OECN_EDIT is a foreign command replacement for the EDIT/TPU DCL +command. It is completely command line (qualifier and parameter) +compatible with EDIT/TPU. Its purpose is to provide I/O routines to +allow TPU to automatically read and translate VFC files into text. When +using OECN_EDIT, all VFC files read by TPU are converted into text with +form-feed and line-feed characters to preserve formatting. All other +file types are NOT affected by OECN_EDIT and are read normally by TPU. +This is different from the default TPU editor, which ignores VFC +formatting. OECN_EDIT is used by the OECN_VIEW.COM procedure to allow +VFC files to be viewed correctly. However, it may also be used with any +TPU section file as an editor. + +

9.2 Using OECN_EDIT

+ +

+In order to use OECN_EDIT as your interface to TPU, define the +following symbol: + +

+ + +
+
+
+ 
+$ EDIT := = $OECN$:OECN_EDIT/TPU
+ 
+
+
+ +

+Note: The /TPU qualifier is required. + +

+You may also include other qualifiers which you would normally use with +EDIT/TPU, such as /SECTION, /UNIT, etc. OECN_EDIT will use the normal +EVE section and initialization files by default. +

+ +

+

Chapter 10
OECN KEYMAP Utility

 + +

10.1 Overview

 + +

+The OECN_KEYMAP utility allows users to select a terminal emulator, +such as REFLECTIONS, EXCURSIONS, or PERSONA. Using this utility defines +the logical OECN$KEY_MAP to point to a .INI file containing the desired +keymapping. The mapping allows you to re-label the standard function +keys. You cannot actually reassign the program functions to different +keys. That is, from the programs point of view, the user is required to +press a VT200 F11 for the "Find" function. However, you can assign F11 +to any PC key you wish in the emulator and then relabel F11 on the +screen to match the PC keyboard. + +

10.2 Using KEYMAP

+ +

+Upon selecting the KEYMAP option from the OECN menu the user is given a +list of keymapping options to select from. This menu of options is +built by searching for all files named OECN$KEYMAP*.INI in either the +OECN$ or the OECN$CUSTOM directory. If the same filename is found in +both directories, only the one in OECN$CUSTOM will be used. The +description used in the menu will be determined by whether or not a +"DESCRIPTION=xxx" command is used. If the command is found in the .INI +file, the description will be used for the menu, otherwise the filename +will be used in the menu. + +

+When a user selects their option, the name of the .INI file selected is +recorded in a file called OECN$KEYMAP.DAT in their SYS$LOGIN directory. +If keymapping is turned off, the OECN$KEYMAP.DAT file is deleted from +the SYS$LOGIN directory. + +

+The OECN_LOGIN procedure has been modified to look for the existence of +this file and define the OECN$KEY_MAP logical to point to the .INI file +found in the .DAT file. After selecting their option in KEYMAP, +OECN_LOGIN will be immediately executed causing the logical to be +defined for that process. Then, each time the user logs in, OECN_LOGIN +will check for the OECN$KEYMAP.DAT file and set the OECN$KEY_MAP +logical appropriately for that process. + +

+The following standard .INI files have been created: + +

+ +

+These files may be used as a starting point to create other .INI files +for other terminal emulators that may be in use by districts or to +support customized key mappings for districts. Instructions are +included at the top of the .INI files which explain how the files need +to be formatted and which keys are able to be mapped. It is recommended +that the new .INI file be placed in the OECN$CUSTOM directory and be +given a different name if it is to be an additional menu option. It is +also recommended that the description inside the .INI file be changed +to something meaningful to the user as this is what they will see in +the KEYMAP menu. +

+ +

+

Chapter 11
OECN SETUPENV Utility

 + +

11.1 Overview

 + +

+SETUPENV is a general purpose utility for establishing or switching to +user environments. The goal of the utility is to provide a single place +to configure the software environment (primarily logicals) for given +entities and allow user processes to configure based on these +environment settings. + +

+The concept for SETUPENV is similar to the BUNNY/FROG utilities +available from NOACSC. However, it is intended to be more flexible and +capable of configuring multiple environments. SETUPENV is not tailored +to any particular software product. It may be used in the configuration +of state software, McSIS, InfOhio, or any other software that requires +logicals in establishing a user's environment. + +

+The general goals of the utility are as follows: + +

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

11.2 Getting Started

 + +

+The SETUPENV utility is very flexible allowing the capability to deal +with the variety of possible setups in use at the OECN DA Sites. This +flexibility leads to a significant number of options in both the DCL +command interface and options available in the OECN$SETUP +initialization file. However, it is unlikely that any one DA Site will +need all of the features provided by SETUPENV. Most sites will only +need a limited set of options. + +

+To get started with SETUPENV it is recommended that a simple OECN$SETUP +file with a minimal set of options for just a few entities be created. +Starting small will give the opportunity to experiment with the utility +to see how, or if, it can fit into your environment. + +

11.2.1 Entity Types

+ +

+SETUPENV manages a user's context by assuming that any given process +will have one context in each of the four entity "types". The current +types of entities are: + +

+ +

+Therefore, a user may have one entity selected in each of these types +and change the context for one entity without affecting the others. For +example, a user might have a context in DISTRICT_A and BLG_B but be +eligible to switch into several different LIBRARY entities. SETUPENV +will allow the user to switch into different libraries without +affecting the current district and building. + +

+Entities can be linked together to form logical hierarchies. For +example, a district entity might define the context for USPS, USAS, and +EMIS. A building entity might define the context for McSIS. When a user +selects a building, it may be desirable for the user's process to also +select the corresponding district entity so that the EMIS logicals are +switched automatically. SETUPENV can handle these relationships using +the PARENT attribute in the OECN$SETUP file. Please refer to the PARENT +attribute for more information. +

+ +

11.2.2 DCL Command Syntax

+
+ +

+SETUPENV must be defined as a foreign command: +
+ +

+ + +
+
+
+ 
+$ SETUPENV :== $OECN$:SETUPENV 
+ 
+
+
+ +

+Syntax: +
+ +

+ + +
+
+
+ 
+$ SETUPENV [entry_code...] 
+           [/MENU] 
+           [/NEXT] 
+           [/RESET] 
+           [/LOGIN[=([SIS],[INFOHIO],[BY_ACCESS],[USERNAME[=n]])] 
+           [/TYPE={DISTRICT,BUILDING,OTHER,ALL] 
+           [/LOG] 
+           [/[NO]PROMPT] 
+           [/CATEGORIES={wildcard}] 
+           [/APPLICATION={application}] 
+           [/ARCHIVE=[archive_code]] 
+           [/[NO]RESTRICT_IRNS] 
+           [/PRINT] 
+           [/USE] 
+           [/BUNNY] 
+           [/FROG] 
+           
+ 
+
+
+ +

+ +

Usage Notes

+ +

+When /NEXT is used, if the specified or next entry cannot be found +SETUPENV exits with an error severity. + +

+After successfully selecting an entry, OECN_LOGIN.COM is executed to +ensure the users OECN$x logicals are set correctly. If the DAS has +established the OECN_LOGIN_EPILOGUE procedure, it will subsequently be +executed. This provides a means for the DAS to customize the behavior +and do any additional processing after an entry is selected. + +

+Likewise, when /EMIS is specified, EMIS_SELECT_EPILOGUE and +EMIS_SWITCH_FY will be invoked after successfully selecting a database. + +

11.3 Logicals Created By SETUPENV

+ +

+After successfully selecting an entry, SETUPENV establishes a series of +logicals (OECN$SETUP_*) to describe the current context and to maintain +it's own context for subsequent invocations of SETUPENV. These logicals +may be used by DCL procedures but should never be modified or +deassigned (use SETUPENV/RESET to deassign the logicals if necessary). + +

+The logical OECN$SETUP_ENTRY contains the current selected entry. This +is the primary entry that was specified as a parameter, selected via +the menu, or selected using /NEXT. + +

+The logical OECN$SETUP_ARCHIVE contains the archive code if one was +selected using /ARCHIVE or the menu. + +

+One logical is defined for each of the entry types that has been +selected. A user can have one context in up to four different "types" +of entries: DISTRICT, BUILDING, LIBRARY, OTHER. For each type that has +been selected, the corresponding logical will be defined: + +

+ +

+The logical will not exist for types that have not been selected. + +

+The value of the OECN$SETUP_CURRENT_* logicals is a string that +describes the selected entry. The format for the string entry is: + +

+ + +
+
+
+        
+        "entry_code,irn,categories,applications" 
+ 
+        Where:  entry_code      the entry for this type 
+                irn             from IRN attribute 
+                categories      space delimited list of categories 
+                                from CATEGORIES attribute 
+                applications    space delimited list of applications 
+                                from APPLICATIONS attribute 
+        
+
+
+ +

+This string is formatted in a manner that is easily parsed using the +F$ELEMENT lexical function. + +

+The following logicals may also be defined depending on the selected +entries relationship with other entries: + +

+ +

+Any of the logicals that do not apply to an entry will not be defined +(e.g. for a parent entry, the siblings logical will not be defined). + +

11.4 OECN$SETUP.INI

+ +

+The OECN$SETUP initialization file defines the environment for various +entities which use OECN (or other) software products. The default +filename is OECN$CUSTOM:OECN$SETUP.INI. OECN$SETUP may be defined as a +logical to override the location and filename. + +

+Each "section" in the INI file describes an "entity". An entity might +be a district, building, library or other entity where a specific +context needs to be established. When the SETUPENV utility is executed +to select an entity, the context is defined as specified in the rules +for that section. + +

+The parameters and formats for each section are as follows: + +

+ +

11.4.1 Special "Reset" Entries

 + +

+Prior to setting any given entry, SETUPENV will attempt to process +special sections named "$RESET_type". If a $RESET section of the +appropriate type exists in the INI file, it will be processed prior to +setting an entry. + +

+The following reset sections may be specified: + +

+ +

+When a user selects an entry of a specific type, the corresponding +reset section is invoked prior to setting the environment for the +selected entry. + +

+This is useful in cases where some entries specify a process logical +but others use a group logical. In order to switch from one entry to +another, it is necessary to deassign the common logical from the +process table prior to switching to the group logicals. + +

+For example, consider that DISTRICT_A has a process logical definition +of OECN$DTA. But DISTRICT_B has a group logical for OECN$DTA. Switching +from DISTRICT_A to DISTRICT_B requires that the OECN$DTA be deassigned +so the group logical is visable. SETUPENV does not attempt to keep +track of this, rather it permits you to create a $RESET entry for each +type to deassign logicals appropriate for your site. For example, +$RESET could be defined as: + +

+ SECTION=$RESET_DISTRICT +
LOGICAL=OECN$DTA +
LOGICAL=OECN$OUT,"SYS$DISK:[]" +
+ +

+The above entry would cause SETUPENV to deassign OECN$DTA and define +OECN$OUT to the default directory prior to setting any valid entry. In +general, you should explicitly deassign any logicals in the reset +section that are defined in any entry of the same type. + +

11.4.2 Sample OECN$SETUP File

+ +

+Below is a very simple OECN$SETUP.INI file which defines entries for +one district and two buildings. The setup file can contain many such +entries for as many districts and buildings provided that the entry +codes are unique. + +

+ + +
+
+
+ 
+        SECTION=SAMPLE 
+        TYPE=DISTRICT 
+        DESCRIPTION="Sample City Schools" 
+        LOGICAL=EMIS_ROOT,          FSA:[EMIS_SAMPLE.],CONCEALED 
+        LOGICAL=OECN$DTA,           FSA:[SAMPLE] 
+        LOGICAL=OECN$FORM_DIRDEP,   OECN$PAY:DIRPRT.FRM 
+ 
+        SECTION=SAME 
+        TYPE=BUILDING 
+        DESCRIPTION="Sample Elementary School" 
+        PARENT=SAMPLE 
+        TABLE=SIS_SAME 
+        IDENTIFIER=SIS_SAME 
+ 
+        SECTION=SAMH 
+        TYPE=BUILDING 
+        DESCRIPTION="Sample High School" 
+        PARENT=SAMPLE 
+        TABLE=SIS_SAMH 
+        IDENTIFIER=SIS_SAMH 
+ 
+        SECTION=$RESET_DISTRICT 
+        LOGICAL=EMIS_ROOT 
+        LOGICAL=OECN$DTA 
+        LOGICAL=OECN$FORM_DIRDEP 
+
+
+ +

+In this example, the buildings point to the district using the PARENT +attribute. This creates the appropriate relationship. When the user +selects one of the buildings, the corresponding logicals from the +district entry will also be set. + +

+Also notice that the district entry uses LOGICAL's to define the +individual logicals. But the building entries use shared logical tables +created outside of SETUPENV. + +

+The special $RESET_DISTRICT section is provided to ensure that the +district logical get reset appropriately prior to setting an entry. + +

11.4.3 Special "APPLICATION" Entries

+ +

+If an entry is defined with one or more APPLICATION attributes, then +SETUPENV will search for an entry named "$APP_app", where "app" is the +application code. This allows logicals, symbols or tables that are +common for an application to be grouped into shared entries. Consider +the following example: + +

+ + +
+
+
+       SECTION=DISTRICT_A 
+       TYPE=DISTRICT 
+       APPLICATION=USAS 
+       LOGICAL=DISTRICT_ROOT,CONCEAL,DISK1:[DISTRICT_A.] 
+ 
+       SECTION=DISTRICT_B 
+       TYPE=DISTRICT 
+       APPLICATION=USAS 
+       LOGICAL=DISTRICT_ROOT,CONCEAL,DISK1:[DISTRICT_B.] 
+ 
+       SECTION=DISTRICT_C 
+       TYPE=DISTRICT 
+       LOGICAL=DISTRICT_ROOT,CONCEAL,DISK1:[DISTRICT_C.] 
+ 
+       SECTION=$APP_USAS 
+       LOGICAL=OECN$DTA,DISTRICT_ROOT:[DATA] 
+
+
+ +

+In this example, the DISTRICT_ROOT logical would be defined for all +three districts. However, OECN$DTA would only be defined for DISTRICT_A +and DISTRICT_B because they have APPLICATION=USAS. DISTRICT_C does not +have the application attribute and so would not invoke the $APP_USAS +entry. + +

+

+ + + + +
Note
+Note: The above is for example only. In practice, OECN$DTA might be +more efficiently defined as a system logical.
+
+ +

+Application entries do not have a corresponding "reset" section. +Logicals defined in this manner may need to be included in the +appropriate "$RESET_type" section to ensure they are reset. + +

11.4.4 Special "INCLUDE" Section

+ +

+A special section may be specified in any INI file called $INCLUDE. +This section may specify other INI files to be included and processed +with the primary INI file. The $INCLUDE section may only contain "FILE" +attributes to indicate the file(s) to be included. + +

+The $INCLUDE section permits INI files to be split into manageable +segments or for INI files to be generated automatically. For example, +you might create one INI file for each district and it's associated +buildings. Or a separate utility may have information for creating +subsets of the INI file. For example, the primary OECN$SETUP.INI might +have: + +

+ + +
+
+
+        SECTION=$INCLUDE 
+        FILE=OECN$CUSTOM:DISTRICT_A.INI 
+        FILE=OECN$CUSTOM:DISTRICT_B.INI 
+        FILE=OECN$CUSTOM:DISTRICT_C.INI 
+
+
+ +

+Each INI file may also have an $INCLUDE section to indicate other files +to be included. There is a maximum of 100 files that may be included +throughout all INI files. + +

+

+ + + + +
Note
+There is a performance penalty incurred for splitting INI files into +many parts. SETUPENV must read the primary and all included files each +time it is invoked.
+
+ +

+Duplicate entries are handled by merging the entries together. For +example, if two included files both contain an entry for DISTRICT_A, +then the attributes (e.g. LOGICAL attributes ) from both sections will +be combined into a single entry. If duplicate entries specify +attributes that only occur once per entry, then the last INI file to be +loaded supercedes the previous value. + +

+The INI files are NOT processed as they are encountered in the file. +Rather they represent a list of INI files that need to be processed. +SETUPENV will complete processing of the current file prior to begin +processing the next file. Therefore, included INI files will always be +processed after the file that included it (although perhaps not +immediately after). In general, you should not depend on files being +processed in any particular order. + +

11.4.5 Limits

+ +

+Certain limits which apply to the OECN$SETUP.INI file are shown in the +table below. Limits are 'per entry' unless otherwise noted.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 11-1 wide
Attribute Maximum Length Limit
+ FILE (in $INCLUDE section) + + 50 + + 100 total in all files +
+ SECTION + + 12 + + 500 total in all files +
+ DESC + + 40 + + 1 +
+ TYPE + + 12 + + 1 +
+ IRN + + 6 + + 1 +
+ CATEGORIES + + 40 + + 1 +
+ APPLICATIONS + + 10 + + 15 (five per line) +
+ ARCHIVE + + 6 + + 20 +
+ ARCHIVE (tables) + + 32 + + 3 per archive +
+ PROMPT + + 40 + + 1 +
+ IDENTIFIERS + + 80 + + unlimited * +
+ LOGICAL (name) + + 50 + + unlimited * +
+ LOGCIAL (value) + + 80 + + 4 per logical +
+ SYMBOL (name) + + 24 + + unlimited * +
+ SYMBOL (value) + + 50 + + 1 per symbol +
+ TABLE + + 50 + + unlimited * +
+ GROUP + + Octal Value + + 1 +
+ PARENT + + 12 + + 1 +
+ +

+

+ + + + +
Note
+* = Attributes which are "unlimited" are limited by virtual memory +available to the user. Very large INI files with large numbers of +logicals or symbols may exhaust virtual memory.
+
+ +

11.5 EMIS_SELECT Compatibility

 + +

+The /EMIS qualifier provides functional compatibility with the +EMIS_SELECT.COM procedure. In this mode, SETUPENV will read the +existing OECN$EMIS_DBS file and convert it to equivalent setup entries. +The primary advantage of using SETUPENV over EMIS_SELECT is it's +ability to use the /NEXT qualifier to process databases sequentially. +SETUPENV also provides a slightly improved user interface over the DCL +version. + +

+

+ + + + +
Note
+SETUPENV/EMIS can be used even if the DAS has not created an +OECN$SETUP.INI file.
+
+ +

+When SETUPENV/EMIS reads the OECN$EMIS_DBS, it creates a special entry +which is equavalent to: + +

+ + +
+
+
+         SECTION=$EMIS_dbscode 
+         DESCRIPTION=description from DBS 
+         CATEGORIES=RP_x FY_fy flags ! See below 
+         LOGICAL=OECN$EMIS$DTA,dev:[dir]  ! From DBS line 
+         IDENTIFIER=OECN_SYSMAN ! If the DBS line contained "HIDE" 
+
+
+ +

+The CATEGORIES is constructed based on the optional reporting period +and flags parameter from the DBS line. The CATAGORIES value will always +be in the format "RP_x FY_fy flags". Where x is the reporting period +and "fy" is the fiscal year from the EMIS configuration. If the DBS +included any additional flags (other than HIDE), they will also be +included in the categories. + +

+One implication of the above is that the /CATEGORIES qualifier can be +used to select specific reporting periods. For example: + +

+ + +
+
+
+        $ SETUPENV/EMIS/NEXT/CATEGORIES="*RP_N*" 
+
+
+ +

+Would select the next EMIS database for reporting period N. + +

+

+ + + + +
Note
+ SETUPENV will invoke the DA Site's EMIS_SELECT_EPILOGUE procedure if it + exists. However, the EMIS_SELECT_PROLOGUE is not supported. DA Sites + that depend on the prologue procedure should contact the SSDT for a + work around.
+
+ +

11.5.1 Converting OECN$EMIS_DBS to OECN$SETUP

 + +

+It is possible to completely convert from using the OECN$EMIS_DBS file +to corresponding entries in OECN$SETUP.INI. To do so, simply create +sections in the OECN$SETUP file as shown in the previous section. The +entry code must be prefixed with "$EMIS_". The corresponding code +should be removed from OECN$EMIS_DBS, otherwise they will both be +processed. + +

+To retain compatibility with EMIS_SELECT, you should be certain to +define the CATEGORIES attribute in the same format as shown. When +entries are stored in the OECN$SETUP file, SETUPENV will not access the +EMIS database to retrieve the fiscal year, therefore you should +explicitly include FY_fy in the CATEGORIES attribute. + +

+One advantage of converting DBS entries into OECN$SETUP is that the +entry definitions are not limited to defining a single logical +(OECN$EMIS$DTA). The $EMIS_ entries can contain any other valid +attribute types, including TABLE, APPLICATION, SYMBOL, etc. + +

+

+ + + + +
Note
+ At the time of this writing, the original EMIS_SELECT.COM procedure is + still invoked by the EMIS_SELECT menu option. Therefore, if you wish to + switch to SETUPENV immediately, you would have to modify the EMIS menu + or customize the EMIS_SELECT.COM procedure. In the future, + EMIS_SELECT.COM will be modified by the SSDT to use SETUPENV/EMIS + instead of the current DCL procedure.
+
+ +

11.6 NOACSC Compatiblity

 + +

+SETUPENV is similar to the USE, BUNNY, and FROG utilities provided by +NOACSC. In some respects SETUPENV is based on these utilities. While +SETUPENV is not 100% compatible with these utilities, it does attempt +to simulate most of the behaviors and should be able to co-exist with +them. + +

+To provide an easier transition for sites who are using NOACSC's +utilities, SETUPENV also provides command line compatibility with the +utilities. The following sections provide information regarding +compatibility with each of the utilities. + +

+Symbols may be established for each of the utilities to invoke SETUPENV +in the appropriate compatibility mode: + +

+ + +
+
+
+    USE :== $OECN$:SETUPENV/USE 
+    BUNNY :== $OECN$:SETUPENV/BUNNY 
+    FROG :== $OECN$:SETUPENV/FROG 
+
+
+ +

+This should allow SETUPENV to be used without modifying any existing +command procedures. + +

11.6.1 USE Compatibliity

+ +

+If /USE is specified as the first qualifier to SETUPENV, then the +original USE qualifiers are accepted. The table below lists the USE +qualifiers and the corresponding qualifier/behavor for SETUPENV. +/PROMPT is the default for /USE. + +

+The SETUPENV /PRINTER qualifier is the default. However, instead of +defining SYS$PRINT, LCL$PRINT is defined to point the queue from the +owner field. + + + + + + + + + + + + + + + + + + + + + + +
Qualifier SETUPENV Implementation
+ /OUTPUT + + Not implemented +
+ /ARCHIVE=nnnn + + /ARCHIVE=nnnn +
+ /HOME + + /RESET +
+ /PRIMARY_RUN + + /LOGIN=(SIS,INFOHIO,USERNAME=2)/NOPROMPT +
+ +

Notable Differences:

+ + + +

11.6.2 BUNNY Compatibility

 + +

+If /BUNNY is specified as the first qualifier to SETUPENV, then the +original BUNNY qualifiers are accepted. + +

+The SETUPENV defaults when /BUNNY is specified are: + +

+ + +
+
+
+        $ SETUPENV/BUNNY/PROMPT/EMIS=NORESTRICT_IRNS 
+
+
+ +

+These defaults are affected by the original BUNNY qualifiers per the +following table. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Qualifier SETUPENV Implementation
+ /ARCHIVE=nnnn + + /ARCHIVE=nnnn +
+ /CURRENT_BUILDING + + not implemented +
+ /EMIS + + not implemented (logicals defined by entry) +
+ /INFOHIO + + /LOGIN=INFOHIO +
+ /PRIMARY_RUN + + /LOGIN=(SIS,INFOHIO)/NOPROMPT +
+ /LOGICAL_ONLY + + /NOPROMPT +
+ /RESTRICT_IRNS + + EMIS=RESTRICT_IRNS +
+ /SCHEDULE_BUILDER + + Chains to SIS$EXE:SISMENU_CMSB.EXE +
+ +

+For interactive processes, if neither /PRIMARY_RUN nor /LOGICALS_ONLY +is specified then SETUPENV/BUNNY chains to SISMENU.EXE, unless +overridden by /SCHEDULE_BUILDER. + +

Notable Differences:

+ + + +

11.6.3 FROG Compatibility

 + +

+If /FROG is specified as the first qualifier to SETUPENV, then the +original FROG qualifiers are accepted. + +

+The SETUPENV defaults when /BUNNY is specified are: + +

+ + +
+
+
+        $ SETUPENV/FROG/PROMPT 
+
+
+ +

+These defaults are affected by the original BUNNY qualifiers per the +following table. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Qualifier SETUPENV Implementation
+ /CURRENT_BUILDING + + Not implemeneted +
+ /LOGICALS_ONLY + + /NOPROMPT +
+ /PRIMARY_RUN + + LOGIN=INFOHIO +
+ /PRINTER + + /PRINTER (see below) +
+ /OPAC=RESTRICTED + + Chains to "@LIS_MGR:OPAC" +
+ /OPAC=UNRESTRICTED + + Chains to "@LIS_MGR:OPAC R" +
+ +

+For interactive processes, if neither /PRIMARY_RUN nor /LOGICALS_ONLY +is specified then SETUPENV/FROG chains to "@LIS_MGR:LISMENU SYSADM.M"., +unless overridden by /OPAC + +

Notable Differences:

+ + + +

+ +

11.7 OECN$SETUPENV API

+SETUPENV provides a callable API which can be used by programs to +select entries. The API parallels the qualifier functions and syntax. + +

11.7.1 Working Storage Field(s)

 + +

+

+ + + + +
Note
+ Picture for string field are maximum sizes that will be used by + OECN$SETUPENV. The string fields are based by descriptor, so the field + sizes are not required to be the exact size.
+
+ +

+ + +
+
+
+ 
+       01   WS-FUNCTION             PIC S9(4) COMP VALUE 0. 
+            88  SET-DB                             VALUE 0. 
+            88  NEXT-DB                            VALUE 1. 
+            88  RESET-DB                           VALUE 2. 
+            88  MENU-SELECTION                     VALUE 3. 
+            88  LOOKUP-DB                          VALUE 4. 
+            88  LOGIN-DEFAULTS                     VALUE 5. 
+       01   WS-FLAGS. 
+            03  WS-SIS-DEFAULT      PIC X. 
+            03  WS-INFOHIO-DEFAULT  PIC X. 
+            03  WS-BY-ACCESS        PIC X. 
+            03  WS-BY-USERNAME      PIC X. 
+            03  WS-EMIS-RESTRICT    PIC X. 
+            03  WS-EMIS-SELECT      PIC X. 
+            03  FILLER                  PIC X(26). 
+       01   WS-SELECTED-DB          PIC X(40). 
+       01   WS-SEL-TYPE             PIC X(25). 
+       01   WS-SEL-CATEGORIES       PIC X(40). 
+       01   WS-SEL-APPLICATION      PIC X(10). 
+       01   WS-SEL-ARCHIVE          PIC X(6). 
+       01   WS-TYPE                 PIC X(25). 
+       01   WS-DESC                 PIC X(40). 
+       01   WS-IRN                  PIC X(6). 
+       01   WS-CATEGORIES           PIC X(40). 
+       01   WS-APPLICATIONS         PIC X(80). 
+       01   WS-PROMPT-STRING        PIC X(40). 
+       01   WS-ARCHIVE              PIC X(6). 
+       01   WS-STATUS               PIC S9(9) COMP. 
+            88  OECN__NORMAL        VALUE EXTERNAL OECN__NORMAL. 
+            88  OECN__NOMORE        VALUE EXTERNAL OECN__NOMORE. 
+            88  OECN__NOTFOUND      VALUE EXTERNAL OECN__NOTFOUND. 
+       01  WS-RELATIONSHIPS. 
+            03  WS-RELATION-COUNT    PIC S9(4) COMP. 
+            03  WS-RELATIONSHIP 
+                    OCCURS 0 TO 40 TIMES DEPENDING 
+                    ON WS-RELATION-COUNT. 
+                    05  WS-RELATION-TYPE        PIC X. 
+                    88  WS-RELATION-PARENT      VALUE "P". 
+                    88  WS-RELATION-SIBLING     VALUE "S". 
+                    88  WS-RELATION-CHILD       VALUE "C". 
+                    05  WS-RELATION-ENTRY       PIC X(12). 
+
+
+ +

+ +

11.7.2 COBOL Call Arguments

+ + + +
+
+
+      CALL "OECN$SETUPENV" 
+                USING 
+                    WS-FUNCTION 
+                    BY DESCRIPTOR WS-FLAGS 
+                    BY DESCRIPTOR WS-SELECTED-DB 
+                    BY DESCRIPTOR WS-SEL-TYPE 
+                    BY DESCRIPTOR WS-SEL-CATEGORIES 
+                    BY DESCRIPTOR WS-SEL-APPLICATION 
+                    BY DESCRIPTOR WS-SEL-ARCHIVE 
+                    BY DESCRIPTOR WS-TYPE 
+                    BY DESCRIPTOR WS-DESC 
+                    BY DESCRIPTOR WS-IRN 
+                    BY DESCRIPTOR WS-CATEGORIES 
+                    BY DESCRIPTOR WS-APPLICATIONS 
+                    BY DESCRIPTOR WS-RELATIONSHIPS 
+                    BY DESCRIPTOR WS-PROMPT-STRING 
+                    BY DESCRIPTOR WS-ARCHIVE 
+                GIVING WS-STATUS. 
+
+
+ +

+

+ + + + +
Note
+ The arguments passed by descriptor may be OMITTED if the return value + is not desired. However, the argument list must not be shortened, that + is, the caller should explictly include the OMITTED keyword.
+
+ +

11.7.3 Argument Descriptions:

 + +
+WS-FUNCTION (read) + +
+ Indicates the function to perform. Behavior matches the corresponding + DCL qualifiers. +
The LOOKUP-DB function is specific to the API and not implemented + via the DCL command. LOOKUP-DB returns the information about the + specified entry without actually setting the logicals. This allows a + program to retrieve information about an entry without switching + contexts. +
+
+
WS-FLAGS + +
+ List of one character flags which modify the behavior of the API. + Unless noted otherwise, the flags should either contain a spaces or a + "Y" if the flag is on. +
The following flags are applicable when the LOGIN-DEFAULTS function + is requested: +
+ +

+ + +
+
+
+                WS-SIS-DEFAULT      Same as /LOGIN=SIS 
+                WS-INFOHIO-DEFAULT  Same as /LOGIN=INFOHIO 
+                WS-BY-ACCESS        Same as /LOGIN=BY_ACCESS 
+                WS-BY-USERNAME      If set, just contain 
+                                    an ascii numeric value indicating 
+                                    the number of characters to use 
+                                    from the username as the entry 
+                                    code.  e.g. Placing "2" in 
+                                    this flag, is the same as 
+                                    /LOGIN=USERNAME=2 
+               WS-EMIS-RESTRICT     Same as /RESTRICT_IRNS 
+               WS-EMIS-SELECT is the same as /EMIS 
+
+
+ +
+
WS-SELECT-DB (modify, by descriptor) + +

+ Entry(s) from INI file to select. Optional if MENU or NEXT functions + are being performed. The actual entry selected is also returned in this + parameter. +
+
+
WS-SEL-TYPE (read, by descriptor) +
+
WS-SEL-CATEGORIES (read, by descriptor) + +
+ Values to restrict entries by type and/or categories. +
Same as /TYPE and /CATEGORIES qualifiers. +
+
+
WS-SEL-APPLICATION (read, by descriptor) + +
+ Value to select by application. Same as /APPLICATION qualifier. +
+
+
WS-TYPE (write, by descriptor) +
+
WS-DESC (write, by descriptor) +
+
WS-IRN (write, by descriptor) +
+
WS-CATEGORIES (write, by descriptor) + +
+ Return values which describe the entry. Same values that are also + placed in the OECN$SETUP_CURRENT Logical. +
+
+
WS-APPLICATIONS (write, by descriptor) + +
+ Space delimited list of appliations associated with the current entry. +
+
+
WS-PROMPT-STRING (write, by descriptor) + +
+ The string SETUPENV would use to create the DCL and Menu prompt if + /PROMPT is specified. Note: The API never sets the prompt. The calling + routine may use this string to set the prompts, if desired. +
+
+
WS-RELATIONSHIPS (write, by descriptor) + +
+ A structure that describes the selected entries relationship to other + entries based on the PARENT attributes. Currently three types of + relationships are defined: Parent, sibling or children. The types of + entries returned in this table will vary depending on the entry + selected. + +

+

+ + + + +
Note
+ Calling routines should not assume that only these three types of + relationships exist. Future versions of the API may return other + relationships.
+
+
+
WS-ARCHIVE + +
+ Contains code of archive if one was selected. +
+
+ +

11.7.4 Return Status

 + +

+OECN$SETUP returns one of the following conditions: + + + + + + + + + + + + + + + + + + + + + + +
+ OECN__NORMAL + + = + + Function completed successfully (Item selected or reset) +
+ OECN__NOMORE + + = + + When using "next" function, no more matching entries were found. +
+ OECN__NOTFOUND + + = + + Specified entry was not found. +
+ OECN__INVNEXT + + = + + Invalid combination of TYPE and current entry for NEXT function. Must + specify a starting entry or valid select type. +
+ +

11.7.5 Description

+ +

+The OECN$SETUPENV routine does basically everything that the SETUPENV +DCL interface does; however, there are some notable exceptions. Here is +a list that the callable interface does NOT provide: + +

    +
  1. Does not simulate /USE, /BUNNY or /FROG behaviors. Those qualifiers + are handled by the SETUPENV utility and are not exposed to the callable + interface. +
  2. Does not modify the Menu or DCL prompts (a string is returned for + setting the prompt if desired). +
  3. Does not invoke OECN_LOGIN or EMIS_SWITCH_FY to ensure that the + correct state software logicals are defined based on the version of the + data files. If the calling program depends on files/programs in any of + the OECN$x logicals, it should take it's own action to ensure the + correct version is selected (or contact the SSDT if this is important). +
  4. Does not implement the function of /PRINTER +
+ +

+ +

+

Chapter 12
Installing and Using UMP - User Mail Profile System

 + +

12.1 Overview

 + +

+ The UMP package provides a means for DA-sites to maintain user e-mail + profiles in a standard way. This will provides an efficient means of + sending mail to a large variety of users across the state. It will also + allows for the creation of an electronic "white pages phone directory" + which permits an easy way to lookup an e-mail address for any user on + the OECN network. + +

12.1.1 Feature List

+ +

+UMP provides the following features: + +

+ +

12.1.2 Web Attachments for OECN state-wide mail

 + +

+A special feature of the OECN state-wide lists is the ability to +"web-ify" attachments send to the OECN lists. As messages addressed to +the OECN lists pass through the central OECN mail server, they are +inspected for certain attachment types. If a suitable attachment type +is discovered, it is placed on a public web site and the original +attachment is replaced by a web link (URL) pointing to the documents +location. Thus, only a single copy of each attachment must be stored on +the OECN web server and will not be delivered to each user's mailbox. + +

+ Each user subscribed to UMP has the option of receiving the original + message with the attachments or the version containing web links + instead of attachments. Most users will benefit from receiving web + links instead of attachments (reduced local storage, shorter download + times and reduce risk of viruses. However, some users may prefer the + original attachments, especially if they download their mail for + disconnected (off-line) reading. + +

+ The benefit of web attachments to DA Sites can be signficant. Without + web attachments, any message containing a large attachment must be + delivered to each user's mailbox separately consuming considerable disk + space and computer resources to deliver. + +

+ However, each DA Site may decide how, and if, to implement OECN web + attachments for their users. Converting existing users to web + attachments may cause confusion or concerns. Therefore, DA Sites are + encouraged not to switch existing users to web attachments without + training or notification. + +

12.1.2.1 Enabling Web Attachments

+ +

+Web attachments are only enabled for each DA Site upon request. If you +wish your users to have the ability to request web attachments, you +must set ENABLE_OECN_WEBATTACH to "YES" and send mail to +listmaster@oecn.k12.oh.us. The listmaster will verify the correct +configuration of your UMP configuration and enable web attachments if +appropriate. Your request may be denied if you have a non-standard UMP +configuration. In that case, the listmaster will explain the problem(s) +with your configuration. + +

+ To see if web attachments are enabled for your site, look for the SITE + command in OECN$UMP_STANDARD.INI and see if the "webatt" parameter is + set for your domain. If this parameter is set, then web attachments are + already enabled. Note: You can not change OECN$UMP_STANDARD.INI + yourself. Only the OECN listmaster can make the change that affects the + OECN mail server. + +

12.1.3 Files

+ +

+The following sections describe the files used and produced by the UMP +system. +

+Files and Procedures Used +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
File/Procedure Use
+ OECN$UMP_LOCAL.INI + + Contains A-site specific information and list codes. +
+ OECN$UMP_STANDARD.INI + + Contains OECN_wide list codes and definitions. +
+ IMPORT_NM_LISTS.COM + + Used to import data from NM style distribution lists into user profiles. +
+ IMPORT_PMDF_LISTS.COM + + Used to import data from PMDF style distribution lists into user + profiles. +
+ EXPORT_LISTS.COM + + Used to generate both NM and PMDF style distribution lists. +
+ EXPORT_DD.COM + + Used to generate a file suitable for loading into a PMDF DIRECTORY + DAEMON database. +
+ UMP_SEND_CSO.COM + + Used to transmit UMP data to the CSO white pages directory. +
+

+Files Created +
+ +

+ The table below describes the files created by UMP. Unless otherwise + specified, the files are created in OECN$UMP:. + + + + + + + + + + + + + + + + + + + + + + + + + + +
File Description
+ MAIL_*_A.DIS + + One file for each distribution list. This file contains addresses of + users who have requested to receive original attachments sent to an + OECN list.. +
+ MAIL_*_W.DIR + + One file for each distribution list. This file contains addresses of + user who have requested web links to attachments sent to the an OECN + lists. +
+ MAIL_ALIASES.DAT + + Alias file defining aliases for UMP generated lists. This file is + intended to be loaded into the PMDF alias database or included into the + PMDF alias file. +
+ USER_ALIASES.TXT + + Alias file defining aliases for UMP remote users to create centralized + naming. This file is intended to be loaded into the PMDF alias database. +
+ USER_RESERVE.TXT + + File containing reversing entries for users to create centralized + naming. This file is intended to be loaded into the PMDF reverse + database. +
+ +

12.2 UMP Menu and Profile Screen

+ +

+The program may be executed by typing: + +

+ + +
+
+
+$RUN OECN$:UMP
+
+
+ +

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

+ + +
+
+
+Menu>UMP
+
+
+ +

+The Main UMP Menu +
+ +

+The following menu will appear: + +

+ + +
+
+
+ 
+ 
+___________________________________________________________________ 
+|                                                                 | 
+|  UMP - User Mail Profile Maintenance                            |                
+|  -------------------------------------------------------------  |  
+|     1. PERSONAL   - Modify Personal Profile                     |               
+|     2. MAINTAIN   - Maintain User Profiles                      | 
+|     3. EXIT       - Exit program                                |               
+|                                                                 |               
+|                                                                 |               
+|                                                                 |               
+|                                                                 |               
+|                                                                 |               
+|                                                                 |               
+|                                                                 |                
+|                                                                 |               
+|     Menu: UMP Option>                                           |               
+|                                                                 |               
+|   XXX Accept       XX  Help        XX  Exit        XXX Next     |          
+|_________________________________________________________________|                                                                 
+             
+ 
+ 
+
+
+ +

+Profile Screen +
+ +

+When you execute the UMP program and select the MAINTAIN option, a User +Mail Profile screen similar to the following will appear: + +

+ + +
+
+
+ 
+ 
+___________________________________________________________________________ 
+|                                                                         | 
+|                                             Updated  12-DEC-1995 16:26  | 
+|                                                                         |  
+| Username  DOE     Group         Node  NWOCAC   User Type  STAFF         | 
+| Internet Host/Mailbox    NWOCA.ORG                                      | 
+| Name   Doe, John                               Phone                    |  
+| Title  NBEC/NWOCA    SSDT Documentalist/Supp   Fax                      |   
+| Position Code                                  Cell/Pager               | 
+|                                                Alternate                | 
+| District IRN                                                            | 
+| Building IRN                                                            | 
+| County   Henry                                                          | 
+| District/Organization  NBEC/NWOCA                                       |   
+| Street Address                                                          |   
+| City, State, Zip                                                        |   
+| Comment                                                                 |   
+| URL                                                                     | 
+| Site information                                                        |   
+| Management Groups                                                       | 
+|                                                                         | 
+|                                                                         |   
+|  UMP: User Mail Profile for OECN Users                                  |   
+|   XX  Top             XXX  Find            XXX  Lockmode                |    
+|   XX  Help            XXX  Add             XXX  Set Defaults            |    
+|   XX  Exit            XXX  Delete          XXX  Email Lists             |    
+|   XXX Next            XXX  Modify                                       |   
+|_________________________________________________________________________| 
+ 
+ 
+
+
+ +

+EMAIL Lists +
+ +

+In order to view the Email lists you currently subscribe to, press the +[Email Lists] key. A screen similar to the following will +appear giving both OECN statewide and local distribution lists. + +

+ + +
+
+
+ 
+___________________________________________________________________________ 
+| User  DOE        Name  Doe, John                                        | 
+|                                Subscribe by name _________________      | 
+| Receive OECN attachments as web links?  Y                               | 
+|Subscribed?  --  Subscribed Distribution Lists --                        | 
+|   -- OECN lists --                                                      | 
+|    Y   MAIL_STAFF           DAS Staff   [Restricted]                    | 
+|    Y   MAIL_SUPT_PUB        Superintendents-Pub   [Restricted]          |   
+|    Y   MAIL_TREAS           Treasuere    [Restricted]                   | 
+|   -- NWOCA lists --                                                     | 
+|    Y   MAIL_SSDT            SSDT Staff                                  | 
+|    Y   MAIL_STAFF_EMIS      EMIS Staff                                  | 
+|    Y   MAIL_STAFF_FIS       Fiscal Staff                                | 
+|                                                                         | 
+|                                                                         | 
+|                                                                         | 
+|                                                                         | 
+|                                                                         | 
+|  Press <Show All Lists> to see all available lists                      | 
+|                                                                         | 
+|  UMP: E-mail Distribution Lists                              1 of   1   | 
+|   XXX Accept (Resort)       XX  Cancel                XX  Prev Screen   |  
+|   XX  First Screen          XXX Last Screen           XX  Next Screen   | 
+|   XX  Help                  XXX Show All Lists                          |  
+|   XX  Exit Dist Lists       XXX Exit Dist Lists                         | 
+|                                                                         | 
+|_________________________________________________________________________| 
+ 
+
+
+ +

+ The field "Receive OECN attachments as web links?" indicates if the + user wishes to receive links, instead of attachments, for files sent to + the OECN state-wide lists. + +

+You may subscribe or unsubscribe to any unrestricted list by entering +the name of the list in the indicated field at the top of the screen +and pressing the [Accept] key. +

+Table of Email Distribution Lists +
+ +

+In order to see the available distribution lists, press the [Show +All Lists] key. A set of screens such as the following will +appear: + +

+ + +
+
+
+ 
+ 
+___________________________________________________________________________ 
+|                                                                         | 
+| User  DOE        Name  Doe, John                                        | 
+|                                Subscribe by name _________________      |                   
+| Receive OECN attachments as web links?  Y                               | 
+| Subscribed?  --  All Available Distribution Lists --                    |        
+|   -- OECN lists --                                                      |       
+|        MAIL_CSTAFF          C-site staff (obsolete)                     |       
+|        MAIL_EMIS            EMIS Coordinators   [Restricted]            |       
+|    _   MAIL_LIBRARIAN       Librarian                                   |       
+|        MAIL_PRINC_NONPUB    Principals-Nonpublic   [Restricted]         |       
+|        MAIL_PRINC_PUB       Principals-Public   [Restricted]            |       
+|           MAIL_PRINC_ELEM      Principals-Elementary   [Restricted]     |       
+|           MAIL_PRINC_SEC       Principals-Secondary   [Restricted]      |       
+|    _   MAIL_SPECED          Special Education                           |       
+|    Y   MAIL_STAFF           DAS Staff   [Restricted]                    |       
+|        MAIL_SUPT_NONPUB     Superintendents-Nonpublic   [Restricted]    |       
+|    Y   MAIL_SUPT_PUB        Superintendents-Pub   [Restricted]          |       
+|           MAIL_SUPT_CITY       Superintendents-City   [Restricted]      |  
+|           MAIL_SUPT_COUNTY     Superintendents-County   [Restricted]    |   
+|  This is the first screen                                               |    
+|                                                                         |  
+|  UMP: E-mail Distribution Lists                              1 of   6   | 
+|   XXX Accept (Resort)       XX  Cancel                XX  Prev Screen   |  
+|   XX  First Screen          XXX Last Screen           XX  Next Screen   |   
+|   XX  Help                  XXX Show Subscribed                         | 
+|   XX  Exit Dist Lists       XXX Exit Dist Lists                         |   
+|_________________________________________________________________________| 
+ 
+ 
+
+
+ +

12.3 Startup Procedure

+ +

+ Follow the steps below to install UMP on your system: + +

    +
  1. Create the system logical OECN$UMP to point to the device and + directory where profile and distribution lists will be created. You + should NOT use the same directory as your NM: or OECN$MAIL directories. + You should create a new directory to contain these files. +
  2. Use OECN_INSTALL and INSTALL PACKAGE as usual to install the OECN + package. +
  3. If installing for the first time, copy OECN$UMP_LOCAL.INI to + OECN$UMP with world:read protection. +
    +
    Modify OECN$UMP_LOCAL.INI to contain A-site specific information. + You must specify A-site name, DECnet node, and internet host names, + etc. See the .INI file for more information. +
  4. Run the UMP.EXE program and choose the MAINTAIN option. Then exit + the program. This will create empy .IDX files in OECN$UMP. Set the + protections on the *.IDX files to W:RW. +
+ +

+ +

12.4 Loading Initial Data

+ Load existing distribution lists. If using NM style distribution lists, + then use: +
+$ @OECN$:IMPORT_NM_LISTS + +

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

+ Then run OECN$:UMP/MAINTAIN to review the user profiles. It should have + set, at least, the username, DECnet node, and host/domain. If the NM + lists were loaded, it will also have the name, district and county from + the NM lists. If a user was on more than one list, the user profile + will have multiple list codes. + +

+ After running the import, the protection on the UMP*.IDX files should + be set to W:RW. + +

+ You may, if desired, import from both the NM and PMDF style lists. + Unique usernames will only be added once, and a user will not be + assigned to the same list more than once. Running both imports + essentially "merges" the NM and PMDF lists. This might be useful if you + are uncertain which of your lists is more correct. + +

12.5 Importing Other Lists

+ +

+ The IMPORT_NM_LISTS.COM and IMPORT_PMDF_LISTS.COM only import the + standard NM lists or lists created by SWOCA's OECN$MAIL utilities. If + you have other local lists which contain users you want to assign to a + list (either a standard list or a local list), you can use the + UMPIMPORT.EXE utility directly. + +

+ The UMPIMPORT utiltiy can read an existing list (either NM or PMDF + format) and assign the users to the distribution list code you specify. + The UMPIMPORT utility takes three parameters in the following form: +
+ +

+ + +
+
+
+$ UMPIMPORT :== $OECN$:UMPIMPORT 
+$ UMPIMPORT {NM|PMDF} {code} {file} 
+
+
+ +

+ The first parameter indicates if the list to be imported is a NM list + or a PMDF list. NM style lists must contain at least the DECnet + address. PMDF style lists must contain internet addresses. The second + parameter is the distribution list code to assign to the users. The + code must be defined in either OECN$UMP_STANDARD.INI or + OECN$UMP_LOCAL.INI. The final parameter is the file to import. See + either IMPORT_NM_LISTS.COM or IMPORT_PMDF_LISTS.COM for examples of + using UMPIMPORT.EXE. +

+ +

12.6 INI File Commands

+The following INI commands are used in either the OECN$UMP_LOCAL.INI or +the OECN$UMP_STANDARD.INI files. The following is a summary of these +commands. See either of these files for more examples of their use.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 12-1 Table of INI File Commands
 Command  Fields Explanation
+ * + + SET_ASITE + + = + + "{Asite}" + + A-site acronym. Required field. +
+ * + + SET_NODE + + = + + "{Node}" + + Default DECnet node, cluster prefered. Required field. +
+ * + + SET_DOMAIN + + = + + "{Domain}" + + Default domain. Used as default for user profile and PMDF aliases. For + example, SET_DOMAIN = "NWOCA.ORG". Required field. +
+ * + + SET_USER_TYPE + + = + + "{Code}" + + Default for "User Type" field. +
+ * + + LOCAL_LIST_PREFIX + + = + + "{Prefix}" + + Alias prefix for local distribution lists. Example, LOCAL_LIST_PREFIX = + "Local_". May be null if local lists are not to be prefixed. +
+   + + LOCAL_HOST + + = + + "{hostname}" + + This parameter defines host name(s) which should be considered "local" + to the current system. You may include multiple LOCAL_HOST lines if + needed. If a users "internet mailbox/host" field contins a local + address, then a user alias will not be created for them. Use this + parameter if you change the domain specified by SET_DOMAIN but you + still have user profiles which refer to the old address. Without this + parameter, UMP will consider profiles with the old domain to be remote + users and will create aliases for them. +
+ * + + PROCESS_CHANNEL + + = + + "{process_channel_name}" + + This parameter may be used to set the name of the reprocess channel to + be used for processing UMP distribution lists. By default, UMPEXPORT + will assume the reprocess channel is named reprocess.domain_name where + domain_name is the domain from the SET_DOMAIN parameter. +
+ * + + DIRECTORY_DOMAIN + + = + + "{directory_daemon_domain}" + + This parameter may be used to specifically set the name of the + directory daemon domain, if any. If this parameter is not specified + then UMPEXPORT will assume that the directory daemon is named + PO.domain_name where domain_name is the deomain from the SET_DOMAIN + parameter. +
+   + + REWRITE + + = + + "{user@host}","{To_Domain}" + + Used by the UMPEXPORT to rewrite a particular domain to a + "pseudo_domain" for public use in the CSO (White Pages) and for address + reverals. The pseudo_domain may be name of your directory channel or an + alias for the local host. For example, REWRITE = *,"po.nwoca.org". In + this example, the command would cause all of NWOCA's users to have an + email address of "username@po.nwoca.org" regardless of their real host + name. In this way, remote users will not learn the real host name + (which may change). REWRITE supports full wildcarding on the "From" + domain portion of the parameter. The user@host may be a wildcard + pattern which matches user email address from the UMP profiles. The + new_host is the domain that the address will be rewritten to. This + parameter allows you better control over how addresses are published in + the CSO database (OECN White Pages) and address reversal +
+   + + CSO_REWRITE + + = + + Synonym for REWRITE + +   +
+ * + + ERRORS_TO + + = + + "{Email_Address}" + + Address for "errors-to" parameter on mailing lists. If not preset, the + "errors_to" address defaults to "postmaster". +
+ * + + EMPTY_ADDRESS + + = + + "{Email_Address}" + + Email address to place in any empty distribution list to prevent + bounces to mail sent to an empty list. Defaults to "empty@bitbucket" + which is suitable if the default "bitbucket" channel is defined. +
+ * + + ENABLE_OECN_WEBATTACH + + = + + {YES|NO} + + Enables users to request and receive "web attachments" sent to the OECN + lists. Default is "YES". Set to "NO" to prevent users from requesting + web attachments. +
+ * + + OECN_WEBATTACH_DEFAULT + + = + + {YES|NO} + + Specifies the "web attachment" default for new users. By default, new + users will receive web links instead of attachments. Set this to NO if + you wish new users to recieve the original attachments. +
+ * + + ALLOW_USER_ALIAS + + = + + {YES|NO} + + Indicates whether the 'Alias' and 'From' fields should be activated. + When set to NO (the default), the alias and from fields will be + disabled. When set to YES, the fields will be active. Note: When set to + YES, the DAS must customize thier procedures to load the + USER_ALIASES.TXT and USER_REVERSE.TXT file into the appropriate PMDF + database. +
+   + + LISTPARMS + + = + + "{named parameter}" + + Specifies named parameter(s) to added to the MAIL_ and local aliases + created by UMP. Multiple named parameters may be specified using + multiple LISTPARMS lines. The named parameters will be included on all + MAIL_* and local UMP aliases. See the PMDF Managers Guide for + information about named parameters. Note: Too many named parameters may + prevent the alias from fitting in the PMDF Alias database. In that + case, the MAIL_ALIASES.DAT file must be included into the PMDF alias + file and the configuration compiled nightly. +
+ * + + PROTECT_SITE_INFO + + = + + [YES|NO] + + Protect "Site Info" field in UMP. The default is "YES". +
+   + + TYPE + + = + + {Type},"{Description}" + + Defines a distribution list type. Types 01---0z are reserved for OECN + use. Types 10---zz are available for DAS use. Types must be defined + prior to using a DEFINE_CODE line. +
+   + + DEFINE_CODE + + = + + [Type-],{Code},"{Description}", {List_Name},[User_Modifiable], + [Master_Code] + + Type is a two digit no., considered above. Code is a 1 to 8 character + code used in the UMP maintenance program. List_Name is the file name + suffix used to create the distribution list filename. User_Modifiable + (Y,N) allows the user to subscribe or unsubscribe to the list. The + default is "NO", which means that the list is restricted. Master_Code + contains the master list code to which a sublist refers. In the case of + a master list, this field also contains the master list code. See the + section, Defining Local Distribution Lists, for more details. +

The default list type for codes in the OECN - wide file is 01. e.g. + in the OECN$UMP_STANDARD.INI file, DEFINE_CODE=COUN,... is equivalent + to DEFINE_CODE=01-COUN,... +

If the first character of the distribution codes is a hyphen (--), + the distribution list is obsolete and should be phased out. This means + that the export routines will not force creation of an alias pointing + to empty distribution lists and will not assign these empty lists as a + sub-list of a master list. +

+   + + TYPE_RESTRICT + + = + + {Type},{Method},{Value} + + For example, TYPE_RESTRICT= 02,SUBSCRIBED,01-STF, restricts type 02 + lists to users who are also subscribed to the list 01-STF. See the + section below on Restricting Types, for more information and kinds of + restrictions. +
+   + + CONVERT + + = + + {From_Code},{To_Code} + + This command will automatically convert an "old" distribution list code + to a "new" one. For example, CONVERT = 01-PM,02-PM. The "From_Code" is + the old (original) distribution list code, and "To_Code" is the new + distribution list code. Note, that codes must specify both the type and + code (e.g. 01-PM). You should NOT rely on the default prefix when + specifying conversions. See the section below for more information on + conversions. +
+   + + NM_MAP + + = + + {From_Code},{To_Code} + + The command causes codes to be mapped to produce a single old-style NM + distribution list for compatibility with NM_SEARCH. +
+   + + SITE + + = + + "{Domain}",{CSO_ID} + + This command defines the OECN DAS host name. Each SITE in this section + will be included in the OECN_xxxx distribution lists. It also specifies + each site's CSO white pages identifiers. A range of CSO ids has been + allocated to each site. These fields should not be modified. This + command should not be placed in the OECN$UMP_LOCAL.INI file. +
+

+
+* This command can appear at most one time in the Local INI file. +
+
+

+ +

12.7 Export NM and PMDF Style Lists

+ A procedure called OECN$:EXPORT_LISTS.COM to is used to create the NM + and PMDF style distribution lists and associated aliases. It is + recommended that each DAS write a custom DCL procedure which invokes + EXPORT_LIST.COM which also contains any local commands to add aliases, + etc. This procedure should be scheduled to run nightly to keep the + aliases and distributions lists up to date. See Section 12.18 for an + example procedure which takes advantage of most of UMP's features. + +

+ To run the procedure: +
+ +

+ + +
+
+
+$ @OECN$:EXPORT_LISTS  "{options}" 
+
+
+ +

+ The P1 parameter should specify one or more of the following options + separated by commas: + + + + + + + + + + + + + + + + + + + + + + + + + + +
Option Description
+ REBUILD + + Rebuild the PMDF alias database from scratch using the alias file(s) + from UMPEXPORT. Use REBUILD if you allow UMP to control all the aliases + in your database, or if you add additional aliases after + EXPORT_LISTS.COM is executed. +
+ MERGE + + (Default) Merge the UMP aliases with the existing PMDF_ALIAS_DATABASE. + Use this option if you control/rebuild the alias files prior to + executing EXPORT_LISTS.COM Note: If this option is used then UMP will + always add aliases and old UMP aliases will not be deleted unless you + are rebuilding the database yourself elsewhere. +
+   + + Note: REBUILD and MERGE are mutually exclusive. +
+ USER + + Indicates that the USER_ALIASES.TXT and USER_REVERSE.TXT should be + loaded into PMDF_ALIAS_DATABASE and PMDF_REVERSE_DATABASE, + respectively. This should option should be specified if the DAS is + using remote addresses or user alias features of UMP. +
+ DEFER + + Defers placing updated PMDF databases back into the PMDF production + directories. This permits the DAS procedure to add additional aliases + to the database before being used by PMDF. If this option is specified + then the DAS's procedures are responsible for moving the databases back + into the PMDF production directories. The PMDF database files created + are: OECN$UMP:ALIASES.DAT (Alias database) OECN$UMP:REVERSE.DAT + (reverse database). +
+ +

+ If you are using UMP as your only source of PMDF database aliases, you + should specify REBUILD. This will ensure that any old or obsolete + aliases are not retained in your database. + +

+ However, if you have other aliases which you are building into your + local PMDF alias database, you must take local action to periodically + rebuild the PMDF alias database using your own aliases. This is + necessary to ensure that old aliases are not retained in your PMDF + alias database. + +

+ If you are unfamilar with how aliases work in PMDF and how the alias + database (PMDF_ALIAS_DATABASE) and the alias file (PMDF_ALIAS_FILE) + interact, we recommend that you do the following: + +

+ +

12.7.1 Centralized Naming

 + +

+ This section describes several ways in which UMP can be used to provide + centrialized naming in a PMDF configuration. Centralized naming + provides means to provide stable user email addresses regardless of + where the users mail is actually being delivered. This section assumes + you are already familar with the basic concepts of centralized naming + in PMDF. + +

12.7.1.1 Remote Mail Boxes

+ +

+ UMP can provide centralized naming for users who have "remote" + mailboxes. Using UMP's centralized naming, a user can have an address + such as USER@das.org even if thier mail is being delivered to a + different address (mailbox), regardless of where that mailbox resides. + The centralized naming may be used to deliver mail to remote systems on + behalf of the user, or simply as a means of forwarding mail without + resorting to VMS Mail forwarding. + +

+ Examples of "remote" users include: + +

+ +

+The primary benefit of centralized naming is that it permits a user to +have a stable mailing address even if the actual mailbox changes in the +future. Everyone with an DAS can have the same host name in thier +address regardless of where the mailbox reside. + +

+ UMP determines if a user requires an alias based on the "Internet + Host/Mailbox" field on the profile. If the "Internet Host/Mailbox" + field contains a different mailbox or a "remote" hostname, then the + user is considered "remote" and an alias is generated. The definition + of "remote" is if the host name portion of the address does not match + the value of SET_DOMAIN or any LOCAL_HOST in the OECN$UMP_LOCAL.INI. + For each user which UMP determines requires an alias, an line is + written to USER_ALIASES.TXT. A line is also written to + USER_REVERSE.TXT. USER_REVERSE.TXT contains the appropriate "address + reversal" entry which allows PMDF to adjust the user's "From:" address + for outgoing mail. + +

+ Both USER_ALIASES.TXT and USER_REVERSE.TXT are suitable for loading + into the PMDF_ALIAS_DATABASE and PMDF_REVERSE_DATABASE, respectively. + The use of these files is optional and is up to each DAS to determine + if they are useful in their configuration. EXPORT_LIST will not load + the files into PMDF by default. You must either set the USER option in + EXPORT_LISTS or write a custom procedure to load these files after + EXPORT_LISTS is executed. + +

+ Please note, the USER_REVERSE.TXT is only effective if mail sent by the + user is routed through your system. For remote systems running mailers + which send internet mail directly (such as a remote VMS system running + PMDF), you must use that system's mechanisms for rewriting "From" + address lines. For instance, on a remote PMDF system, adding a REVERSE + mapping to the PMDF_MAPPING_FILE may be appropriate. Alternatively, you + could take steps to ensure that all outgoing mail is routed through the + system containing the UMP reversing entries. + +

+ When exporting CSO, the user's real mailbox will be exported by + default. You can control this by using the REWRITE line in the local + INI file to rewrite addresses to either the DAS domain, a host alias, + or the directory channel. If you do this, be sure that you are loading + the appropriate file into either PMDF_ALIAS_DATABASE or your directory + channel. An address rewritten in this manner will be rewritten back to + the username or alias on the UMP profile (not the username in the + mailbox field). + +

12.7.1.2 User Aliases

+ +

+ UMP provides the ability to create a user-specific alias independent of + the username or actual mailbox. For example, a username of + "SMITH@nwoca.org" could have an alias of "dave.smith@nwoca.org". + Furthermore, the user alias may optionally be used as the user's + backward pointing (From:) address. This permits the user to have an + easier to remember address as well as obscuring the actual username for + security purposes. + +

+ The user aliases in UMP are implemented as two fields on the UMP + profile called "Alias" and "From". The alias is a 32 character field + which may consist of letters, digits or dots (.). The alias is required + to have a least one dot to avoid duplicates with VMS usernames. The + 'From' field is a flag indicating if the alias should be used as the + profile's official "From:" address. If the "From" flag is set to 'N', + then the alias is merely an alternative address for the user and will + be published in the CSO (White Pages). If the flag is set to 'Y', then + an entry will be added into the USER_REVERSE.TXT to reverse the + backward pointing addresses for any mail sent by the user. + +

+ The 'Alias' and 'From' fields may only be modified by a system or group + manager. That is, end-users cannot specify thier own alias or reversal. + This allows the appropriate manager to control the alias standards. It + also prevents users from changing thier alias or 'From:' address + frequently without understanding the implications or attempting to + forge mail messages. + +

+Group managers are required to specify an "alias prefix" which matches +one of the group codes they are responsible for. For example, if a +group manager is responsible for the groups "AA,AB", then they may only +specify aliases beginning with "aa." or "ab.". This helps ensure +uniqueness in the mailbox namespace when multiple group managers are +responsbile for different groups of profiles. + +

+ Since the DAS must take additional configuration steps in PMDF to + implement aliases and address reversal, the 'Alias' and 'From' fields + are disabled by default. The DAS must take explicit action (see below) + to implement this feature. + +

12.7.1.2.1 Implementing User Aliases

+ +

+ The following steps must be performed in order to activate the user + alias and address reversal using UMP: + +

    +
  1. Configure PMDF to use the 'reverse database' on the appropriate + channels. This feature is enabled by default in a standard PMDF + configuration. See the PMDF documentation for more information. +
  2. Set ALLOW_USER_ALIAS to YES in OECN$UMP_LOCAL.INI. This flag + enables the 'Alias' and 'From' fields in UMP. +
  3. Invoke EXPORT_LISTS.COM using the USER option to cause the + USER_ALIASES.TXT and USER_REVERSE.TXT files to be loaded into the + appropriate database. See Section 12.18, Example Procedure for Periodic Rebuilds for an example procedure which + invokes EXPORT_LISTS.COM. +
+ +

12.8 Distribution List Codes

 + +

+ Each distribution list code has a "type" prefix. The type value allows + distribution lists to be organized into subsets independent of the + list's name and allows restrictions to be placed on lists so users only + see lists that may apply to them. The type codes also ensure that lists + defined by the OECN do not conflict with those created by the DAS. + +

+ This version uses an 8 character code in the following format: +
+TT-CCCCCC + +

+ Where TT is the distribution list "type" (or category) and CCCCCC is + the distribution list code. The following types are predefined by UMP: + + + + + + + + + + + + + + + + + +
+   + + 01 + + OECN-wide user distribution lists +
+   + + 02 + + OECN DAS staff-only lists +
+   + + 10 + + Default type for lists defined by DAS +
+ +

+ Types beginning with "0" are reserved for OECN use. All other types + (any type not starting with "0) are available for use by the DAS. + Currently, a maximum of 100 types can be defined. + +

+ Type 10 is predefined and available for DAS use. To add additional + types add a line to the local ini file, like: +
+TYPE=tt,"description" + +

+ For example: +
+TYPE=11,"NWOCA Staff Lists" + +

+ Once a type has been defined, you may use the type in subsequent + DEFINE_CODE lines, for example: +
+DEFINE_CODE = 11-STFRCP, "Staff Recipes", STAFF_RECIPIES +
+DEFINE_CODE = 11-STFJOK, "Staff Jokes", STAFF_JOKES + +

+ This creates two lists called MAIL_STAFF_RECIPIES and MAIL_STAFF_JOKES. + When displayed in UMP, they will be sorted and displayed under a + subheading called "NWOCA Staff lists". +

+Restricting Types to Particular Users +
+ +

+ Using types allows you to organize your lists into categories for + presentation to the user. But it may also be useful to restrict + categories of lists to particular types of users. UMP allows you to + apply several types of restrictions based on the user's profile + information. + +

+ Note that type restrictions do NOT affect whether or not a user can + subscribe or unsubscribe from a given list. Each DEFINE_CODE line + determines whether a list is user-subscribable. The type restrictions + only limit whether the user can see a list or not. + +

+ Please note that the type restrictions are not intended as rigid + security. Since some of the criteria is based on user modifiable + fields, it is possible for a user to enter incorrect information and + get assigned to the wrong lists. For example, a user might enter + another district's IRN which allows them to subscribe to another + districts lists. However, if the user changes the IRN back to the + correct value, UMP will remove them from any incorrectly assigned lists. + +

+ To apply a restriction to a type value, use one of the following + commands in the local ini file: +
+ + + + + + + + + + + + + + + + + + + + + + +
+ TYPE_RESTRICT=tt,SUBSCRIBED,tt-cccccc + + Restricts type tt to users who are also subscribed to list tt-ccccc. +
+ TYPE_RESTRICT=tt,IRN,nnnnnn + + Restrict type to users who have a district or building IRN matching + nnnnnn +
+ TYPE_RESTRICT=tt,TYPE,xxxx + + Restrict type to users with a 'user type' field matching xxxxx. +
+ TYPE_RESTRICT=tt,COUNTY,xxxx + + Restrict type to users with a 'county' field matching xxxx. +
+ TYPE_RESTRICT=tt,USERNAME,wildcard + + Restrict type to users with a 'username' field matching wildcard mask. +
+ +

+ Multiple TYPE_RESTRICT lines may be added for a single list type. In + this case, the restrictions form a logical OR operation. That is, if + the user matches any one of the criteria, they will have access to the + type. + +

+ For example, to restrict the type 11 lists (from the example in the + previous section) to DAS staff members, the following restriction could + be applied: +
+ +

+ + +
+
+
+TYPE_RESTRICT=11, SUBSCRIBED, 01-STF 
+
+
+ +

+ This will restrict all type 11 lists to users who are also subscribed + to the standard DAS staff list. + +

12.9 Auto Conversion of Distribution List Codes (Optional)

+ +

+ Because of the features provided by the distribution list types, it may + be desirable for DAS's to change their existing distribution list + codes. By default, during the conversion, all distribution list codes + in the LOCAL INI file are prefixed with type 10. For instance, if a DAS + has defined several "staff" lists, you may wish to separate these into + a separate type and restrict them to staff members only. + +

+ To help facilitate this, an optional command is available for the LOCAL + INI file called CONVERT. The CONVERT command takes the following form: +
+CONVERT={old_code},{new_code} + +

+ For example, to convert an existing code of 10-SEM (Staff EMIS) to + 11-STFEMS, place the following line in the LOCAL.INI: +
+CONVERT=10-SEM, 11-STFEMS + +

+ Note that the prefix is required even if you did not use the prefix + when defining the code originally. Remember that any codes defined by + the local ini file default to type 10, so if a code was defined without + a type, it's type is 10. + +

+ When changing a existing code using a CONVERT line, you should change + the DEFINE_CODE line to reflect the new code at the time you add the + CONVERT line. You should not reuse old codes until you are certain they + no longer exist in the UMDDAT file. After you are certain the old code + no longer exists in the UMDDAT file, you may remove the CONVERT line + from your INI file. + +

+ Adding the CONVERT line and revising the DEFINE_CODE line, is all that + must be done to convert an existing list. UMP and it's utilities will + automatically convert the code as needed "on-the-fly". If you look at + the UMDDAT.IDX file after making a conversion, you may notice that some + users have the new code and others still have the old code. This is the + expected behavior. The new code will not be physically written to the + file until the record is changed with UMP's Modify function. + +

+ If you are creating locally written programs to update or report on + user's distribution list codes, it may be confusing to have both the + old and new codes on file. In this case, you may run the UMPUPDATE + program to force the conversion on all records. + +

12.10 Defining Local Distribution Lists

+ +

+To define a local distribution list, you need to add several additional +lines to the OECN$UMP_LOCAL.INI file. + +

+You will probally need to use the ini commands: +
+LOCAL_LIST_PREFIX, TYPE, TYPE_RESTRICT, DEFINE_CODE +

+Example 1 +
+ +

+The following example illustrates how to define a local distribution +list for payroll clerks. + +

+Add the following lines to the OECN$UMP_LOCAL.INI file: + +

+ + +
+
+
+TYPE = 12,"Local Payroll Clerks" 
+DEFINE_CODE = 12-PAYCLK,"Payroll Clerks",PAYROLL_CLERK 
+
+
+ +

+In order to actually subscribe to this distribution list, a user or DAS +person, will have to access the user's UMP profile, bring up the list +of available distribution lists, and subscribe the person. +

+Example 2 +
+ +

+As another example, suppose you wish to set up a distribution list for +staff jokes, restrict the list to just those users who have access to +DAS staff lists, create sublists for fiscal, programming, and EMIS +jokes, and set a prefix for local lists. + +

+Add the following lines to the OECN$UMP_LOCAL.INI file: + +

+ + +
+
+
+ 
+LOCAL_LIST_PREFIX = "local_" 
+TYPE = 11, "Local Staff Lists" 
+TYPE_RESTRICT = 11,SUBSCRIBED,01-STF 
+DEFINE_CODE = 11-STFJOK,"Staff Jokes",STAFF_JOKES,Y,11-STFJOK 
+DEFINE_CODE = 11-FISJOK,"Fiscal Jokes",FISCAL_JOKES,Y,11-STFJOK 
+DEFINE_CODE = 11-PRGJOK,"Programmer Jokes",PROGRAMMER_JOKES,Y,11-STFJOK 
+DEFINE_CODE = 11-EMSJOK,"EMIS Jokes",EMIS_JOKES,Y,11-STFJOK 
+
+
+ +

+Then those users who are subscribed to the 01-STF list will see the +following entry when they access the table of available lists in the +UMP program. +
+-- LOCAL STAFF LISTS -- +
+---LOCAL_STAFF_JOKES Staff Jokes +
+---LOCAL_FISCAL_JOKES Fiscal Jokes +
+---LOCAL_PROGRAMER_JOKES Programmer Jokes +
+---LOCAL_EMIS_JOKES EMIS Jokes +
+ +

+Users who are not subscrbed to the list 01-STF would see not entries +for "Local Staff Lists" including the heading itself. + +

+Note that the three sublists point to the master list, 11-STFJOK in the +DEFINE_CODE lines. This makes these sublists, so that mail addressed to +one of these sublists will be delivered to anyone on this list and +anyone on the master list, but not to users on any of the other +sublists. Also, mail addressed to the master list will be delivered to +everyone on any of the sublists. + +

12.11 Profile Group Management

+ +

+ UMP provides the ability to segregate profiles into management + groups and delegate responsibility for the groups to selected + individuals. Once delegated, the group manager has nearly complete + control over the content of the profiles in the groups they are + responsible for. They may add, change or delete profiles within their + group and assign profiles to unrestricted distribution lists. + +

+

+ + + + +
Note
+ Group managers may not add or remove profiles from the restricted + distribution lists. These lists (MAIL_STAFF, MAIL_SUPT_PUB, etc.) are + the responsibility of the DA-site and may not be delegated.
+
+ +

+ User profiles are assigned to groups simply by placing a value in the + 'Group' field on the UMP profile. If desired, the field may be massed + changed using Datatrieve by modifying the GRP field in the UMP_HEADER + domain or UMP view. This value is a protected field and may only be + changed by DAS personnel or a group manager associated with the group. + +

+ A user may be granted management rights to one or more groups by + entering a comma separated list of groups in the 'Management Groups' + field. A limit of ten comma separated groups may be included. The + following standard wildcards are supported in the management groups + field: + + + + + + + + + + + + + + + + + + +
+ * + + Any sequence of zero or more characters +
+ % + + Exactly one character +
+ # + + Exactly one numeric character +
+ @ + + Exactly one alphabetic character +
+ +

+ The user with any value in the 'Management Groups' field will be + permitted access to the MAINTAIN option in UMP. No special security + identifiers are required. The user will be able to view any profile on + the system, but will only be permitted to modify or delete profiles + associated with one of their groups. If a group manager adds a profile, + they must enter a group which matches their group management field. + +

+ The value of the group field is entirely arbitrary. The DAS may assign + the groups in any fashion desirable. Most likely, a group would be + created for all users in a district and one or more group managers + would be assigned to manage that district's profiles. However, groups + could be further defined by building, or perhaps by classes of users + (teachers, administrators, etc.). Since wildcards are supported, it is + possible to devise complex hierarchies of groups which permit different + users various levels of access. + +

+ Group managers should be carefully instructed regarding local + conventions for the various UMP fields. In particular, if the DAS uses + the USER_ALIAS.TXT to route mail to remote mailboxes, then proper use + of the UMP 'Internet Host/Mailbox' field is critical to ensure proper + mail delivery. Likewise, if the DAS uses the 'User Type' field to + control which profiles are sent to the OECN White Pages, then the + correct values must be provided to the group manager. + +

12.12 Export DIRECTORY DAEMON File (optional)

+ +

+ You have the option of exporting to a DIRECTORY DAEMON database. + Executing the EXPORT_DD.COM file will produce a file suitable for + loading into a PMDF DIRECTORY-DAEMON data file. The procedure only + produces a DIRECTORY-DAEMON.TXT file in the OECN$UMP directory. You + must execute the appropriate PMDF CRDB command to create the indexed + file database and place it in the PMDF_ROOT:[DIRECTORY] with the + appropriate filename for your pseudo-domain. + +

+ EXPORT_DD creates several aliases for each user. For example, the + following aliases would be created for username "SMITH" and a profile + name "Dave Smith": + + + + + + + + + + + + + + + + + + + + + + +
+ SMITH + + SMITH@nwoca.org +
+ dave.smith + + SMITH@po.NWOCA.ORG +
+ smith.dave + + SMITH@po.NWOCA.ORG +
+ d.smith + + SMITH@po.NWOCA.ORG +
+ smith.d + + SMITH@po.NWOCA.ORG +
+ +

+ Notice that the first alias (the username alias) sends directly to the + user's "real" address. The other aliases (dotted names) send to the + username at the directory channel. Since the username should be unique, + the first alias should never cause a bounce. The other addresses may + cause a bounce if they are not unique (the sender is notified of the + duplicates and their addresses). Since only dotted names and their + addresses are returned to the sender, the sender never learns the + "real" address. This helps isolate remote users from knowning the real + host names of the recipient. + +

+ The directory channel for the DAS is assumed to be "po." plus the value + of the SET_DOMAIN line from the OECN$UMP_LOCAL.INI file. For instance, + for nwoca.org, the directory channel is assumed to be po.nwoca.org. If + the DAS is using a different name for the directory channel, you may + place the following line in the OECN$UMP_LOCAL.INI file: +
+DIRECTORY_DOMAIN=pseudo.domain + +

+ See the PMDF System Adminstrators Guide for more information about the + directory daemon, channels and pseudo-domains. + +

12.13 Submit UMP Data to OECN CSO Database

+ +

+ The CSO nameserver is a public domain software system which allows a + single database to be built containing name and address information. + The CSO is much flexible and allows client/server access to the + database anywhere on the network. Users can use GOPHER, LYNX or other + web browsers to perform queries. A utility called PH is also available + to perform direct queries against the central database. + +

+ To transmit UMP data for loading into the CSO database, each DAS should + run the UMP_SEND_CSO.COM command procedure once per week. This command + procedure will extract the UMP database into CSO format and send it to + NWOCA.ORG for loading into CSO. + +

+ Unless instructed otherwise, please do not routinely run UMP_SEND_CSO + more than once per week. In general, a single weekly run is sufficient + to keep the OECN White Pages up to date. However, situations will arise + where an extra run of UMP_SEND_CSO is necessary or desirable. For + example, if you change domain names, or load a large number of new + users or make significant changes to the the profiles. In these cases, + feel free to make a special run of UMP_SEND_CSO. + +

+ NWOCA's system will run an update routine at approximately midnight + each night to load any files submitted during the day. Therefore, the + CSO data on file at the server will be updated the day after you run + UMP_SEND_CSO. This schedule means that your CSO data will be at most + one week behind when compared to your current UMP database. + +

+ If you are also using EXPORT_DD.COM to build a DIRECTORY-DAEMON + database, you may wish to have the email addresses in the CSO database + reflect your directory daemon address, rather than your user's real + addresses. In this case, you may add the following line to your + OECN$UMP_LOCAL.INI file: + +

+ + +
+
+
+    REWRITE=*,"pseudo_domain" 
+
+
+ +

+ Where "pseudo_domain" is the domain name of your directory channel, for + example, NWOCA uses the following line: + +

+ + +
+
+
+    REWRITE=*,"po.nwoca.org" 
+
+
+ +

+ This line would cause all of NWOCA's users to have an email address of + username@po.nwoca.org regardless of their real host. In this way, + remote users will not learn the real host name (which may change). + +

12.14 Master List/Sub-list Handling

+ +

+ Starting with the 29-Aug-95 version of UMPEXPORT, the master lists are + handled differently than in the past. Previously, there were master + lists which pointed to the respective sub-lists. But this caused + duplicate messages if the user was on more than one sub-list. With this + version, the master lists will contain the actual email addresses of + the users who are on the master list or any of the sub-lists. + +

+ There were also "compatibility" codes which were used for the original + NM distribution list codes. This proved too cumbersome and confusing. + Therefore, a new method of handling the master lists was implemented + which essentially combines the master lists with the NM-compatibilty + lists. + +

+ The codes PRN, SPT and TRS were previously indicated as "Obsolete-NM" + codes. This is no longer the case. These codes are now "master list" + codes (and indicated as such on the UMP help screen). If a user is + coded as having a "master list" code, they will placed on the master + list _and_ will also be placed on _all_ of the sub-lists for that code. + +

+ If a user is coded on one of the sub-lists, they will be placed on that + sub-list and the corresponding master list. + +

+ These changes provides two advantages: + +

    +
  1. It provides a simple way of placing a single user on all sub-lists + using a single code. For example, if a DAS staff member wishes to be + placed on all the MAIL_TREAS_xxx lists, they may simply be given the + TRS master code. This will cause them to be placed on the master list + and all of TRS's sub-lists. +
  2. Users which have not yet been recoded to one of the more specific + lists will automatically be placed on the master and all sub-lists. + This ensures that users who have not been recoded to the appropriate + list will still receive mail sent to any of the lists. +
+ +

+

+ + + + +
Note
+This change means that it is somewhat less important to get your users +migrated off of the old distribution list codes. However, if you leave +users on the master list codes, they may receive mail that was not +intended for them. For example, if mail is sent to mail_supt_jvsd, it +will be received by all users who are on the SPT or SJV lists.
+
+ +

12.15 UMPCHECK - Verifying UMP Profiles against SYSUAF (Optional)

 + +

+ UMPCHECK is a utility which reads the UMP profiles and compares the + usernames to the SYSUAF file. It reports usernames which do not exist, + have been disusered or dismailed. Optionally, UMPCHECK can delete + profiles for such usernames. By default, UMPCHECK only checks profiles + when the user's DECnet node name matches the values of the SYS$NODE or + SYS$CLUSTER_NODE logicals. Other users are considered to be remote + users and are not verified against the current node's SYSUAF. UMPCHECK + must be run as a foreign command and accepts the following syntax: +
+$ UMPCHECK {CHECK|DELETE|DELETE/CONFIRM} [nodes,...] + +

+ The first parameter is the function to perform: + + + + + + + + + + + + + + + + + +
+ CHECK + + -- + + Verify the UMP profiles against the SYSUAF and report usernames which + are invalid, disusered or dismailed. +
+ DELETE + + -- + + Unconditionally deletes local usernames which are invalid, disusered or + dismailed. +
+ DELETE/ +
CONFIRM + 		+ -- + + Same as DELETE but prompts whether each username should be deleted or + not. +
+ +

+

+ + + + +
Note
+ The function must be specified exactly as shown above without + abbreviation and there may not be spaces between DELETE and /CONFIRM. +
+
+ +

+ The second parameter indicates the node names of the users to be + validated against the current SYSUAF. By default, the node names used + are the current values of the SYS$NODE and SYS$CLUSTER_NODE logicals. +

+ +

12.16 UMP_LOGIN - To Prompt Users to Enter Profiles During Login (Optional)

+ UMP_LOGIN.COM may be run during login to determine if the user has ever + modified their own profile. If they have not entered their profile, + UMP_LOGIN will ask them if they would like to do so immediately and + place them in the UMP profile. + +

+ You may invoke UMP_LOGIN.COM at any point during login when appropriate + for your users. For example, SYLOGIN or other procedure appropriate for + your system. If you want UMP_LOGIN to be invoked automatically by + OECN_LOGIN, you may create a file in OECN$CUSTOM called + OECN_LOGIN_EPILOGUE.COM and execute OECN$:UMP_LOGIN from there. + +

+ If you use UMP_LOGIN.COM you may wish to use the VMS INSTALL utility to + install OECN$:UMPMODIFIED.EXE as a known image to speed up the login + process. + +

12.17 UMPID2DIS - Creating Distribution Lists from VMS Identifiers (Optional)

+ +

+ UMPID2DIS.EXE is an optional utility which builds PMDF style + distribution lists containing all users who hold a specified + identifier. This may be used by sites who wish to build distribution + lists for all users of a given package. These distribution lists are + not standard OECN-wide lists. + +

+ UMPID2DIS will only work correctly on your system if your UIC's are + unique. That is, each user (holder of an identifier) has their own + unique UIC. If two users hold the same UIC identifier, only one of them + will be output to the lists. + +

+ To create a distribution list for users holding a given identifier, use + the following commands: +
+$ ID2DIS :== $OECN$:UMPID2DIS +
+$ ID2DIS {identifier},... {distribution_list_file} + +

+ where "identifier" is the identifier. If you specify an OECN_ + identifier, users who hold the standard identifier or the _RO and _GM + variants will be included in the list. You may specify multiple + identifiers separated by commas (no spaces). If a user holds more than + one of the identifiers, they will only be included on the list once. +
+
"distribution_list_file" is the filename to contain the + distribution list. If a device and extention are not included, the + default is OECN$UMP:.DIS. +
+ +

+ Only users that meet the following criteria will be output to the list: + + + + + + + + + + + + + + + + + +
+   + + 1) + + The user holds one or more of the specified identifiers. +
+   + + 2) + + The UAF flags DISUSER and DISMAIL are not set. +
+   + + 3) + + The username has a valid UMP profile. +
+ +

+ Note that UMPID2DIS does NOT create the PMDF alias to point to the + distribution list. If aliases are desired for the list you must use + PMDF CRDB or PMDF DB to create the PMDF aliases. + +

+ For example, NWOCA could use the following commands to create a + distribution list for all NWOCA USPS users: +
+$ ID2DIS := $OECN$:UMPID2DIS +
+$ +
+$ ID2DIS OECN_USPS NWOCA_USPS +
+$ +
+$ PMDF DB +
+ open pmdf_alias_database +
+ override on +
+ add "nwoca_usps" "nwoca_usps-list@reprocess.nwoca.org" +
+ add "nwoca_usps-list" "<oecn$ump:nwoca_usps.dis,*,*,postmaster,*, + USPS" +
+$ EXIT + +

12.18 Example Procedure for Periodic Rebuilds

+ +

+ Periodically, each site should run EXPORT_LISTS.COM to update the + distribution lists from the UMP data. Most likely you will want to run + EXPORT_LISTS nightly. You should also run it anytime that you recreate + your PMDF alias database from scratch or make significant modifications + to the UMP profiles. + +

+ If you have PMDF's directory channel configured, you should run + EXPORT_DD.COM and build a new directory daemon database. You may also + to use UMPID2DIS to create distribution lists based on VMS identifiers. + +

+ You will most likely want to write a DCL command procedure to execute + all of the appropriate steps in a single batch job, and then schedule + it with DECscheduler. Attached is a sample of such a procedure which is + currently in use at NWOCA. You may wish to use this as a starting point + for your own procedure. + +

+ + +
+
+
+ 
+ 
+$!+ 
+$! NWOCA_EXPORT_UMP.COM 
+$! 
+$!  This procedure run the UMP routines to export distribution list, build 
+$!  aliases, etc. 
+$! 
+$! - 
+$! 
+$ SET PROC/PRIV=(BYPASS,SYSPRV,SYSNAM,SYSLCK) 
+$ SET VERIFY 
+$ SET DEFAULT OECN$UMP 
+$!+ 
+$! Temporarily suspend mail processing while lists are being 
+$! created and datbases rebuilt. 
+$!- 
+$ STOP/QUEUE/NEXT MAIL$BATCH 
+$!+ 
+$! Export distribution lists and rebuild PMDF databases. 
+$!- 
+$ @OECN$:EXPORT_LISTS "REBUILD,USER,DEFER" STAFFR 
+$ ! 
+$ ! Merge aliases for mail addressed to former MAVCA users.  
+$ ! May be removed after MAVCA.OHIO.GOV goes away. 
+$ ! 
+$ pmdf crdb /long/nofast/nodup/strip OECN$UMP:MAVCA_ALIASES.DAT oecn$ump:aliases.dat 
+$ 
+$!+ 
+$! Create directory daemon text file. 
+$!- 
+$ @OECN$:EXPORT_DD 
+$!+ 
+$! Build new directory daemon database.  Build into a temp file in case 
+$! someone attempts to use database while in progress. 
+$!- 
+$ pmdf crdb/duplicate/stat oecn$ump:directory_daemon.txt - 
+   oecn$ump:directory_daemon.tmp 
+$ copy oecn$ump:directory_daemon.tmp - 
+     pmdf_root:[directories]PO$NWOCA$ORG.DAT 
+$ set prot=w:re pmdf_root:[directories]PO$NWOCA$ORG.DAT 
+$ purge pmdf_root:[directories]PO$NWOCA$ORG.DAT 
+$ delete/nolog oecn$ump:directory_daemon.tmp;* 
+$! 
+$! Build distribution list based on VMS identifiers 
+$! 
+$ ID2DIS := $OECN$:UMPID2DIS 
+$ 
+$ ID2DIS OECN_USPS,OECN_SYSMAN  NWOCA_USPS NM_USPS.DIS 
+$ ID2DIS OECN_PPS,OECN_SYSMAN    NWOCA_PPS NM_PPS.DIS 
+$ ID2DIS OECN_USAS,OECN_SYSMAN    NWOCA_USAS NM_USAS.DIS 
+$ ID2DIS OECN_EMIS,OECN_EMIS_STU,OECN_EMIS_STF,OECN_EMIS_SFU,OECN_EMIS_GEN,OECN_EMIS_FIN,OECN_SYSMAN NWOCA_EMIS NM_EMIS_USERS.DIS 
+$ ID2DIS OECN_EIS,OECN_SYSMAN  NWOCA_EIS NM_EIS.DIS 
+$ ID2DIS OECN_VIS,OECN_SYSMAN  NWOCA_VIS NM_VIS.DIS 
+$ ID2DIS OECN_SECIMS,OECN_SYSMAN NWOCA_SECIMS NM_SECIMS.DIS 
+$ ID2DIS NWOCA_INFOHIO NWOCA_INFOHIO NM_INFOHIO.DIS 
+$ COPY OECN$UMP:nm_*.dis/sinc NM:/PROT=W:R 
+$ 
+$! Create aliases for NWOCA's identifier lists 
+$ PMDF DB 
+open oecn$ump:aliases.dat 
+override on 
+add "mail_hs_counselors" "mail_counselor_sec" 
+ 
+add "nwoca_usps" "nwoca_usps-list@reprocess.nwoca.org" 
+add "nwoca_usps-list" "<oecn$ump:nwoca_usps.dis,*,*,postmaster,*, USPS" 
+ 
+add "nwoca_PPS" "nwoca_PPS-list@reprocess.nwoca.org" 
+add "nwoca_PPS-list" "<oecn$ump:nwoca_PPS.dis,*,*,postmaster,*, PPS" 
+ 
+add "nwoca_USAS" "nwoca_USAS-list@reprocess.nwoca.org" 
+add "nwoca_USAS-list" "<oecn$ump:nwoca_USAS.dis,*,*,postmaster,*, USAS" 
+ 
+add "nwoca_EMIS" "nwoca_EMIS-list@reprocess.nwoca.org" 
+add "nwoca_EMIS-list" "<oecn$ump:nwoca_EMIS.dis,*,*,postmaster,*, EMIS" 
+ 
+add "nwoca_EIS" "nwoca_EIS-list@reprocess.nwoca.org" 
+add "nwoca_EIS-list" "<oecn$ump:nwoca_EIS.dis,*,*,postmaster,*, EIS" 
+ 
+add "nwoca_VIS" "nwoca_VIS-list@reprocess.nwoca.org" 
+add "nwoca_VIS-list" "<oecn$ump:nwoca_VIS.dis,*,*,postmaster,*, VIS" 
+ 
+add "nwoca_SECIMS" "nwoca_SECIMS-list@reprocess.nwoca.org" 
+add "nwoca_SECIMS-list" "<oecn$ump:nwoca_SECIMS.dis,*,*,postmaster,*, SECIMS" 
+ 
+add "nwoca_INFOHIO" "nwoca_INFOHIO-list@reprocess.nwoca.org" 
+add "nwoca_INFOHIO-list" "<oecn$ump:nwoca_INFOHIO.dis,*,*,postmaster,*, INFOhio" 
+$ 
+$!+ 
+$! Create VMS Mail forwarding addresses for same aliases 
+$!- 
+$ mail := mail 
+$ mail 
+set forward/user=nwoca_usps in%nwoca_usps 
+set forward/user=nwoca_pps in%nwoca_pps 
+set forward/user=nwoca_usas in%nwoca_usas 
+set forward/user=nwoca_emis in%nwoca_emis 
+set forward/user=nwoca_eis in%nwoca_eis 
+set forward/user=nwoca_vis in%nwoca_vis 
+set forward/user=nwoca_secims in%nwoca_secims 
+set forward/user=nwoca_infohio in%nwoca_infohio 
+$ 
+$ 
+$!+ 
+$! Create a MAIL_ALL distribution list.  Will contain all user profiles 
+$! which are subscribed to one or more distribution list (non-duplicated 
+$! addresses). 
+$!- 
+$ delete /nolog/noconfirm mail_all.*;* 
+$ append mail_*.dis/sinc mail_all.tmp/new 
+$ sort/nodupli mail_all.tmp mail_all.dis 
+$ set prot=w:r mail_all.dis;* 
+$ 
+$ PMDF DB 
+open oecn$ump:aliases.dat 
+override on 
+add "mail_all" "mail_all-list@reprocess.nwoca.org" 
+add "mail_all-list" "<oecn$ump:mail_all.dis,*,*,postmaster,*, All NWOCA users" 
+$ mail := mail 
+$ mail 
+set forward/user=mail_all in%mail_all 
+$ 
+$ purge oecn$ump:*.* 
+$ 
+$!+ 
+$! All local aliases have been added to databases.  
+$! Place the new databases back into PMDF production 
+$! directory. 
+$!- 
+$ copy/nolog oecn$ump:aliases.dat PMDF_ALIAS_DATABASE 
+$ set file pmdf_alias_database/prot=w:re 
+$ purge/keep=3/nolog pmdf_alias_database 
+$ 
+$ copy/nolog oecn$ump:reverse.dat PMDF_REVERSE_DATABASE 
+$ set file pmdf_reverse_database/prot=w:re 
+$ purge/keep=3/nolog pmdf_reverse_database 
+$ 
+$!+ 
+$! All done.  Restart dispatcher to ensure services open 
+$! the fresh databases. 
+$ PMDF RESTART DISPATCHER 
+$ START/QUEUE MAIL$BATCH 
+$  
+$ EXIT 
+ 
+ 
+
+
+ +

+ +

12.19 Multiple Non-Clustered Systems

+ DAS's with a single VMS system, or a single VMS cluster, need not be + concerned with this section. + +

+ The UMP system is currently designed assuming that each A-site will + have a single set of UMP files regardless of how many independent + (non-VMSclustered) systems. This provides a single point of + adminstration for DAS personnel and makes building the PMDF + distribution lists and aliases easier. At present, there are no plans + to implement multiple UMP files on multiple systems while still being + able to produce a single set of distribution lists for the entire DAS. + This may be added in the future if a well defined need arises. + +

+ However, it would be useful if remote users could modify their own user + profiles without having to log into the system which contains the UMP + files. This section describes a secure way of providing remote users + access to their own UMP profiles. + +

+ Use the following procedure to establish remote access to the UMP + system. + +

    +
  1. Choose a system to contain the UMP files. This would normally be + your cluster or the system primarily responsible for mail delivery. + This will be called the "server" system. +
  2. Put UMP on the server normally as described in the "Setup" section. + Users on this system will use the UMP program directly from this system. +
  3. Create a username on the server called UMP_SERVER. This should be + non-prived, network-only access. The login directory for this account + can be the OECN$UMP directory, or it can have a separate login + directory. +
  4. On the server define the OECN$UMP logical as normal. +
  5. On the server use AUTHORIZE to define network proxies into the + server for each remote system. For example: +
    +UAF> ADD/PROXY node::* UMP_SERVER
    Where "node" is the DECnet +node name of the remote node.
    This will give any user on one of +your non-server nodes proxy access to the UMP_SERVER. +
  6. On each node (client) that you want to have access to the server, + define OECN$UMP as follows (assuming MAIN:: is the server): +
    +$ DEFINE OECN$UMP "MAIN""UMP_SERVER""::OECN$UMP:"
    Also, copy the +UMP.EXE file to the OECN$: directory on the client node. Set up the +users to run the local copy of the .EXE. +
  7. Copy the *.INI files from the server to the client system. and + define the following logicals: +
    +$ DEFINE OECN$UMP_STANDARD dev:[dir]OECN$UMP_STANDARD.INI +
    +$ DEFINE OECN$UMP_LOCAL dev:[dir]OECN$UMP_LOCAL.INI
    Modify the +OECN$UMP_LOCAL.INI file to contain the local system's DECnet node name +and internet host. This will ensure that each user's profile is built +using the local system's node names. +
+ +

+ If you do the above, each node will appear to have local access to the + UMP files, and you will end up with a central DAS-wide database to + build your distribution lists from. The server node will be the only + one that needs to run the EXPORT_LISTS.COM to produce the mail_ and + oecn_ for your DAS. + +

12.20 Programming Considerations

+ +

+ DAS programmers may wish to use DTR, COBOL or other high level language + to query or manipulate the UMP data files. This section contains a + brief description of the UMP data files and special considerations. DTR + and COBOL definitions are provided with the software release for this + purpose. The COBOL definitions are contained in UMPDAT.LIB and + UMDDAT.LIB in OECN$LIB. The DTR definitions are in the domains + OECN$CDD_OECN.UMP_HEADER and OECN$CDD_OECN.UMP_DIST. OECN$CDD_UMP.UMPS + is a view which joins the header and distribution list code. + +

+ The UMP data is stored in two files in OECN$UMP: + + + + + + + + + + +
+ UMPDAT.IDX + + Contains profile information. Keys: +
    +
  • Primary: Group + Username +
  • Secondary: Username (no duplicates) +
  • Secondary: Alias (no duplicates) +
+
+ UMDDAT.IDX + + Contains the distribution lists the user is subscribed to. Each record + represents a single distribution list assignment. The distribution + lists are stored as a code value defined by the OECN$UMP_STANDARD.INI + or OECN$UMP_LOCAL.INI files. Primary key: Username + + Distribution_list_code +
+ +

12.20.1 Field Requirements

+ +

+Some fields in UMP may display to the user differently than is +physically stored in the file. Other fields have specific requirements. +Please note the following: + +

+ +

+ +

+

Chapter 13
VFC2PDF - Converting Text Files to PDF Format

 + +

+VFC2PDF converts VFC or plain text files into PDF (Portable Document +Format) files. After a report is converted to PDF format, it can be +transferred to a PC or a MAC. It can also be viewed or printed using +the Adobe Acrobat viewer. By using this utility, it becomes much easier +to publish documents on public Internet web sites, CDrom, etc. +

accessing the program

+
+
+
+ +

+The program may be executed by typing: + +

+ + +
+
+
+Menu>VFC2PDF
+ 
+
+
+ +

+at the Menu or from the $ prompt by typing: + +

+ + +
+
+
+$ VFC2PDF/[qual 1]/.../[qual n]  {input_file}  [output_file]) 
+ 
+
+
+ +

+ +

+By executing from the Menu, you have no control over the default +formatting options. + +

+By executing from the $ prompt, you can control the output, including +the use of wildcards. By default, VFC2PDF will attempt to choose +appropriate orientation, font sizes and margins based on the record +length of the input file. However, these values may be controlled by +using qualifiers as given below. + +

+

+ + + + +
Note
+ A foreign command must be defined for VFC2PDF, such as: +
+ ($ VFC2PDF :== $OECN$:VFC2PDF).
+
+

+Syntax +
+ +

+ + +
+
+
+ 
+ 
+   VFC2PDF {input_file} [output_file] 
+   
+        /ORIENTATION={PORTAIT|LANDSCAPE} 
+        /FONT_SIZE={points} 
+        /FONT_STYLE=([NORMAL],[BOLD],[ITALIC]) 
+        /VERTICAL_SPACING={points} 
+        /TOP_MARGIN={points} 
+        /LEFT_MARGIN={points} 
+        /LOG 
+        /PAGE_LENGTH={max_lines_per_page} 
+        /LINE_WIDTH={characters_per_line} (defaults to record size) 
+        /INFORMATION=([AUTHOR="author"], 
+                      [CREATOR="creator (defaults to username)"], 
+                      [TITLE="title (defaults to filename)"], 
+                      [SUBJECT="subject"]) 
+        /[NO]COMPRESS 
+ 
+ 
+
+
+ +

+Defaults +
+ +

+ + +
+
+
+ 
+ 
+    PORTRAIT:  /FONT_SIZE=11 /VERTICAL_SPACING=11 /LEFT_MARGIN=45 
+               /PAGE_LENGTH=66 
+    LANDSCAPE: /FONT_SIZE=9 /VERTICAL_SPACING=9 /LEFT_MARGIN=30 
+               /PAGE_LENGTH=66 
+      If /LINE_WIDTH is greater than 132: 
+               /FONT_SIZE=7 /VERTICAL_SPACING=9 /LEFT_MARGIN=30 
+ 
+ 
+
+
+ +

+Notes +
+ +

+ + +
+
+
+ 
+ 
+   - Wildcards are supported in the input specification. If wildcards 
+     are used, the output_file may be omitted or must not include a file 
+     name. Output files will be written to the default directory unless 
+     the second parameter contains an output directory. 
+ 
+   - All qualifiers are optional.  If /ORIENTATION is omitted, then 
+     it will be selected automatically based on the record length of the 
+     input file.  Line lengths over 80 characters will be printed in LANDSCAPE, 
+     otherwise PORTRAIT will be used. 
+ 
+       Note: Record size determination is based on the MRS (Maximum Record 
+             Size) in the RMS header.  For formats where MRS is not set, 
+             VFC2PDF will assume 80 characters. 
+ 
+ 
+
+
+ +

transfer options

+
+
+ +

+There are several methods available to transfer the PDF formated file +to a PC or MAC. + +

+One method is to use some FTP utility. + +

+Another procedure, which seems to work well in Netscape, is to specify +an FTP URL as: + +

+ + +
+
+
+ 
+  ftp://username@host.org/ 
+ 
+ 
+
+
+ +

+Netscape will prompt you for a password and connect with an +authenticated FTP. + +

+A second simple method is to mail the file(s) to yourself as follows: + +

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

+or for multiple PDF files: + +

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

+For the above, "noedit" means No Edit feature, and "nocc" means No +Carbon Copy desired. + +

+Once the files are sent, the user can open the message with their +browser, or WEB-Mail, or some other client, and then save it to their +desktop or print from there. +

+

+ + + + +
Contents
+ +