.LAYOUT 1,2 .NO NUMBER .SET PARAGRAPH 0,1,2 .AUTOPARAGRAPH .NO AUTOJUSTIFY .NO JUSTIFY .FILL .LEFT MARGIN 2.RIGHT MARGIN 76 .FLAGS BOLD.FLAGS BREAK.FLAGS CAPITALIZE .FLAGS HYPHENATE.FLAGS INDEX.FLAGS PERIOD .FLAGS LOWERCASE.FLAGS SPACE .XLOWER .STYLE HEADERS 5,0,6,0,7,3,1,9,2 .NO HEADERS .PAGE .FIGURE 8 .CENTER;^*SETUP.MAR V4.0\* .CENTER;^*VMS V5.1-1\* .BLANK 5 .CENTER;^*User Guide\* .CENTER;^*and\* .CENTER;^*Reference Manual\* .BLANK 17 .CENTER;David G. North .CENTER;International Telecharge, Inc. .CENTER;9999 W. Technology Blvd. .CENTER;Dallas, Texas 75202 .BLANK .CENTER;November 20,1990 .NUMBER PAGE 1 .NO NUMBER .PAGE .DISPLAY NUMBER RL .NUMBER LEVEL 0 .IFNOT FINAL .DISABLE TOC .HEADER LEVEL 1 ^*^&Contents\&\* .ENABLE TOC .SEND TOC .CENTER;^*^&Table \of Contents\&\* .SEND TOC .FIGURE 3 .HEADER LEVEL 2 ^*^&Table \of Contents\&\* .ENDIF FINAL .require "setup.rnt" .NUMBER PAGE .PAGE .HEADER LEVEL 2 ^*^&Introduction\&\* VAX/VMS provides a user with the capability of setting up a LOGIN.COM procedure in order to perform a standard, but individualized initialization task at each login. For some of us, this LOGIN.COM procedure can become extremely large. Since LOGIN.COM must be executed by the DCL command line interpreter, the phrase 'extremely large' translates equally well as 'extremely slow'. The SETUP program described here was initially designed to address the speed issue associated with a large LOGIN.COM. Since then, it has evolved to become a very effective tool for the management of multiple environments, and for providing a stable and consistent environment basis. This program is provided on an as-is basis. Any part of this routine may be freely copied and distributed so long as two conditions are met: .LITERAL * Use is non-commercial only (all other uses require prior written permission of the author(s)). * This document and all identification messages are retained in the source files. .END LITERAL There are no guarantees as to the usefulness or functionality of this program under any conditions. I have, however, done my best to make this program as generic as possible (within the limitations of some of it's functions), and I consider it to be generally bug-free (I currently run it on at least 10 machines with no known problems). Special thanks go to Hunter Goatley of Clyde Digital Systems in Orem Utah for providing the DCL key definition routines used herein. The original article, which is excellent, may be found in the February 1988 issue of the VAX Professional magazine, and is recommended reading for anyone interested in how these routines work. The routines used here are rough copies of a subset of the routines published in the original article and are included here by permission of the original author. .HEADER LEVEL 2 ^*^&Format \of \this Manual\&\* This manual is divided into two parts. Part I contains an overview of the program and describes how to use the customization section of SETUP.MAR to change (for example) such things as the symbols or logicals one may wish to define. Part II describes the more technical details of how the program and its macros function and the various well-defined interface methods that may used to augment the functionality of SETUP.MAR in a consistent and (hopefully) maintainable fashion. .PAGE .LEFT MARGIN 2.RIGHT MARGIN 76 .SEND TOC .FIGURE 3 .SEND TOC .CENTER;^*^&PART I\&\* .STYLE HEADERS 5,0,6,7,7,3,1,9,2 .FIGURE 8 .CENTER;^*SETUP.MAR V4.0\* .CENTER;^*VMS V5.1-1\* .BLANK 5 .CENTER;^*^&PART I\&\* .BLANK 19 .CENTER;David G. North .CENTER;International Telecharge, Inc. .CENTER;108 South Akard, AT-5 .CENTER;Dallas, Texas 75202 .BLANK .CENTER;November 20,1990 .DISPLAY NUMBER D .NO NUMBER .CHAPTER ^*^&O\v\e\r\v\i\e\w\&\* .LEFT MARGIN 2.RIGHT MARGIN 76 .NUMBER PAGE This chapter contains an overview of SETUP.MAR. .!LEFT MARGIN -4 .HEADER LEVEL 1 Program Distribution \and Build Instructions .LEFT MARGIN +4 The first item on the agenda should probably be a discussion of the program distribution, and how to build a working program. Contents of the distribution are: 1) SETUP.MAR - the main program, 2) SETUPMSG.MSG - messages used by SETUP, 3) SETUPMLB.MAR - the macro library used by SETUP. Steps to build the program are: 1) Build macro library, 2) Assemble SETUP, 3) Build message object file, and 4) Link program. The following DCL will perform this task provided all files reside in the default directory: .LITERAL $ LIBRARY/MACRO/CREATE SETUPMLB SETUPMLB $ MACRO SETUP $ MESSAGE SETUPMSG $ LINK SETUP,SETUPMSG/CONTIG/NOTRACE .END LITERAL .LEFT MARGIN -4 .HEADER LEVEL 1 Basic Functions Description .LEFT MARGIN +4 SETUP.MAR provides sixteen basic functions. Most of these functions will be performed for all login types, although some functions are restricted to interactive mode only, some batch, and some have individual lists for each mode. Valid modes are: 1) Batch, 2) Interactive, 3) Network, 4) Other, and 5) Failure (to identify mode). Each function is described by some kind of list structure implemented by macro calls. Use of these macros and several key routines within the program provide the foundation for making this program easy to modify and use, and for providing node-specific operations. SETUP.MAR provides the following basic functions: .TEST PAGE 14 .BREAK ##^&Description\&##############################^&DCL Example\& .LITERAL * symbols to delete $ DEL/SYM/GLO symbol * symbols to define $ symbol=="Text" * logicals to define $ DEF/NOLOG/TAB=LNM$JOB l1 l2 * keys to define $ DEF/KEY/TERM/NOECH F17 CLS * default process names $ SET PROCESS/NAME * default protection $ SET PROT=(s,o:rwed,g,w)/DEF * default message bits $ SET MESS/NOFAC/NOIDE/NOSEV * default privileges $ SET PROC/PRIV=ALL * default directory $ SET DEF SYS$LOGIN * default terminal broadcast classes $ SET BRO=NOUSER16 * Terminal characteristics to disable $ SET TE/NOBROADCAST * Terminal characteristics to enable $ SET TE/PASSTHRU * Operator console classes to enable $ REPLY/ENABLE=SECURITY * Set DCL prompt $ SET PROMPT="$ " * Set DCL verify state $ SET VERIFY * Execute a DCL command on exit .END LITERAL Alteration of the contents of the above lists should be a fairly easy if the user will simply alter the examples given in the source file, however, the following sections will detail each list and how to modify its contents in the case where the user encounters problems, or wishes further clarification. .LEFT MARGIN -4 .HEADER LEVEL 1 Modification Prerequisites .LEFT MARGIN +4 There are two items which it would be helpful to understand before attempting any major modifications of the source code. First, one needs to understand the concepts I have termed 'classes' and 'collections' in order to implement node-specific operations, and second, one should be aware of the list definition macros and how they function. What follows is an overview only; please refer to the documentation on the specific lists and macros for more detailed information. .LEFT MARGIN -4 .HEADER LEVEL 2 Classes, Collections, \and Nodes .LEFT MARGIN +4 For purposes of clarification, a class is an artificial construct of which a node may be a member, and which a particular operation may require in order to be executed. Thus, only nodes which are members of the class TEST1 will execute the functions that are limited to members of class TEST1. Since classes are usually used in sets (i.e. one node usually is a member of more than one class), manipulation of individual classes can become fairly clumsy. Therefore, classes must be grouped into collections before use. A collection is, then, a set of classes. There are a maximum of 32 classes, and an arbitrary number of collections and nodes. Each class name definition creates an identically named collection so that unless you need collections consisting of multiple classes, the existence of collections is tranparent. Such a scheme may be used, for example, to allow privileged operations on one set of nodes (i.e. those nodes which are members of a class allowing those operations) and not on others, and/or it may be used to perform logical name definitions on any node holding a class pertaining to the cluster of which that node is a member. There are three macros used to define classes, collections, and nodes: DEFINE__CLASS, DEFINE__COLLECTION, and DEFINE__NODE. These macros interact with the '.ITM' and '.ITMVAL' macros described below to provide node-specific operations. For example, if there exist three nodes, DEVL, TEST, and ISOL, where DEVL and TEST are part of the STAR1 cluster, you may wish to define a class STAR1 which may be used to identify operations to be performed only on nodes that are members of STAR1, and a class PRIV to allow privileged operations only on ISOL and TEST as follows: .TEST PAGE 7 .LITERAL DEFINE_CLASS STAR1 ; Define class for cluster STAR1 DEFINE_CLASS CME ; Allow executive mode operations DEFINE_CLASS CMK ; Allow kernel mode operations DEFINE_COLLECTION PRIV,CME,CMK ; Allow all mode operations DEFINE_NODE DEVL,STAR1 ; Node DEVL, member of STAR1 DEFINE_NODE TEST,STAR1,PRIV ; Node TEST, member of STAR1 DEFINE_NODE ISOL,PRIV ; Node ISOL, *not* member of STAR1 .END LITERAL .LEFT MARGIN -4 .HEADER LEVEL 2 List Structures .LEFT MARGIN +4 There are three macros that define the list structures. The usage of these macros may vary or even be omitted from list to list, so it is important to pay close attention to the original list structures. The macros are '.ITM', '.ITMVAL', and '.EOLIST'. There are three basic structures that will be created using these macros: 1) List of 'valueless' items, 2) List of items with one or more values, 3) List of type 2 lists. Please note these list types since they are referred to later in the description of the customization section. Examples of each of these follow: .TEST PAGE 4 .LITERAL 1) List of 'valueless' items: (Type 1) .ITM ;one symbol, no value given .ITM ,COLL=STAR1 ;one symbol, no val, coll STAR1 .EOLIST ;end of list .END LITERAL .BLANK .TEST PAGE 5 .LITERAL 2) List of items with one or more values (type 2) .ITMVAL , ;symbol, with value .ITMVAL ,<$$:YACC>,- ;symbol, with value, COLL=STAR1 ; only for members of STAR1 .EOLIST ;end of list .END LITERAL .BLANK .TEST PAGE 10 .LITERAL 3) List of type 2 lists (type 3) .ITM ;Table LNM$JOB (begins list 1) .ITMVAL , ;Logical, single value .ITMVAL ,, ;Logical, 2 value search list .EOLIST ;End of list 1 (LNM$JOB) .ITM ;New table (begins list 2) .ITMVAL , ;Logical, single value .ITMVAL , ;Logical, single value .EOLIST ;End of list 2 (LNM$PROCESS) .EOLIST ;End of list of tables .END LITERAL .CHAPTER ^*^&G\u\i\d\e \t\o SETUP.MAR M\a\c\r\o\s\&\* .LEFT MARGIN 2.RIGHT MARGIN 76 .NUMBER PAGE This chapter contains a list of the macros provided by SETUP.MAR (contained in SETUPMLB.MAR) for use in the customization section. Macros are arranged alphabetically after omitting any leading characters such as '__' or '_.'. Items within square brackets ('_[','_]') indicate optional parameters and are not to be considered syntactically operational. .!LEFT MARGIN -4 .HEADER LEVEL 1 _.COLL .LEFT MARGIN +4 This macro provides a technique for allocating a longword of storage and equating it to the bitmask representing the specified collection's value. Subsequent operations will test that longword to see what classes are required to perform the operation. Depending on the specific operation, all classes in the collection may be required, or any class in the collection may be required. Refer to documentation on a specific operation to find out which type of test is used. .TEST PAGE 7 .LITERAL Usage: DEFINE_CLASS TEST1 ;Symbolic DEFINE_CLASS TEST2 ;Symbolic DEFINE_COLLECTION ALL_TESTS,TEST1,TEST2 ;Symbolic label: .COLL ALL_TESTS ;Longword of storage .END LITERAL .LEFT MARGIN -4 .HEADER LEVEL 1 DEFINE__CLASS .LEFT MARGIN +4 This macro provides an easy way to define a class by some arbitrary symbolic name. Classes are internally represented as a bitmask 32 bits in size with one unique bit set. Therefore, the maximum number of classes you may define is 32. This macro also automatically defines a collection of the same name as the class being defined alleviating the need to do a DEFINE__COLLECTION prior to using macros requiring a collection as input. Refer to documentation on DEFINE__COLLECTION for a possible side-effect of the automatic collection definition. .TEST PAGE 4 .LITERAL Usage: DEFINE_CLASS TEST1 .END LITERAL .LEFT MARGIN -4 .HEADER LEVEL 1 DEFINE__COLLECTION .LEFT MARGIN +4 This macro is used to define a symbolic collection of classes which is actually the binary OR of the individual classes comprising the collection. Excercise caution if you choose to use DEFINE__COLLECTION to define a collection name that has been previously defined (probably using DEFINE__CLASS). In such cases the specified classes will be OR'ed into the existing collection producing a collection which may not be exactly what was desired. .TEST PAGE 6 .LITERAL Usage: DEFINE_CLASS TEST1 DEFINE_CLASS TEST2 DEFINE_COLLECTION ALL_TESTS,TEST1,TEST2 [,...] .END LITERAL .LEFT MARGIN -4 .HEADER LEVEL 1 DEFINE__NODE .LEFT MARGIN +4 This macro will insert the specified nodename into a global storage list of all such names, and combine all classes_/collections of which it is a member into the class mask to be associated with that node. During execution of SETUP.MAR, the current nodename is acquired from VMS and the global list is searched for that nodename. If the nodename is found, the class mask for that node is read and subsequent operations will test against the class mask specified by this macro during the original assembly. Nodes that are not found are given a class mask of 0 indicating membership in no classes. .TEST PAGE 8 .LITERAL Usage: DEFINE_CLASS TEST1 DEFINE_CLASS TEST2 DEFINE_CLASS OPER DEFINE_COLLECTION ALL_TESTS,TEST1,TEST2 DEFINE_NODE GEMINI,OPER,ALL_TESTS [,...] .END LITERAL .LEFT MARGIN -4 .HEADER LEVEL 1 _.EOLIST .LEFT MARGIN +4 This macro ends a list that began with a '_.ITMVAL' or a '_.ITM' macro. Requirements for where this macro must be used vary slightly depending on the specific list being terminated. Refer to the documentation for each specific list for further information. .TEST PAGE 4 .LITERAL Usage: .EOLIST .END LITERAL .LEFT MARGIN -4 .HEADER LEVEL 1 _.ITM .LEFT MARGIN +4 The '.ITM' macro is used to define a single entity. That entity may have a name, an option, and/or a collection. It may have only one of these depending on the usage, or it may even have all three, but it must have at least one of the three arguments. Refer to the documentation for each specific list for further information. .TEST PAGE 5 .LITERAL Usage: .ITM .ITM OPTION=label,COLL=ALL_NODES .END LITERAL .LEFT MARGIN -4 .HEADER LEVEL 1 _.ITMVAL .LEFT MARGIN +4 This macro is very similar to the preceeding '.ITM' with the additional capability to specify a list of values for the item being defined. Refer to the documentation for each specific list for further information. .LITERAL Usage: .ITMVAL ,, .ITMVAL ,,COLL=CMKRNL .END LITERAL .LEFT MARGIN -4 .HEADER LEVEL 1 __MSGBITDEF .LEFT MARGIN +4 This macro defines the bits used to set the default message flags. There may be a VMS macro to do this, but I was not able to locate one. The flags have the same values as those for controlling the output of the $PUTMSG system service. The defined values are of the form MSG__V__xx...xx or MSG__M__xx...xx where 'V' is a bit number, 'M' is a mask value, and 'xx...xx' is one of 'SEVERITY', 'TEXT', 'IDENT', or 'FACILITY'. .TEST PAGE 4 .LITERAL Usage: defmsg: .ITM OPTION=MSGBIT_M_TEXT,COLL=CMKRNL .END LITERAL .LEFT MARGIN -4 .HEADER LEVEL 1 __PRTDEF .LEFT MARGIN +4 This macro defines the bits used to set the default protection mask. There may be a VMS macro to do this, but I was not able to locate one. Refer to the documentation for SYS$SETDFPROT for information on how the protection argument is constructed. .TEST PAGE 7 .LITERAL Usage: defpro: .ITM OPTION=<!- !- !- > .END LITERAL .CHAPTER ^*^&G\u\i\d\e \t\o SETUP.MAR C\u\s\t\o\m\i\z\a\t\i\o\n\&\* .LEFT MARGIN 2.RIGHT MARGIN 76 .NUMBER PAGE This chapter contains the documentation on all items defined in the customization section of SETUP.MAR. It will discuss what exactly is provided as well as the formats and usage of each of the lists. Topics are arranged in the same order as the program and therefore are not in alphabetical order. Please refer to the table of contents to locate a specific item. .!LEFT MARGIN -4 .HEADER LEVEL 1 Code Generation Flags .LEFT MARGIN +4 The following section describes flags that may be enabled or disabled in the program to allow or prevent generation of certain functions. For example, if there are no machines on which you will execute kernel mode code, you may set a flag which will prevent that code not only from being executed, but even from being generated at all. .LEFT MARGIN -4 .HEADER LEVEL 2 DISABLE__BOOST .LEFT MARGIN +4 This program has code in it to set the process _/NOSWAP and boost the priority to twelve (12) for either the duration of the program, or five (5) seconds, whichever comes first. That way, if the program gets hung up for some reason (there are no known reasons that this may happen), it will not stay at a priority that will degrade system performance for an extended period of time. If you do not wish the program to do this, you may uncomment the DISABLE__BOOST flag definition. .LEFT MARGIN -4 .HEADER LEVEL 2 DISABLE__CMKRNL .LEFT MARGIN +4 This program can set the default message flags for the process. Unfortunately, they are protected URKW requiring that kernel code be used to change them. Use of any user-written kernel code on some machines may not be acceptable, or the user simply may not have CMKRNL privilege on any machines. In order to completely disable generation of kernel mode code, you may uncomment the DISABLE__CMKRNL flag definition. .LEFT MARGIN -4 .HEADER LEVEL 2 DISABLE__CMEXEC .LEFT MARGIN +4 This flag is identical to the DISABLE__CMKRNL flag, but disables generation of any executive mode code. This means that DCL keys may not be defined. In order to completely disable generation of executive mode code, you may uncomment the DISABLE__CMEXEC flag definition. .LEFT MARGIN -4 .HEADER LEVEL 2 DISABLE__CMSUPER .LEFT MARGIN +4 This flag is identical to the DISABLE__CMKRNL flag, but disables generation of any supervisor mode code. This means that the DCL prompt may not be defined, and the DCL verify state may not be set. In order to completely disable generation of supervisor mode code, you may uncomment the DISABLE__CMSUPER flag definition. .LEFT MARGIN -4 .HEADER LEVEL 1 Class, Collection, and Node Definitions .LEFT MARGIN +4 This portion of the SETUP program is provided only as an example. You must tailor this section to your usage requirements. The macros used have been described in an earlier section of this document. .LEFT MARGIN -4 .HEADER LEVEL 1 List Definitions .LEFT MARGIN +4 The following sections describe the format and usage of the various lists. The SETUP.MAR program is considered to be the examples for these sections and therefore, no examples will be included in the documentation of these lists. Note that activation of an item in a list is dependent on the 'test type' of the particular list. (Exceptions to this 'rule' are the few cases where the entire list has a special key using the .COLL to exclude list processing for non-members of that collection). There are 2 categories of nodes recognized: 1) node is known, and has class membership, 2) node is known, but has no class memberships, or node is unknown (and assumed member of no classes). There are 2 types of item definitions for those lists supporting the 'COLL_=' option: a) collection absent, and b) collection present. This leads to a total of four combinations (1a,1b,2a,2b). There are four different test types that act differently and require different levels of matching for each of the four possible combinations. The reaction matrix for the 4 combinations mapped against the four possible list test types is as follows (the descriptions following will refer to the relevant test types by these names): .TEST PAGE 10 .LITERAL Node/Item comb. | Test type --------------------|-------------------------------------- # Class Item_Coll | Default Members Inhibit Protected -- ----- --------- | ------- ------- ------- --------- 1a yes no | execute execute ignore ignore 1b yes yes | execute execute execute execute 2a no no | execute ignore execute ignore 2b no yes | ignore ignore ignore ignore .END LITERAL .LEFT MARGIN -4 .HEADER LEVEL 2 Automatic Symbol Deletion .LEFT MARGIN +4 This list may be found after the label 'hitlst:'. Structure is that of a type 1 list described above. Test type is default. No errors will occur, even if the symbol is not present. .LEFT MARGIN -4 .HEADER LEVEL 2 Symbol Definition .LEFT MARGIN +4 This list may be found after the label 'symlst:'. Structure is that of a type 2 list described above with the restriction that the number of values assigned to each symbol must be exactly one (1). Test type is default. No errors will occur, even if the symbol is redefined. As in DCL, a '_*' may be used to indicate an abbreviated symbol. .LEFT MARGIN -4 .HEADER LEVEL 2 Logical Name Definition .LEFT MARGIN +4 This list may be found after the label 'loglst:'. Structure is that of a type 3 list described above, i.e. it is a list of '.ITM'...'.EOLIST' where each '.ITM' has an intervening '.ITMVAL'...'.EOLIST'. The '.ITM' macro describes the name of a logical name table (such as LNM$JOB) into which the following '.ITMVAL' logical names will be inserted. Test type is default. Unexpected errors will terminate the program (such as logical name table full). Logical names containing multiple values will be defined as search-listed logical names. The 'OPTION' argument of each '.ITMVAL' macro is used to assign logical name attributes such as LNM$M__CONCEALED. Make special note of the equivalence string '_*'. This equivalence string is a keyword requesting a rooted-logical specification for SYS_$LOGIN:; usually used with OPTION_=LNM_$M__CONCEALED. .LEFT MARGIN -4 .HEADER LEVEL 2 DCL Key Definitions .LEFT MARGIN +4 This list may be found after the labels 'keycls:' and 'keylst:'. Label 'keycls:' defines a collection which is tested for inclusive membership (that is to say only nodes possessing membership in all classes in the specified collection will be allowed to execute the key definitions). Structure is that of a type 3 list described above, i.e. it is a list of '.ITM'...'.EOLIST' where each '.ITM' has an intervening '.ITMVAL'...'.EOLIST'. The '.ITM' macro describes the name of a keypad state (such as DEFAULT) for which the following '.ITMVAL' keys will be defined. Test type is default. Unexpected errors will terminate the program. If you specify two values to be assigned to the key, the second value is interpreted to be a state name to set. In such a case, you will need to specify the SYM__M__STATE flag and possibly the SYM__M__LOCK flag as well. More than 2 values in a key's value list will terminate the program with an error. The 'OPTION' argument of each '.ITMVAL' macro is used to assign symbol definition flags such as SYM__M__ERASE. Valid options for the flags are SYM__M__ECHO (causes the equivalence string to be echoed), SYM__M__ERASE (erase command line first), SYM__M__LOCK (lock keypad in specified state), SYM__M__STATE (set_state value is present), and SYM__M__TERMINATE (add a carriage return). At the risk of sounding repetitious, special thanks go to Hunter Goatley of Clyde Digital Systems in Orem Utah for providing the DCL key definition routines used herein. The original article, which is excellent, may be found in the February 1988 issue of the VAX Professional magazine, and is recommended reading for anyone interested in how these routines work. The routines used here are rough copies of a subset of the routines published in the original article and are included here by permission of the original author. .LEFT MARGIN -4 .HEADER LEVEL 2 Default Process Names .LEFT MARGIN +4 This list may be found after the label 'prclst:'. Structure is that of a type 1 list described above. Test type is inhibit. Usage of this list is a little unusual though. It is a list of single .ITM's with no values, just OPTION_= statements whose values are the addresses of other type 1 lists of single-value process names. This allows multiple processname lists dependent on 'COLL_=' criteria. Note that even though the processname lists conform to type 1 list format, there is a requirement of 8 items in the list. The trailing '.EOLIST', or any items specified after the eighth entry are ignored. .LEFT MARGIN -4 .HEADER LEVEL 2 Default Protection .LEFT MARGIN +4 This list may be found after the label 'defpro:'. Structure is that of a type 1 list described above. Test type is inhibit. Specify the default protection in the OPTION_= using the PRT__xx macros. .LEFT MARGIN -4 .HEADER LEVEL 2 Default Message Flags .LEFT MARGIN +4 This list may be found after the labels 'msfcls:' and 'defmsg:'. Label 'msfcls:' defines a collection which is tested for inclusive membership (that is to say only nodes possessing membership in all classes in the specified collection will be allowed to execute the message flag setup). List is type 1, test type is inhibit. Flag values are specified using 'OPTION_=' and some logical or of MSGBIT__M__xxx masks. .LEFT MARGIN -4 .HEADER LEVEL 2 Default Privileges .LEFT MARGIN +4 These lists are mode-sensitive, and occur following the labels 'batprv:' (batch), 'othprv:' (other mode), 'intprv:' (interactive), 'falprv:' (mode id failure), and 'netprv:' (network). The lists are type 1, test type is inhibit. Use the 'OPTION_=' to specify the address of a VMS privilege quadword. .LEFT MARGIN -4 .HEADER LEVEL 2 Default Drives _& Directories .LEFT MARGIN +4 These lists are mode-sensitive, named similarly to the previous lists, and occur following the following labels: 'faldir:', 'batdir:', 'othdir:', 'intdir:', and 'netdir:'. For each 'xxxdir:', there is a corresponding 'xxxdrv:'. Since the 'SET DEFAULT' operation is a two-step operation (i.e. default directory, _*and_* drive), each has its own list. Both lists are type 1, and test type inhibit. Use the 'OPTION_=' to specify the address of the appropriate .ascid text. .LEFT MARGIN -4 .HEADER LEVEL 2 Broadcast Classes .LEFT MARGIN +4 This list appears at symbol 'ttbro:', is type 1, and test type inhibit. Use the 'OPTION_=' to specify the address of a IO$__SETMODE,IO$M__BRDCST $QIO quadword. (Refer to I/O User's guide for more info). Use BRK$C__xxx codes to specify those broadcast classes you do not wish to receive. .LEFT MARGIN -4 .HEADER LEVEL 2 Terminal Characteristics .LEFT MARGIN +4 This list is in two pieces, first which characteristics to enable, and then those to disable. They are found at labels 'tton:', and 'ttoff:' respectively. Lists are type 1, test type is inhibit. Use 'OPTION_=' to specify the address of 12 bytes of terminal attributes corresponding to the SETMODE characteristics described under the parameters IO$__SENSEMODE in the terminal driver section of the I/O user's guide. .LEFT MARGIN -4 .HEADER LEVEL 2 Operator Console Enable .LEFT MARGIN +4 This list is found at 'opcmsk:', is type 1, and test type is protected. Use the 'OPTION_=' to specify the logical or of the OPC$M__NM__xxx classes you wish to enable. .LEFT MARGIN -4 .HEADER LEVEL 2 Set DCL prompt .LEFT MARGIN +4 This list is found at the label 'prmlst:'. It is type 1, test type protected. Use 'OPTION_=' to specify the address of a list of prompts, setups, and terminal selection characteristics. Format for the list whose address is specified in the 'OPTION_=' is as follows: .TEST PAGE 7 .LITERAL .address prompt_descriptor ;prompt to define .address setup_descriptor ;terminal setup string .long TT$_VT300_SERIES ;required terminal type .long 0 ;required TT$M_xxx characteristics .long TT2$M_REGIS ;required TT2$M_xxx characteristics .EOLIST .END LITERAL The first two addresses specify the prompt to set, and a terminal setup string if necessary (the terminal setup string is omitted by using .long 0). The third item is a required terminal type to activate the prompt. If it is specified as zero, then the terminal type is not checked. The fourth item is a bitmask of required bits from $TTDEF. If this is nonzero, then the terminal must have the requested characteristics in order to activate the prompt. The fifth item is same as fourth, but for $TT2DEF. This set of five items is repeated as many times as necessary, and terminated with .EOLIST. If a terminal match is found, the prompt is set, and the search is aborted. This means that you must set prompts in order of decreasing specificity. .LEFT MARGIN -4 .HEADER LEVEL 2 Set DCL verify state .LEFT MARGIN +4 This list is a type 1 list found at symbols 'batver:', 'netver:', 'intver:', 'falver:', and 'othver:'. Test type is protected. Use 'OPTION_=0' or 'OPTION_=1' on each .ITM to disable or enable (respectively) verify for that _.ITM. List naming is mode-dependent per prior examples. .LEFT MARGIN -4 .HEADER LEVEL 2 Execute final command on exit .LEFT MARGIN +4 This list is a type 1 list found at symbols 'batdo:', 'netdo:', 'intdo:', 'faldo:', and 'othdo:'. Test type is protected. Use 'OPTION_=' to specify the address of the command to execute (by descriptor). If the list contains a matching item per-current-mode, then the command described will be requested using LIB$DO__COMMAND as the last thing the program does before exiting. .PAGE .LEFT MARGIN 2.RIGHT MARGIN 76 .SEND TOC .FIGURE 3 .SEND TOC .CENTER;^*^&PART II\&\* .FIGURE 8 .CENTER;^*SETUP.MAR V4.0\* .CENTER;^*VMS V5.1-1\* .BLANK 5 .CENTER;^*^&PART II\&\* .BLANK 19 .CENTER;David G. North .CENTER;International Telecharge, Inc. .CENTER;108 South Akard, AT-5 .CENTER;Dallas, Texas 75202 .BLANK .CENTER;November 20,1990 .DISPLAY NUMBER D .NO NUMBER .CHAPTER ^*^&I\m\p\l\e\m\e\n\t\a\t\i\o\n \_& D\a\t\a S\t\r\u\c\t\u\r\e\s\&\* .LEFT MARGIN 2.RIGHT MARGIN 76 .NUMBER PAGE This chapter covers from a more detailed viewpoint the data structures that SETUP.MAR uses, and how SETUP.MAR is structured. These descriptions are provided to assist other programmers in consistently understanding and modifying SETUP.MAR. .!LEFT MARGIN -4 .HEADER LEVEL 1 General SETUP architecture .LEFT MARGIN +4 SETUP is broken into a number of functional sections best termed 1) user data section, 2) internal data section, 3) list driver routines, 4) class matching routines, 5) class execution routines, 6) main function subroutines, and 7) the main execution module. .LEFT MARGIN -4 .HEADER LEVEL 2 User data section .LEFT MARGIN +4 This section defines all user-selectable parameters. It is referenced from all levels of the code sections, and from the internal data section. .LEFT MARGIN -4 .HEADER LEVEL 2 Internal data section .LEFT MARGIN +4 This section contains all of the 'working-storage' for SETUP.MAR. It also contains a number of 'lists' which map parts of the user data section. It is referenced by all levels of the code sections. It also should not be tinkered with by a casual user. .LEFT MARGIN -4 .HEADER LEVEL 2 List driver routines .LEFT MARGIN +4 These routines will be discussed in a little more detail below. They are the 'traversal' routines to traverse a specific list type, and call first the class matching routine, and then, if the class matched ok, call the class execution routine. These routines are literally the 'heart' of SETUP's list processing. .LEFT MARGIN -4 .HEADER LEVEL 2 Class matching routines .LEFT MARGIN +4 These routines are called by the list processing routines to determine if the current node membership allows selection of the current item. These also will be discussed in a little more detail later. It is these routines that implement the 'test type' mentioned in the previous part; i.e. default, inhibit, member, or protected. .LEFT MARGIN -4 .HEADER LEVEL 2 Class execution routines .LEFT MARGIN +4 These routines are complementary routines to the main function subroutines and are responsible for initializing or executing list-specific functions after a match has been found. Some of these routines will actually execute code to perform the list's function, others will simply set up a pointer for use later after the traversal completes and returns to the main function subroutines. .LEFT MARGIN -4 .HEADER LEVEL 2 Main function subroutines .LEFT MARGIN +4 These routines provide the coarse granularity functions of the program; i.e. defining all logicals, deleting all requested symbols, etc. They call into the list driver routines passing list address, class match routine address, and class execution address. Some of these routines will simply setup and call the list driver routines allowing the class execution routine to do the main work, and others will use the class execution routine to select a parameter, then execute the 'real function' with the selected parameter. .LEFT MARGIN -4 .HEADER LEVEL 2 Main execution module .LEFT MARGIN +4 This is the traditional MAIN module. It calls all of the main function subroutines in order, then returns. Basically, the only instructions that should be found in this routine are 'JSB' or 'BSBW'. It is simply a dispatcher. .LEFT MARGIN -4 .HEADER LEVEL 1 List types .LEFT MARGIN +4 .HEADER LEVEL 2 Type 1 list This list type consists of a number of .ITM's followed by .EOLIST. .TEST PAGE 2 .LITERAL The .ITM arguments are: .ITM [][,OPTION=][,COLL=] .END LITERAL Each item has the following structure: .TEST PAGE 12 .LITERAL +--------+--------+ | -0- co| offset | - offset to next item, bits for coll/opt pres. +--------+--------+ | ^x010e | len | - Text descriptor (optional) +--------+--------+ / text / - Text + fill to word boundary +-----------------+ | collection mask | - Collection membership requirement mask +-----------------+ | option longword | - Contents of 'OPTION=' argument +-----------------+ .END LITERAL Note that any (but not all) of the items text, collection, or option may be omitted. They are simply omitted from the structure if they are not specified. This implies that routine using the list needs to 'know' if the string is present or not, and that all items in a list will either have, or not have the string present! _.EOLIST is simply a longword 0. .LEFT MARGIN -4 .HEADER LEVEL 2 Type 2 list .LEFT MARGIN +4 This list type consists of a number of .ITMVAL's followed by .EOLIST. Each item has the following structure: .TEST PAGE 2 .LITERAL The .ITMVAL arguments are: .ITMVAL [][,OPTION=][,COLL=],- [][,][...,] .END LITERAL Each item has the following structure: .TEST PAGE 7 .LITERAL +--------+--------+ | count | - count of values defined +--------+--------+ |.ITM text,OPT,COL| - .ITM description of item text, options & +--------+--------+ coll statments. |.ITM val1... | - Repeated .ITM's for each value +--------+--------+ .END LITERAL .LEFT MARGIN -4 .HEADER LEVEL 2 Type 3 list .LEFT MARGIN +4 Type 3 lists use a combination of the previous data structures. They consist if a series of .ITM's followed by .EOLIST just like a type 1 list, but after each .ITM, a type 2 list consisting of a number of .ITMVAL's followed by .EOLIST appears. Since this structure is a composite of the previous structures, a detailed example will not be given. .LEFT MARGIN -4 .HEADER LEVEL 1 Example of a type 2 list .LEFT MARGIN +4 Following is a sample of a type 2 list. Type 2 list was used since it incorporates the type 1 structures within itself. The following is the source definition for what we will examine: .TEST PAGE 4 .LITERAL .ITMVAL ,<$7$DUA233:>,- OPTION=,COLL=DWARVES .END LITERAL Here's binary breakdown of how this is built in memory: .TEST PAGE 16 .LITERAL 1E76: 0000 0001 - 1 value specified ($7$DUA233:) { .ITM ,OPTION=,COLL=DWARVES } 1E7A: 0003 001A - OPTION & COLL present, offset ^x1A to eof .ITM 1E7E: 010E 0006 - Descriptor header for 'RCVVSM' 1E82: 0000 1E86 - Address of 'RCVVSM' (immediately following) 1E86: 5656 4352 - 'RCVV' 1E8A: 4D53 - 'SM' 1E8C: 0000 0020 - COLL=DWARVES 1E90: 0000 0100 - OPTION-LNM$M_CONCEALED { .ITM <$1$DUA103> } 1E94: 0000 0016 - no OPTION, no COLL, offset 16 to end of .ITM 1E98: 010E 000A - Descriptor header for '$7$DUA233' 1E9C: 0000 1EA0 - Address of '$7$DUA233' (immediately following) 1EA0: 4424 3724 - '$7$D' 1EA4: 3332 4155 - 'UA23' 1EA8: 3A33 - '3:' .END LITERAL .LEFT MARGIN -4 .HEADER LEVEL 1 Selected specific list structure descriptions .LEFT MARGIN +4 This section will cover some of the list structures in a little more depth. The lists covered here are a representative selection of all of the less than plain-vanilla list structures used by SETUP. Read _& understand these, then look at SETUP to determine exactly how a particular list is processed. .LEFT MARGIN -4 .HEADER LEVEL 2 General description of mode specific lists .LEFT MARGIN +4 Certain list types in SETUP.MAR are mode-sensitive. That is to say that there is an individual list for each possible job execution mode that SETUP may encounter. The defined modes are INTERACTIVE, BATCH, NETWORK, OTHER, and FAILURE. The mode-specific lists work just like other lists, but there are individual labels for each mode. The labels are named using a three-letter mode specifier followed by two or three characters identifying the list. For example, the 'execute DCL command on exit' lists are mode-specific, and occur at the labels 'intdo:', 'batdo:', 'netdo', 'othdo:', and 'faldo:'. The prefixes are 'int', 'bat', 'net', 'oth', 'fal' for each of the types listed above, respectively. The 'do' portion is the name of the list. Usage of these lists which appear in the user data section is achieved using a 'vector' in the internal data area that looks like this: .TEST PAGE 1 .LITERAL modedo: .long othdo,netdo,batdo,intdo,faldo .END LITERAL which will be indexed using the value from 'modev:' to get the appropriate mode-specific list. Modev is set up by the main function subroutine 'defmode' using $GETJPI code JPI$_MODE. .LEFT MARGIN -4 .HEADER LEVEL 2 Default directory and device lists .LEFT MARGIN +4 These lists are mode specific and occur at the standard format labels for mode-specific lists under that names '_dir:', and '_drv:'. There are two lists '...dir' and '...drv' because the set default code is implemented in two pieces: 1) set default directory using SYS$SETDDIR, and 2) define logical SYS$DISK in SUPERVISOR using LIB$SET_LOGICAL. Even though the lists are type 1 lists, they _*do not_* contain standard _.ITM text for each .ITM. Rather, the list is used as a type 1 list only for the purposes of matching collection memberships. The 'real' data is pointed to using the 'OPTION_=' to specify the address of the associated text string descriptor. This basic technique of using a list simply for the purpose of collection membership matching is common among several other lists used by SETUP.MAR. It is important to _*NOT_* try to specify text in these types of lists since the class execution routines do not expect this. .LEFT MARGIN -4 .HEADER LEVEL 2 Terminal characteristics list .LEFT MARGIN +4 This list is also in two pieces: 1) characteristics to disable, and 2) characteristics to enable. The operation is performed by using $QIO to the terminal driver, function IO$__SENSEMODE, then bit-clearing the characteristics to disable, and then bit-setting the characteristics to enable, and then using $QIO function IO$__SETMODE to alter the terminal. Keep the order of operations in mind in case the same bits appear in both the enable and disable masks (the 'enable' will win). This list also uses the 'OPTION_=' format described above, but instead of pointing to a descriptor, it points to a 12-byte block contents of which are described in the terminal driver section of the I/O user's guide under the discussion of the setmode operation. .LEFT MARGIN -4 .HEADER LEVEL 2 Prompt list .LEFT MARGIN +4 This also is a list using the 'OPTION_=' format described above. The 'OPTION' address points to a series of blocks of five (5) longwords each containing (in order) the address of the prompt descriptor, the address of a terminal setup string descriptor or zero, a required terminal type or zero, required terminal basic characteristics or zero, and required terminal extended characteristics or zero. The series of blocks is terminated when a block is found that has a prompt descriptor address of zero. This means that the macro .EOLIST will correctly terminate the block list. Once the type 1 list match occurs, the class execution routine will simply store the address of the series of blocks pointed to by the 'OPTION' statment. Upon return from the list driver routines, the main function subroutine will search the list for the first entry that either specifies no matching criteria or which matches exactly all specified criteria. If a match has been found, then the setup string (if specified) is written to the terminal, and then the prompt is set. Only the first 32 characters of the prompt string can be used due to DCL restrictions. .LEFT MARGIN -4 .HEADER LEVEL 2 Processname list .LEFT MARGIN +4 This list is also an 'OPTION_=' type 1 list. The address passed is that of another type 1 list containing a minimum of eight (8) .ITM's whose text is the processnames to set. The main function subroutine will use the least significant three (3) bits of the current system time as an index into the matched list of precessnames. This allows a user to set up pseudo-random processnames. .LEFT MARGIN -4 .HEADER LEVEL 1 List traversal routines .LEFT MARGIN +4 These routines comprise the 'list driver routines'. There are three, one for each list type. We will cover them from the most complex list down to the least, since the most complex uses the less complex traversal routines. .LEFT MARGIN -4 .HEADER LEVEL 2 TRVSL2 .LEFT MARGIN +4 This routine is called with three arguments: 1) address of the class execution routine that will be called, 2) the address of the type 3 list to be examined, and 3) the address of the class matching routine to be used. In turn, after finding a match, TRVSL2 will call TRVSL1. .LEFT MARGIN -4 .HEADER LEVEL 2 TRVSL1 .LEFT MARGIN +4 This routine is called with three, or optionally, four arguments: 1) address of the class execution routine that will be called, 2) the address of the type 2 list to be examined, 3) the address of the class matching routine to be used, and maybe 4) the address of a 'level-2' text descriptor from TRVSL2. Even though this routine uses type 1 lists, it processes those lists independently from TRVSL0. .LEFT MARGIN -4 .HEADER LEVEL 2 TRVSL0 .LEFT MARGIN +4 This routine is called with three arguments: 1) address of the class execution routine that will be called, 2) the address of the type 1 list to be examined, and 3) the address of the class matching routine to be used. .LEFT MARGIN -4 .HEADER LEVEL 1 Class matching routines .LEFT MARGIN +4 These routine are passed as arguments to the list driver routines, and are used to determine whether or not an item in a list should be selected based on the membership status of the current node combined with the 'COLL_=' specification for the current item being examined. Call formats for all class matching routines are identical. Entry is by JSB rather than CALLx, arguments are: r0 _= address of current item header, and r6 _= address of next item header. Due to the structure of a .ITM, r6 may be negative indexed to access the OPTION and COLL arguments of the preceeding .ITM (which is the current .ITM). Also provided is the global label 'class:' which is a longword containing the complete membership collection for the current node. _*All*_ registers must be preserved, except the output r1 which will contain 0 or the 'OPTION' value if specified. Return either EQ condition to select the current item, or return NE contition to reject the item. You may use: .TEST PAGE 3 .LITERAL bicpsw #^m ;this sets a NE condition bispsw #^m ;this sets an EQ condition .END LITERAL to force the status to be set the way you need it. The following routines are listed in order of increasing restrictiveness. .LEFT MARGIN -4 .HEADER LEVEL 2 GETOPT__DEFAULT .LEFT MARGIN +4 This class matching routine returns NE (reject/fail) only if the node does not match the 'COLL' specified. If a 'COLL' is not specified, the item will always match. .LEFT MARGIN -4 .HEADER LEVEL 2 GETOPT__MEMBER .LEFT MARGIN +4 This class matching routine returns NE (reject/fail) for all nodes with no memberships. If the node's membership list is nonzero, then this routine will match if the 'COLL' matches, or if 'COLL' was not specified. .LEFT MARGIN -4 .HEADER LEVEL 2 GETOPT__INHIBIT .LEFT MARGIN +4 This class matching routine returns EQ (match) only if the node membership matches the specified 'COLL' statment, _*or_* if the node is a member of no classes _*and_* the 'COLL' statement was not specified. Take special note of the fact that if a node has a nonzero membership list, this routine _*will not_* match an item without a 'COLL' statment specified and matching. .LEFT MARGIN -4 .HEADER LEVEL 2 GETOPT__PROTECTED .LEFT MARGIN +4 This class matching routine returns EQ (match) if and only if the node membership is nonzero, matching, and 'COLL' was specified. All other combinations are rejected. .LEFT MARGIN -4 .HEADER LEVEL 1 Class execution routines .LEFT MARGIN +4 These routines are called from the list driver routines after a class matching routine as accepted the current item. The arguments passed to the class execution routines from traversal of a type 1 list (TRVSL0) are: 1) the descriptor for the current item text, and 2) the options longword. The arguments passed to the class execution routines from traversal of a type 2 list (TRVSL1) are: 1) the descriptor for the current item text, 2) the options longword, 3) the level-2 descriptor address (may be zero), and 4) thru n) are the descriptors of the values specified in the .ITMVAL, but in _*reversed_* order. .LEFT MARGIN -4 .HEADER LEVEL 1 Good luck _& best wishes .LEFT MARGIN +4 I've used this program now in one form or another for several years and I would now be hard-pressed to do without it. I sincerely hope that the work I've done here can be as beneficial to others as it has been to me. Good luck _& best wishes.