SETUP.MAR V4.0 SETUP.MAR V4.0 VMS V5.1-1 VMS V5.1-1 User Guide User Guide and and Reference Manual Reference Manual David G. North International Telecharge, Inc. 9999 W. Technology Blvd. Dallas, Texas 75220 November 20,1990 Table of Contents _____ __ ________ _____ __ ________ Table of Contents 0.1 Table of Contents . . . . . . . . . . . . . . . . i 0.2 Introduction . . . . . . . . . . . . . . . . . . iii 0.3 Format of this Manual . . . . . . . . . . . . . iii PART I ____ _ ____ _ PART I CHAPTER 1 Overview 1.1 Program Distribution and Build Instructions . . . 1-1 1.2 Basic Functions Description . . . . . . . . . . . 1-1 1.3 Modification Prerequisites . . . . . . . . . . . . 1-2 1.3.1 Classes, Collections, and Nodes . . . . . . . . 1-2 1.3.2 List Structures . . . . . . . . . . . . . . . . 1-3 CHAPTER 2 Guide to SETUP.MAR Macros 2.1 .COLL . . . . . . . . . . . . . . . . . . . . . . 2-1 2.2 DEFINE_CLASS . . . . . . . . . . . . . . . . . . . 2-1 2.3 DEFINE_COLLECTION . . . . . . . . . . . . . . . . 2-2 2.4 DEFINE_NODE . . . . . . . . . . . . . . . . . . . 2-2 2.5 .EOLIST . . . . . . . . . . . . . . . . . . . . . 2-2 2.6 .ITM . . . . . . . . . . . . . . . . . . . . . . . 2-3 2.7 .ITMVAL . . . . . . . . . . . . . . . . . . . . . 2-3 2.8 _MSGBITDEF . . . . . . . . . . . . . . . . . . . . 2-3 2.9 _PRTDEF . . . . . . . . . . . . . . . . . . . . . 2-4 CHAPTER 3 Guide to SETUP.MAR Customization 3.1 Code Generation Flags . . . . . . . . . . . . . . 3-1 3.1.1 DISABLE_BOOST . . . . . . . . . . . . . . . . . 3-1 3.1.2 DISABLE_CMKRNL . . . . . . . . . . . . . . . . . 3-1 3.1.3 DISABLE_CMEXEC . . . . . . . . . . . . . . . . . 3-2 3.1.4 DISABLE_CMSUPER . . . . . . . . . . . . . . . . 3-2 3.2 Class, Collection, And Node Definitions . . . . . 3-2 3.3 List Definitions . . . . . . . . . . . . . . . . . 3-2 3.3.1 Automatic Symbol Deletion . . . . . . . . . . . 3-3 3.3.2 Symbol Definition . . . . . . . . . . . . . . . 3-3 3.3.3 Logical Name Definition . . . . . . . . . . . . 3-3 3.3.4 DCL Key Definitions . . . . . . . . . . . . . . 3-4 3.3.5 Default Process Names . . . . . . . . . . . . . 3-4 3.3.6 Default Protection . . . . . . . . . . . . . . . 3-4 3.3.7 Default Message Flags . . . . . . . . . . . . . 3-5 3.3.8 Default Privileges . . . . . . . . . . . . . . . 3-5 3.3.9 Default Drives & Directories . . . . . . . . . . 3-5 3.3.10 Broadcast Classes . . . . . . . . . . . . . . . 3-5 3.3.11 Terminal Characteristics . . . . . . . . . . . . 3-5 3.3.12 Operator Console Enable . . . . . . . . . . . . 3-6 3.3.13 Set DCL Prompt . . . . . . . . . . . . . . . . . 3-6 3.3.14 Set DCL Verify State . . . . . . . . . . . . . . 3-6 3.3.15 Execute Final Command On Exit . . . . . . . . . 3-6 PART II ____ __ ____ __ PART II CHAPTER 4 Implementation & Data Structures 4.1 General SETUP Architecture . . . . . . . . . . . . 4-1 4.1.1 User Data Section . . . . . . . . . . . . . . . 4-1 4.1.2 Internal Data Section . . . . . . . . . . . . . 4-1 4.1.3 List Driver Routines . . . . . . . . . . . . . . 4-2 4.1.4 Class Matching Routines . . . . . . . . . . . . 4-2 4.1.5 Class Execution Routines . . . . . . . . . . . . 4-2 4.1.6 Main Function Subroutines . . . . . . . . . . . 4-2 4.1.7 Main Execution Module . . . . . . . . . . . . . 4-2 4.2 List Types . . . . . . . . . . . . . . . . . . . . 4-3 4.2.1 Type 1 List . . . . . . . . . . . . . . . . . . 4-3 4.2.2 Type 2 List . . . . . . . . . . . . . . . . . . 4-3 4.2.3 Type 3 List . . . . . . . . . . . . . . . . . . 4-3 4.3 Example Of A Type 2 List . . . . . . . . . . . . . 4-4 4.4 Selected Specific List Structure Descriptions . . 4-4 4.4.1 General Description Of Mode Specific Lists . . . 4-4 4.4.2 Default Directory And Device Lists . . . . . . . 4-5 4.4.3 Terminal Characteristics List . . . . . . . . . 4-5 4.4.4 Prompt List . . . . . . . . . . . . . . . . . . 4-5 4.4.5 Processname List . . . . . . . . . . . . . . . . 4-6 4.5 List Traversal Routines . . . . . . . . . . . . . 4-6 4.5.1 TRVSL2 . . . . . . . . . . . . . . . . . . . . . 4-6 4.5.2 TRVSL1 . . . . . . . . . . . . . . . . . . . . . 4-6 4.5.3 TRVSL0 . . . . . . . . . . . . . . . . . . . . . 4-7 4.6 Class Matching Routines . . . . . . . . . . . . . 4-7 4.6.1 GETOPT_DEFAULT . . . . . . . . . . . . . . . . . 4-7 4.6.2 GETOPT_MEMBER . . . . . . . . . . . . . . . . . 4-7 4.6.3 GETOPT_INHIBIT . . . . . . . . . . . . . . . . . 4-8 4.6.4 GETOPT_PROTECTED . . . . . . . . . . . . . . . . 4-8 4.7 Class Execution Routines . . . . . . . . . . . . . 4-8 4.8 Good Luck & Best Wishes . . . . . . . . . . . . . 4-8 ii Introduction ____________ ____________ 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: * 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. 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. Format of this Manual ______ __ ____ ______ ______ __ ____ ______ 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. iii SETUP.MAR V4.0 SETUP.MAR V4.0 VMS V5.1-1 VMS V5.1-1 PART I ____ _ ____ _ PART I David G. North International Telecharge, Inc. 108 South Akard, AT-5 Dallas, Texas 75202 November 20,1990 CHAPTER 1 Overview ________ ________ Overview This chapter contains an overview of SETUP.MAR. 1.1 Program Distribution and Build Instructions 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: $ LIBRARY/MACRO/CREATE SETUPMLB SETUPMLB $ MACRO SETUP $ MESSAGE SETUPMSG $ LINK SETUP,SETUPMSG/CONTIG/NOTRACE 1.2 Basic Functions Description 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: 1-1 ___________ ___ _______ Description DCL Example * 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 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. 1.3 Modification Prerequisites 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. 1.3.1 Classes, Collections, and Nodes 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, 1-2 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: 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 1.3.2 List Structures 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: 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 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 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 1-3 CHAPTER 2 Guide to SETUP.MAR Macros _____ __ _________ ______ _____ __ _________ ______ Guide to SETUP.MAR Macros 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. 2.1 .COLL 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. Usage: DEFINE_CLASS TEST1 ;Symbolic DEFINE_CLASS TEST2 ;Symbolic DEFINE_COLLECTION ALL_TESTS,TEST1,TEST2 ;Symbolic label: .COLL ALL_TESTS ;Longword of storage 2.2 DEFINE_CLASS 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. 2-1 Usage: DEFINE_CLASS TEST1 2.3 DEFINE_COLLECTION 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. Usage: DEFINE_CLASS TEST1 DEFINE_CLASS TEST2 DEFINE_COLLECTION ALL_TESTS,TEST1,TEST2 [,...] 2.4 DEFINE_NODE 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. Usage: DEFINE_CLASS TEST1 DEFINE_CLASS TEST2 DEFINE_CLASS OPER DEFINE_COLLECTION ALL_TESTS,TEST1,TEST2 DEFINE_NODE GEMINI,OPER,ALL_TESTS [,...] 2.5 .EOLIST 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. 2-2 Usage: .EOLIST 2.6 .ITM 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. Usage: .ITM .ITM OPTION=label,COLL=ALL_NODES 2.7 .ITMVAL 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. Usage: .ITMVAL ,, .ITMVAL ,,COLL=CMKRNL 2.8 _MSGBITDEF 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'. Usage: defmsg: .ITM OPTION=MSGBIT_M_TEXT,COLL=CMKRNL 2-3 2.9 _PRTDEF 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. Usage: defpro: .ITM OPTION=<!- !- !- > 2-4 CHAPTER 3 Guide to SETUP.MAR Customization _____ __ _________ _____________ _____ __ _________ _____________ Guide to SETUP.MAR Customization 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. 3.1 Code Generation Flags 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. 3.1.1 DISABLE_BOOST 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. 3.1.2 DISABLE_CMKRNL 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 3-1 privilege on any machines. In order to completely disable generation of kernel mode code, you may uncomment the DISABLE_CMKRNL flag definition. 3.1.3 DISABLE_CMEXEC 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. 3.1.4 DISABLE_CMSUPER 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. 3.2 Class, Collection, And Node Definitions 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. 3.3 List Definitions 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): 3-2 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 3.3.1 Automatic Symbol Deletion 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. 3.3.2 Symbol Definition 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. 3.3.3 Logical Name Definition 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. 3-3 3.3.4 DCL Key Definitions 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 (setstate 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. 3.3.5 Default Process Names 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. 3.3.6 Default Protection 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. 3-4 3.3.7 Default Message Flags 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. 3.3.8 Default Privileges 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. 3.3.9 Default Drives & Directories 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. 3.3.10 Broadcast Classes 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. 3.3.11 Terminal Characteristics 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. 3-5 3.3.12 Operator Console Enable 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. 3.3.13 Set DCL Prompt 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: .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 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. 3.3.14 Set DCL Verify State 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. 3.3.15 Execute Final Command On Exit 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. 3-6 SETUP.MAR V4.0 SETUP.MAR V4.0 VMS V5.1-1 VMS V5.1-1 PART II ____ __ ____ __ PART II David G. North International Telecharge, Inc. 108 South Akard, AT-5 Dallas, Texas 75202 November 20,1990 CHAPTER 4 Implementation & Data Structures ______________ _ ____ __________ ______________ _ ____ __________ Implementation & Data Structures 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. 4.1 General SETUP Architecture 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. 4.1.1 User Data Section This section defines all user-selectable parameters. It is referenced from all levels of the code sections, and from the internal data section. 4.1.2 Internal Data Section 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. 4-1 4.1.3 List Driver Routines 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. 4.1.4 Class Matching Routines 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. 4.1.5 Class Execution Routines 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. 4.1.6 Main Function Subroutines 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. 4.1.7 Main Execution Module 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. 4-2 4.2 List Types 4.2.1 Type 1 List This list type consists of a number of .ITM's followed by .EOLIST. The .ITM arguments are: .ITM [][,OPTION=][,COLL=] Each item has the following structure: +--------+--------+ | -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 +-----------------+ 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. 4.2.2 Type 2 List This list type consists of a number of .ITMVAL's followed by .EOLIST. Each item has the following structure: The .ITMVAL arguments are: .ITMVAL [][,OPTION=][,COLL=],- [][,][...,] Each item has the following structure: +--------+--------+ | 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 +--------+--------+ 4.2.3 Type 3 List 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 4-3 given. 4.3 Example Of A Type 2 List 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: .ITMVAL ,<$7$DUA233:>,- OPTION=,COLL=DWARVES Here's binary breakdown of how this is built in memory: 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:' 4.4 Selected Specific List Structure Descriptions 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. 4.4.1 General Description Of Mode Specific Lists 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 4-4 'vector' in the internal data area that looks like this: modedo: .long othdo,netdo,batdo,intdo,faldo 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. 4.4.2 Default Directory And Device Lists 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$SETLOGICAL. 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. 4.4.3 Terminal Characteristics List 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. 4.4.4 Prompt List 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 4-5 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. 4.4.5 Processname List 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. 4.5 List Traversal Routines 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. 4.5.1 TRVSL2 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. 4.5.2 TRVSL1 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. 4-6 4.5.3 TRVSL0 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. 4.6 Class Matching Routines 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: bicpsw #^m ;this sets a NE condition bispsw #^m ;this sets an EQ condition to force the status to be set the way you need it. The following routines are listed in order of increasing restrictiveness. 4.6.1 GETOPT_DEFAULT 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. 4.6.2 GETOPT_MEMBER 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. 4-7 4.6.3 GETOPT_INHIBIT 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. 4.6.4 GETOPT_PROTECTED 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. 4.7 Class Execution Routines 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. 4.8 Good Luck & Best Wishes 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. 4-8