SCAN USER'S MANUAL SCAN USER'S MANUAL Reed Powell Digital Equipment Corp. Western Region Software Operations Group Santa Clara, California 11-June-79 EDITION: 2.5 EDITION: 2.5 -OLS This manual reflects the status of SCAN, Version 7(11,541) This is a modified version of SCAN 7(541), which contains a number of additions, improvements and corrections installed at On-Line Systems, Inc. ("OLS"). While it reflects the overall operation of any SCAN release from 7(541) upwards, no guarantee is made as to the applicability or correctness of statements made herein. Ownership rights to the contents remain Ownership rights to the contents remain with On-Line Systems, Inc., Pittsburgh, with On-Line Systems, Inc., Pittsburgh, Pa. Pa. Table of Contents Table of Contents 1. Introduction 2. Routine Call Definitions 3. The Command Scanners (Overview) 4. Defining Switches - "SWTCHS" Macro 5. The "DM" and "KEYS" Macros 6. Defining the "STORAGE" Field 7. Default Value Handling 8. File-Spec Scanning 9. ISCAN - Scanner Initialization 10. TSCAN - The Traditional Scanner 11. OSCAN - Options File Scanning 12. VSCAN - The Verb Form Scanner 13. PSCAN - The Partial Mode Scanner 14. Accessing SCAN 15. Example of Using SCAN 16. Using the Miscellaneous Routines 17. Appendices: o Notes on using SCAN o Notes on using WILD o DEC/OLS differences in SCAN and WILD o SCNMAC o $SCNDC o SWTCHS, DOSCAN, DM & KEYS Examples o LIST OF CUSPS & THE SCANNERS THEY USE 18. Index CHAPTER 1 INTRODUCTION 1.1 INTRODUCTION SCAN is a library of well-written routines of general applicability to a wide variety of user programs. Included in SCAN are: command scanners; input and output routines for file specifications, numbers, dates, strings and characters; space allocation; data management; universal date-time conversions; register saving; and indirect-file handling. All routines are written to be virtually independent of the main program's register conventions. Only two constraints exist: o AC17 must be a stack pointer, with a stack depth at call time of at least 15. o AC1 and AC7 are used to pass arguments, and (when applicable), return values. All routines will preserve any registers which they do not return a value in. The default character input and output method is via TTCALLs, but the user is free to specify the address of his own routine if he so desires. For character input, the same rule applies, but the user must always call an initialization routine as well. The routines described in chapter two will be those which are the most generally useful, and fall into the following groupings: INTRODUCTION Page 1-2 Initialization Register Saving Space Allocation Output Routines - all Input Routines - numbers, dates, file-specs, and words The register mnemonics used will be those of SCAN, which are: T1 - T4: 1-4 ("Temporaries") P1 - P4: 5-10 ("Permanents") P: 17 ("Stack Pointer") All calls are via a PUSHJ, and return at the call+1 or call+2. SCAN is loaded in library search mode from (70001,1). (See the section on "Accessing SCAN and its Macros".) CHAPTER 2 ROUTINE CALL DEFINITIONS 2.1 INITIALIZATION .TYOCH - Use the address in T1 as the typeout routine. Returns the previous routine's address (if any) in T1. .ISCAN - Initialize for input. T1 is a pointer to an argument block: T1/ LENGTH,, BLOCK BLOCK: Z +1: Z +2: INPUT ROUTINE,,OUTPUT ROUTINE +3: Z +4: Z +5: Z If "Input Routine" or "Output Routine" (or both) is zero, then TTCALL I/O (e.g.: INCHWL or OUTCHR) is used. The chapter on ".ISCAN" describes the meanings and usages of the other words in the argument blocks. ----------------------------------------------- NOTE: Those routine descriptions marked with an asterisk (*) in the outer left hand margin are not a part of the standard Digital supplied SCAN. These routines are peculiar to the modified version of SCAN for which this manual was written. ROUTINE CALL DEFINITIONS Page 2-2 REGISTER-SAVING 11 Jun 79 2.2 REGISTER-SAVING .SAVE1 - Save P1 .SAVE2 - Save P1-P2 .SAVE3 - Save P1-P3 .SAVE4 - Save P1-P4 *.SAV1T - Save T4 * *.SAV2T - Save T3-T4 * *.SAV3T - Save T2-T4 * *.SAVET - Save T1-T4 * .POPJ - Non-skip return (do a POPJ) .POPJ1 - Skip return .PSH4T - Stack T1-T4 .POP4T - Unstack T1-T4 All of the .SAVxx routines automatically restore the registers on a skip or non-skip return from the routine which called the .SAVxx routine. 2.3 SPACE ALLOCATION *.GTWDS - Allocate (upwards from .JBFF) the number of words * in T1. T1 is returned with the address, if the allocation was successful, of the first word. The allocated area will be zeroed. On a failure, T1 will contain the negative number of words available. 2.4 OUTPUT ROUTINES - TEXT .TSIXN - Type T1 in SIXBIT. .TSTRG - Type ASCIZ string which T1 points to. .TXWWW - Type a wild octal word; T1 contains the word, T2 contains the mask. .TMOHW - Type a wild octal half word; the word is in LH of T1, the mask is in RH. ROUTINE CALL DEFINITIONS Page 2-3 OUTPUT ROUTINES - DATE/TIME 11 Jun 79 2.5 OUTPUT ROUTINES - DATE/TIME .TDTTM - Type the date and time which is in T1; the argument is in the Universal Date/Time format. .TDATE - Type the date which is in T1; the argument is in the standard DEC format (a la DATE UUO). .TDATN - Type the current date. .TTIME - Type the time which is in T1; the argument is the number of milliseconds past midnight (a la MSTIME UUO). .TTIMN - Type the current time. 2.6 OUTPUT ROUTINES - NUMBERS .TDECW - Type T1 as a decimal number. .TDEC2 - Type T1 as a decimal number with at least two positions; fill character is in T2. .TOCTW - Type T1 as an octal number. .TRDXW - Type T1 in the radix which is in T3. .TXWDW - Type T1 as an octal number, in XWD format (LH,,RH) .TVERW - Type T1 as a standard DEC version number. .TCORW - Type T1 as a core size, in P, K, or Words. .TBLOK - Type T1 as a file size, in Blocks or Words. .TPPNW - Type T1 as a PPN. 2.7 OUTPUT ROUTINES - FILE SPECIFICATIONS .TOLEB - Type a file-spec. T1 points to an OPEN UUO block; T2 points to an extended LOOKUP or ENTER UUO block of at least four words. ROUTINE CALL DEFINITIONS Page 2-4 OUTPUT ROUTINES - CHARACTER 11 Jun 79 2.8 OUTPUT ROUTINES - CHARACTER .TCHAR - Type T1 as an ASCII character. .TFCHR - Type T2, using mnemonics and abbreviations for non-printing characters, and preceeding lower-case characters with an apostrophe. .TCRLF - .TSPAC - .TTABC - Type a horizonal tab. .TCOLN - Type a colon. .TASTR - Type an asterisk. .TRBRK - Type a right bracket character. .TCOMA - Type a comma. *.T2CRL - * *.T4CRL - Type 1, 2 or 4 CRLF's, respectively * *.T2SPC - * *.T4SPC - Type 1, 2, or 4 spaces, respectively * *.TPLUS - Type a plus sign. * *.TSLSH - Type a slash character. * *.TAPOS - Type an apostrophe. * *.TCART - Type a caret (up arrow on some printers). * *.TRPAR - Type a right parenthesis. * *.TRANG - Type a right angle bracket * *.TLPAR - Type a left parenthesis. * *.TLBRK - Type a left bracket. * *.TLANG - Type a left angle bracket. * *.TAMPR - Type an ampersand. * *.TAROW - Type a left arrow (underscore on some printers). * *.TATSI - Type an at-cost sign. * *.TDASH - Type a dash. * *.TDOLR - Type a dollar sign. * *.TEQUL - Type an equal sign. * *.TEXCL - Type an exclamation mark. * *.TPCNT - Type a per cent sign. * *.TSEMI - Type a semi-colon. * *.TQUOT - Type a double-quote mark. * *.THASH - Type a hash mark ("#"). * *.TBKSL - Type a back-slash character ("\"). * ROUTINE CALL DEFINITIONS Page 2-5 INPUT ROUTINES - INTRODUCTION 11 Jun 79 2.9 INPUT ROUTINES - INTRODUCTION The input routines will normally leave their result in accumulator "P3" - which they use under the alias "N". Single character input routines will use "P4", under the alias "C". Most routine descriptions given below will list two names; the second one will often be the same as the first but with the last character of the name changed to "C". The second routine entry point is used when the next character in the input stream is already in accumulator "CH" ("P4"), while the first routine entry point is used when the next character in the stream has not yet been input. This ability to already have the next input character waiting is used in conjunction with the so called "re-eat" facility of SCAN, which allows a program to look-ahead one character. The routine ".REEAT" is used to perform this, and is described later in this chapter in the section "MISCELLANEOUS ROUTINES." More information on this is included in the chapter on USING THE MISCELLANEOUS ROUTINES. ROUTINE CALL DEFINITIONS Page 2-6 INPUT ROUTINES - STRING AND NUMERIC 11 Jun 79 2.10 INPUT ROUTINES - STRING AND NUMERIC .SIXSW, .SIXSC - Input a SIXBIT word into P3. .OCTNW, .OCTNC - Input an octal number into P3. .DECNW, .DECNC - Input a decimal number into P3. Optional suffixes for decimal and octal input are: K, M and G, for the base raised to the third, sixth, and nineth power, respectively. .NAMEW, .NAMEC - Input a possibly wild SIXBIT word; word is in P3, mask is in "MASK". .ASCQW, .ASCQC - Input a possibly quoted ASCII string. The string will be input into the area (inside SCAN) beginning at the global symbol ".NMUL", and extending no further than the symbol ".NMUE". Input terminates at the first non-alphanumeric character. Any characters within the string being typed, but which cannot be fit into the buffer, is lost. Since the symbols are global, they are accessable from the calling program, which should BLT them to a safe place. .SIXQW, .SIXQC - This functions exactly as does .ASCQW/.ASCQC above, except that the characters are stored in SIXBIT rather than ASCII. .SIXMW, .SIXMC - This functions exactly as does .SIXQW/.SIXQC above, except that the input string cannot be quoted. 2.11 INPUT ROUTINES - DATE/TIME [More information on this subject is contained in the later chapter on USING THE MISCELLANEOUS ROUTINES] .DATIM, .DATIC - Input date-time into P3, storing it in universal format. .DATIP, .DATIQ - Input a date-time in the past into P3, storing it in universal format. ROUTINE CALL DEFINITIONS Page 2-7 INPUT ROUTINES - DATE/TIME 11 Jun 79 .DATIF, .DATIG - Input a date-time in the future into P3, storing it in universal format. Legal date-time formats, examples and explanations are: ROUTINE CALL DEFINITIONS Page 2-8 INPUT ROUTINES - DATE/TIME 11 Jun 79 FORMAT EXAMPLE EXPLANATION DATE-SPEC: day WED WEDNESDAY day offset 123D 123 days ago from now MM-DD 6-12 Jun. 12 MM-DD-Y 6-12-6 Jun. 12, 1976 MMM-DD-YY JUN-12-76 June 12, 1976 DD-MMM-YYYY 12-JUN-1976 June 12, 1976 Mnemonic YESTERDAY TOMORROW TODAY TIME-SPEC: HH 12 noon HH:MM 13:02 2 past 1 PM HH:MM:SS 1:02:37 37 secs past 1:02 AM mnemonic NOON LOGIN DATE-TIME: date-spec:time-spec JUN-12-76:13:02:37 2.12 INPUT ROUTINES - VERSION NUMBER .VERSW, .VERSC - Input a version number into P3. Version number format is: NNMM(EE) where: NN is the major version, blank to 511 MM is the minor version, blank to ZZ (EE) is the edit number, blank to 202,143 ROUTINE CALL DEFINITIONS Page 2-9 INPUT ROUTINES - CORE & FILE SIZES 11 Jun 79 2.13 INPUT ROUTINES - CORE & FILE SIZES .COREW, .COREC - Input a core size in words, pages, or K; suffixes are: W (default), P and K, respectively. Returns size, in words, in P3. .BLOKW, .BLOKC - Input a file size in words or blocks; suffixes are: W (default) or B. Returns size in words in P3. 2.14 INPUT ROUTINES - CHARACTERS .TICAN - Check for an alphanumeric character in P4. Non-skips if not alphanumeric, skips if it is. .TIMUC - Convert character in P4 to upper case, if it is in lower case. .TIAUC - Input a character into P4, handling lower case, altmodes and all compressions. .TIALT - Input a character, handling altmodes and space compression, into P4. .TIGET - Gets a character into P4, with no equivalencing. For .TIAUC and .TIALT, P4 is returned in the following format: 1-177: actual character 0: end-of-line character -1: altmode -2: end-of-file (Control Z or EOF on indirect file) The following are Guide Words (pseudo characters): 4000: 'AND' 4001: 'OR' 4002: 'NOT' 4003: 'TO' 4004: 'FROM' 4005: 'INPUT' 4006: 'OUTPUT' 4007: 'SOURCE' 4010: 'LIST' 4011: 'OBJECT' ROUTINE CALL DEFINITIONS Page 2-10 Input: Character, File Specifications 11 Jun 79 See "SYNTAX REPRESENTATIONS" in Chapter 8. Also refer to Appendix D - "SCNMAC." 2.15 INPUT ROUTINE - FILE SPECIFICATIONS .FILIN - Input a file specification. Details on its usage is the subject of a later chapter in this document. ROUTINE CALL DEFINITIONS Page 2-11 MISCELLANEOUS ROUTINES 11 Jun 79 2.16 MISCELLANEOUS ROUTINES .RUNCM - Process a /RUN specification, if any has been encountered. No arguments are possible; returns only if no /RUN was ever seen on the line, or if the RUN UUO failed. Usually called right before normal program termination code. More on this routine in included in a later chapter on USING THE MISCELLANEOUS ROUTINES. .MKPJN - Make a CCL job number. Call with the job number (or whatever) in T1. Returns with SIXBIT form of argument in (RH) of T1. More information is in a later chapter on USING THE MISCELLANEOUS ROUTINES. .LKNAM - Do a table search for an exact or abbreviated match. Call with SIXBIT value in T2, and a pointer in T1 of the form: IOWD length, table-address Skip-returns if a match was found, with (RH) of T1 pointing to the match, and (LH) of T1 zero if it was abbreviated, or negative if an exact match. Non-skip returns if unsuccessful, with T1 negative if no match was found, or positive if multiple matches were found. A later chapter (USING THE MISCELLANEOUS ROUTINES) covers this routine in greater detail. *.RAND - Generate a random number between 0 and 2**18-1, * ** storing it in T1. *.RANDM - Same as .RAND, but on call T1 contains the upper * bound on the result. Method used is "middle-squares." [More information on the following routines for date and time conversion is included in a later chapter: USING THE MISCELLANEOUS ROUTINES] .CNTDT - Convert universal date/times to DEC formats. Call with universal form in T1, returns with DEC date in T2, and MS in T1. .GTNOW - Get current date and time, in universal format, into T1. .CNVDT - Convert DEC format date/time to universal format. Call with time in T1, stored as the number of milliseconds past midnight (MSTIME UUO). The date ROUTINE CALL DEFINITIONS Page 2-12 MISCELLANEOUS ROUTINES 11 Jun 79 is in T2, stored in the standard DEC format (DATE UUO). Returns universal form in T1 (or -1 if date was beyond September 27, 2217). Note that "Day 0" was a Wednesday, and so (T1)/7 gives a day of week index, with Wednesday being 0. ROUTINE CALL DEFINITIONS Page 2-13 MISC: Scan-Block Conversion, Input Back-Spacing 11 Jun 79 .STOPB - Convert a "scan-block" (see the later section on "FILE-SPEC SCANNING") to OPEN and extended LOOKUP/ENTER blocks. Call with: T1/ length,,address of scan-block T2/ ,,address of OPEN block T3/ length,,address of LOOKUP block T4/ ,,address of PATH block (9 words) Returns non-skip (error) if any wild-cards were seen in the scan-block; otherwise it skip-returns. .REEAT - Cause the contents of P4 to be the next character to be read. P4 will normally contain the current character. Call is simply MOVEI P4, char PUSHT P,.REEAT More information on this routine, and the general concept of positioning input from the command line, is covered in a later chapter on USING THE MISCELLANEOUS ROUTINES. .CLRBF - This routine will clear any type ahead in the input stream. No arguments are passed, no values returned, and control always comes to the calling point +1. .GTWRD - Get a word from a list. Call with: T1/ table address T2/ length of table On return (always to Call +1), the values are: T1/ incremented by 1 T2/ decremented by 1 T3/ data from list, or 0 if at end This routine is covered in greater detail, along with the following routine (.PTWRD), in a later chapter on USING THE MISCELLANEOUS ROUTINES. .PTWRD - Put a word into a list. This is meant to be used along with .GTWRD, above. Control always returns to the call +1 location. Calling sequence is: ROUTINE CALL DEFINITIONS Page 2-14 MISC: Scan-Block Conversion, Input Back-Spacing 11 Jun 79 T1/ table address T2/ maximum table length T3/ data to be stored PUSHJ P,.PTWRD## T1/ incremented by 1 T2/ decremented by 1 T3/ old data from location stored into .MKMSK - This routine makes a mask for its argument word. The argument must be SIXBIT data. The mask contains 1s where the argument had non-blanks. Calling sequence is: MOVE T3,argument PUSHJ P,.MKMSK -always returns here- T1/ mask for argument More information on this routine is in the chapter USING THE MISCELLANEOUS ROUTINES. .TDIRB - This routine is used to type out directory blocks. Three formats are accepted: 1) Extended LOOKUP/ENTER blocks; 2) PATH blocks; and 3) "bi-words", which is an internal SCAN format. The calling sequence is: HRLI T1,code HRRI T1,address PUSHJ P,.TDIRB## -always returns here- where "code" is one of the following: 1 if (RH) is address of LOOKUP/ENTER block 2 if (RH) is a PATH block address 3 if (RH) is address of "bi-words" More information on .TDIRB is in the chapter USING THE MISCELLANEOUS ROUTINES. .ISLGI - This routine is used to test to determine if the calling job is logged in. No argument is passed. The value returned is: PUSHJ P,.ISLGI## -here with T1=-1 if not logged in, or T1=1 if indeterminate -here if logged in (skip ret) CHAPTER 3 THE COMMAND SCANNERS 3.1 INTRODUCTION This chapter will discuss the types of command scanners provided by SCAN. The actual details of usage are covered separately in later chapters on each scanner. The purpose of this chapter is to present the concepts of command scanners and switch types which are relevant to determining which scanner is best for various applications. 3.2 OVERVIEW OF THE 4 SCANNERS Within SCAN there are four basic Command Scanning routines, and an initialization routine. The four scanners all accept the same switch formats; their only differences lie in the structure of the command line itself. The scanners are: 3.2.1 TSCAN This is the so-called "Traditional Scanner." Command lines are of the form: OUTPUT = INPUT OUTPUT = INPUT,INPUT, ... or INPUT Users of this syntax are PIP and DIRECT. THE COMMAND SCANNERS Page 3-2 OVERVIEW OF THE 4 SCANNERS 11 Jun 79 3.2.2 VSCAN This is the "Verb Form Scanner." Command lines look like: COMMAND-WORD /SWITCH/SWITCH COMMAND-WORD /SWITCH/SWITCH FILE-SPEC or COMMAND-WORD DUMP and BACKUP programs are users of this format. 3.2.3 OSCAN This is the "Option File Scanner." This scans the options-file SWITCH.INI for entries of the form: NAME /SWITCH/SWITCH or NAME:OPTION /SWITCH/SWITCH Users of this feature include LOGIN, DIRECT, BACKUP, SOS, and ALKFIL. 3.2.4 PSCAN PSCAN is the "Partial Mode" Scanner. Commands are of the TSCAN style, but only part of the line is processed by SCAN. Command lines might be of the format: mumble mumble /SWITCH /SWITCH In this case, the "mumble mumble" portion of the command could be parsed by the user program, and PSCAN would be used to do the "/SWITCH" processing. An example of a PSCAN user is CREDIR. THE COMMAND SCANNERS Page 3-3 SWITCH-FORMATS: 11 Jun 79 3.3 SWITCH-FORMATS: The general formats of a switch specification are quite simple -- which format a particular switch will require depends on how it is defined in the SWTCHS Macro (described later). The simplest switches are those which take no value -- it is their presence (or absence) which is important. The presence of the switch will cause SCAN to deposit a predefined value into a predefined memory byte or word. It is also possible for these switches to be, in effect, three-way rather than two-way. Either the switch is absent, present, or present with "NO" prefixed to it. Examples of these types of switches are: /FAST /HELP /MAP /NOMAP The second type of switch is one that takes a value (or values) which must be part of a pre-defined list of legal values for that switch. The "value" of the switch is then the numeric index, into the table of legal values, of the value specified. For example, if the legal values for "/MODE" were "ASCII, OCTAL, SIXBIT, DECIMAL," then: /MODE:OCTAL value = 1 /MODE:DECIMAL value = 3 /MODE is illegal A variation of this switch allows for defaults when: o The switch was not mentioned. or o The switch was mentioned, but without an explicit value. The third type of switch is one that takes a more or less arbitrary value. This value can be anything the user desires. SCAN is supplied with the name of a routine to "pick-up" the value, and a description of where and how to store the value. If desired, a maximum value may be specified. In addition, the comment above about defaults for Type 2 switches also holds here. The switch may be defined to take only one value, or to take many values. Typical values are numbers and file specifications. Examples are: THE COMMAND SCANNERS Page 3-4 Switch Formats 11 Jun 79 /WIDTH:75 /ABCD:(12,34,56,78) /FILE:MYFIL.MAC[70001,1] The three basic switch types can be summarized as: TYPE 1 - no value TYPE 2 - specific values only TYPE 3 - arbitrary values 3.4 FILE-SPECIFICATIONS The format of a file specification for SCAN is quite general. No ordering between the components is either expected or necessary. The basic parts of a file-spec are: o DEVICE: 1-3 SIXBIT characters followed by a colon. o FILENAME: 1-6 SIXBIT characters. o EXTENSION: 1-3 SIXBIT characters, preceeded by a period. o PPN: A Project Number (1-377777 octal), a Programmer Number (1-377777 octal) and (optionally) an SFD specification, in one of the following arrangements: [PROJECT,PROGRAMMER] [PROJECT,PROGRAMMER,sfd,sfd,...] [,PROGRAMMER] uses logged-in PROJECT [,PROGRAMMER,sfd,sfd,...] -dittoe- [PROJECT,] uses logged-in PROGRAMMER [PROJECT,,sfd,sfd,...] -dittoe- [,] uses logged-in PPN [,,sfd,sfd,...] -dittoe- [-] uses default path o SWITCHES: Any of the switches described later as "Internal Scan Switches." (See "FILE-SPEC SCANNING.") THE COMMAND SCANNERS Page 3-5 DEFAULT VALUES FOR SWITCHES 11 Jun 79 3.5 DEFAULT VALUES FOR SWITCHES When the user calls SCAN, he has the option of specifying a set of defaults for any of the above components. SCAN will use these defaults in the event that the user does not specify the corresponding component of the specification. More of this topic is covered in detail in a later chapter -- "DEFAULT VALUE HANDLING." CHAPTER 4 DEFINING SWITCHES - THE "SWTCHS" MACRO 4.1 DEFINING SWITCHES - "SWTCHS" MACRO The purpose of this chapter is to cover the topic of switch definition. it is necessary for the user program to provide SCAN with information on the switches to be parsed. This includes data such as the switch name, the type of argument, if any, where to store the parsed values, and the like. The definition process has been made relatively simple and painless by the use of macros supplied by SCNMAC. 4.2 SWTCHS & DOSCAN -- USAGE The properties of each switch to be scanned for are defined via a set of MACROs provided by SCAN. There is always a one-to-one correspondence between a switch and its MACRO specification. These switch MACROs are all included within a user defined MACRO called "SWTCHS". The definition of SWTCHS is of the following simple form: DEFINE SWTCHS < macro-call . . . . macro-call . . . . . . . macro-call . . . . >;END OF SWTCHS MACRO DEFINING SWITCHES - THE "SWTCHS" MACRO Page 4-2 SWTCHS & DOSCAN -- USAGE 11 Jun 79 Once the switches are defined in SWTCHS, the scanning tables are generated by calling the macro "DOSCAN". The format of this call is: DOSCAN (NAME) where "NAME" is a legal MACRO-10 label from 1-5 characters. The tables generated for use by SCAN will have labels of the form "NAMEx," where "x" identifies the specific table. The tables involved are: o nameN - The table of switch names (in SIXBIT), one per word. o nameD - The table of default values. o nameM - The table of routine addresses for processing switch values. o nameP - The table of pointers used for storing values. o nameL - This symbol's value is the length of each of the above tables. 4.3 SWTCHS -- DEFINITION There are four switch defining macros (USED WITHIN SWTCHS) which are described below: SS (Switch-Storage), SN SS S S SN (Switch-Name), SL (Switch-List), and SP (Switch-Pointer). S N SL S L SP S P fsyntax A "typical" switch-table definition might now look like: DEFINE SWTCHS < SS... SN... SL... SP... > DOSCAN (TEST) The switch macros and their parameters are: 1. SS - This is for switches described above as "TYPE 1". No value is specified on the command line; instead, a pre-defined value is stored. The SS format is: DEFINING SWITCHES - THE "SWTCHS" MACRO Page 4-3 SWTCHS -- DEFINITION 11 Jun 79 SS NAME, STORAGE, VALUE, FLAGS When the switch is encountered, VALUE will be placed in the location described by STORAGE. FLAGS are scan-controlling flags which will be described later. STORAGE may be an address or a byte pointer. Use of the POINTR macro for defining the STORAGE field latter is described later. An example of SS usage is: SS MAP,MAPLOC,1,0 In this case, "1" is stored in MAPLOC if /MAP is seen on the command line. 2. SN - This is also for "TYPE 1" switches, in the cases where "NO" may be prefixed to a switch's defined name. The SN format is: SN NAME, STORAGE, FLAGS If the switch is encountered without the "NO" prefix, STORAGE takes the value "1." If the prefix "NO" is included, the value of STORAGE is then "0." STORAGE and FLAGS are as defined for SS. For example: SN INTERCHANGE,INTLOC,0 If /INTERCHANGE were define in this manner, then whenever /INTERCHANGE appeared on the command line, "1" would be stored in INTLOC (as would be the case with SS). However, if /NOINTERCHANGE were seen (which would not be legal using SS unless a seperate SS definition were made), then "0" would be put into INTLOC. 3. SL - This is used to define "TYPE 2" switches; those with one of a specific set of values. Associated with this macro are two others -- "KEYS" and "DM" -- which are called outside of SWTCHS. The SL format is one of: _______ SL NAME,STORAGE,TABLE,DEFAULT,FLAGS SL NAME,PROCESSOR,TABLE,DEFAULT,FLAGS STORAGE and FLAGS are as described for SS formats. PROCESSOR is used to specify a non-standard (i.e.: non-SIXBIT) input routine. This routine is then also responsible for storing the value as well. TABLE and DEFAULT are names associated with the KEYS and DM macros, respectively. DEFINING SWITCHES - THE "SWTCHS" MACRO Page 4-4 SWTCHS -- DEFINITION 11 Jun 79 The value placed in STORAGE will be the index into the table of values generated by KEYS. The format of the MACRO-10 labels generated are described below with the KEYS macro. An example of the SL format is: SL PARITY,PARLOC,PARY,PAR, This will be explained once the KEYS and DM macros are described below. 4. SP - This format is used with "TYPE 3" switches; those which take an arbitrary value, possibly less than a predefined maximum. The SP format is: SP NAME,STORAGE,PROCESSOR,DEFAULT,FLAGS STORAGE and FLAGS are as described above for SS. PROCESSOR is the address of the routine (either SCAN or User-supplied) to "pick-up" the value. This routine must leave the value in P3 if it wants SCAN to store it. The routine must return +1 for SCAN to store the value, or +2 for SCAN to not store the value. DEFAULT is as described for SL and may be null if no defaults (or maximum value) are desired. Examples, which will be explained in more detail later, are: SP PROTECTION,PROTEC,.OCTNW##,,0 SP PROTECTION,PROTEC,.OCTNW##,PRO,0 Each of these macros will uniquely identify and describe a switch in terms of the following characteristics: o Its name. o Where to place its value, if any (STORAGE). o How to read its value, if any (PROCESSOR). o What its legal values, if any, are (TABLE). o What its default and maximum values are, if any (DEFAULT). o The syntax in which it may or may not be used (FLAGS). 4.4 SCAN - CONTROLLING FLAGS: Each switch may have associated with it a combination of any of the following flags. These flags control how the switch may be used in a command line. DEFINING SWITCHES - THE "SWTCHS" MACRO Page 4-5 FS.??? Flags 11 Jun 79 o FS.VRQ - A value is required. o FS.NFS - The switch is never part of a file-specification. This switch should be meant as a global switch. o FS.LRG - The maximum and default values are 0 or greater than 2**17. If set, and the maximum value (in DM macro) is set, then 36-bit values for this switch are possible. Otherwise, only 18-bit values are legal. o FS.NCM - This switch is not a command switch (for VSCAN). o FS.NUE - No user exit on this switch. This means that /EXIT and ^Z do not cause an exit via MONRET, as they normally would. o FS.OBV - "OR bit values." This causes the value of the switch to be OR-ed with whatever existing value may already have been stored. Normally, the old value in the STORAGE location is overwritten. If this flag is set, then SCAN will LDB the existing value, IOR in the value of the switch as just parsed, and then DPB the value back to storage again. o FS.NOS - For the SN macro calls only: This switch may take "NO" as a prefix. CHAPTER 5 THE "DM" & "KEYS" MACROS 5.1 THE "DM" AND "KEYS" MACROS These two scanning macros are those related to: 1) default (and maximum) values, and 2) values for "TYPE 2" (SL) switches. These were mentioned above in the discussions of the SL and SP macros, and will now be described in detail. 5.2 DM -- MAXIMUM & DEFAULT VALUES In order to supply SCAN with a set of default and maximum values, the programmer supplies a 1-3 character name in the SL or SP macro, in the field DEFAULT. After SWTCHS has been defined, DM is called for each switch referencing it. A DM call has the form: DM (NAME,MAX,ABSENT,PRESENT) where: NAME is the 1-3 character name in the SL or SP PD.???? call. MAX is the maximum value. ABSENT is the default value if the switch is not encountered. PRESENT is the default value if the switch is present, but without a value. Each of these values is given a symbolic name, if the name already is defined, then the existing definition takes precedence over the DM argument. The three symbol names are of the respective forms: MX.NAME AD.NAME PD.NAME THE "DM" & "KEYS" MACROS Page 5-2 "DM" 11 Jun 79 An example will clarify this somewhat. Given the following: DEFINE SWTCHS < SP PROTECTION,PROTEC,.OCTNW##,PRO,0 > DM (PRO,777,057,155) This defines a switch "/PROTEC" whose maximum value is "777". If the switch is not in the command line, THE PROGRAM (not SCAN) may use the symbol AD.PRO for the value, which may be "057." If only "/PROTEC" is in the command string, then the value stored BY SCAN will be that of PD.PRO, in this case "155". 5.3 KEYS - KEYWORD DEFINITION "TYPE 2" (SL) switches always take a value from a predefined list of keywords. These keywords must be made from the SIXBIT characters, and are defined in the KEYS macro. The SL macro's TABLE field is then used as an argument to KEYS. KEYS is called after SWTCHS is defined (just like DM is). The call is of the form: KEYS (NAME,WORD1,WORD2,...WORDn) where: NAME is the 1-4 character name from the SL call. WORD1 is the first possible value. WORD2 is the second possible value. WORDn is the last possible value. The table of values is given the name NAME.T and is of length NAME.L. Each possible value's position in the table is the value of the symbol NAMExx, where "xx" are the first two characters of the value. This implies that if these SCAN constructed symbols are to be used by the program (not a necessity), then all keywords must be unique in their first two letters. Once again, an example is in order. Consider the following: DEFINE SWTCHS < SL PARITY,PARLOC,PARY,PAR > KEYS (PARY,EVEN,ODD,NONE) DM (PAR,PARY.L,PARYNO,PARYOD) THE "DM" & "KEYS" MACROS Page 5-3 "KEYS" 11 Jun 79 This generates a switch "PARITY" which takes as a "value" of of the following keywords: EVEN ODD NONE The default is "NONE" if only "/PARITY" is seen in the command without an explicit value. If the "/PARITY" switch is missing from the command line altogether, then the default value (not supplied by SCAN) is "ODD". The location "PARLOC" will receive the "value" of the switch, which is determined by the order in which the keywords are listed in the KEYS macro: EVEN=0 ODD =1 NONE=2 The maximum value for such a switch is the VALUE (not the contents) of the symbol "PARY.L" (ie, the 1-4 character designater used in KEYS, with ".L" catenated to the right). The elemets of the DM call specifying the defaults may be the symbolic names constructed by the KEYS call, or the actual values (as literals or non-SCAN defined symbols) values. The later is normally undesireable, as it makes changing a switch's characteristics difficult, but is used when the possible values (keywords) cannot be unique in their first two letters. If the non-unique values are not to also be default or maximum values, then this poses no real problem (since the assembler will simply use the latest definition it encounters). 5.4 CONSTRUCTED SYMBOLS - SUMMARY The previous sections has covered a number of symbols used by SCAN and its support code that are created by the SCAN macros themselves. To summarize them: o MX.??? - ??? is first arg to DM; this is created by DM as the maximum value for the switch o AD.??? - as above, but this is the absent default value for the support program to use if it sees fit. o PD.??? - as above, but this is the present default value for the switch, used by SCAN. o ????.L - ???? is the first agr to KEYS; this is created by KEYS, and has as its value the length of the table of keywords created by KEYS for this switch. o ????.T - as above, but this is the address of the table of keywords created by KEYS. THE "DM" & "KEYS" MACROS Page 5-4 CONSTRUCTED SYMBOLS - SUMMARY 11 Jun 79 o ????XX - as above, but this is the index into ????.T for the keyword whose first 2 characters are XX. o ?????N - ????? is the arg to DOSCAN (see previous chapter); this is the table of switch names. o ?????D - as above, this is the table of default values o ?????M - as above, this is the table of processor routines for the switch o ?????P - as above, this is the table of information for storing values. o ?????L - as above, this is the length of the other tables created by DOSCAN. CHAPTER 6 DEFINING THE "STORAGE" FIELD 6.1 DEFINING THE "STORAGE" FIELD All of the Switch macros have the field denoted "STORAGE." This field can have a number of formats, sometimes depending on the switch macro itself. Each of the formats will be described here. 6.2 THE POINTR MACRO One of the principle uses of STORAGE is as a byte pointer. Because of this, it is useful to first mention the use of the POINTR macro, since it is quite often the method used to define the STORAGE field. This macro is used to define a byte pointer, given: 1) the definition of the byte in terms of a mask, and 2) the storage location containing the byte. An example might prove useful here. Suppose a word "Y" contains a byte "X," consisting of bits 11 through 19. The POINTR usage would then be: X=177600000; mask for bits 11-19 POINTR (Y,X) If "X" were changed to be some other byte, either in "Y" or in some other location, the only change needed would be to its definition; references to it via the POINTR macro would not need changing DEFINING THE "STORAGE" FIELD Page 6-2 STORAGE FIELD 11 Jun 79 6.3 STORAGE FIELD There are five formats for STORAGE: 1. Word Address. (SN,SS,SP,SL) 2. Byte Address. (SN,SS,SP,SL) 3. Pointer to multiple-value storage. (SS,SP,SL) 4. Pointer to a file-specification storage area. (SP) 5. Address of a routine to process keyword. (SS,SP,SL) For all formats except #1, STORAGE is in the format of a PDP-10 byte pointer, although it may not always be used as such. The exact format definitions for the five types, in order are: 1. (LH)=0 (RH)=word address; value is MOVEMed into the storage address. 2. Standard byte pointer format; value is DPBed into the storage field. 3. The byte size field contains the number of words in the storage area, in the form (65-#words). (RH) points to the first word. 4. This is implicit: ".FILIN" will have been given as the PROCESSOR. (RH) is the address of the SCAN storage area (see later discussion of SCAN blocks). The length of this area (see later discussion of SCAN blocks) is the value of MX.NAME (from the DM call), which would otherwise have no meaning in this context. 5. Bits 0 through 11 in the "byte-pointer" being all 1s means that (RH) is the dispatch address of a processor which will "pick-up" the keyword.e a dummy symbol to be the required value, The easiest method of specifying such a value (getting both the size and position fields to be 1s) is to deine a dummy symbol to be the required value, and to then use that symbol in the STORAGE field. CHAPTER 7 DEFAULT VALUE HANDLING 7.1 INTRODUCTION In Chapter five ("THE 'DM' AND 'KEYS' MACROS"), the concept of specifying default values for the various switches was introduced. This chapter will cover the topic in more detail. Both SCAN-supplied and user-supplied default values will be covered. This is an especially important area, since it is something many believe should be provided by SCAN directly, that the user program should not be forced to become involved with. Because of this, it is also important to notice when the standard DEC SCAN is being referenced, and when the modified SCAN is being referenced. 7.2 FILE SPEC DEFAULTS The "DM" macro gives the user the ability to specify defaults, but the user program must also do the enforcement of some of those defaults. This is especially true of default values used when the switch is absent on the command line: SCAN will not go through the tables DOSCAN produces to see what switches were not specified, to be able to apply the appropriate default values. This entire area is one of the gaping holes in SCAN. 7.3 ABSENT DEFAULTS VS PRESENT DEFAULTS When the DM macro was introduced, the point was made that two default values are allowable. One is the default value to be used whenever the switch is absent from the command line (absent default), and the other is the default value to be used when the switch is given, but without an explicit value (present default). The arguments given to DM are in the following format: DM (ABBREV,MAX,ABSENT,PRESENT) where: DEFAULT VALUE HANDLING Page 7-2 ABSENT DEFAULTS VS PRESENT DEFAULTS 11 Jun 79 ABBREV is the 1-3 char name used in the SL or SP macro MAX is the maximum value PRESENT is the present default ABSENT is the absent default which generate the following symbols: MX.ABBREV (maximum value) PD.ABBREV (present default) AD.ABBREV (absent default) The generated symbols are always global, and will never re-define prior values. In other words, one can manually give values to some of the symbols to which DM normally assigns values, then call DM, without having the manually assigned values destroyed. This discussion leads one to expect that SCAN will perform the following functions when it is processing switches, or when it is applying default values (as in .APLST): o Range check values to be sure they are within 0<=MX.ABBREV o Give PD.ABBREV as the value when only /SWITCH is seen on the command line o Give AD.ABBREV as the value when /SWITCH is not seen on the command line at all However, only #1 and 2 are supported by SCAN at the present time. The generation of the AD.ABBREV symbols by DM is solely for use by the program which is using SCAN. Such support is planned for the next release of the modified DEC SCAN. The text below will outline the steps necessary to support this in a user program. The envisioned support within the modified SCAN will be in one of two forms: o Additional code to .APLST, so that all switches are defaulted whenever file specifications are. It is not clear that this is the way to go, since it is sometimes desirable to seperate the handling of file-spec and non-file-spec switches. This is the reason, for instence, for the existence of the FS.NFS (Not a File Switch) flag. o The inclusion of an additional routine, which will default the user switches. This is the preferable method, and (more than likely) the one which will be used. DEFAULT VALUE HANDLING Page 7-3 IMPLEMENTING SUPPORT OF ABSENT DEFAULTS 11 Jun 79 7.4 IMPLEMENTING SUPPORT OF ABSENT DEFAULTS This support consists of two distinct phases: assembly time generation of necessary table(s), and execution time code to scan the SWTCHS tables (as well as the added one(s)). There is no real problem or difficulty in either of these. 7.4.1 GENERATING TABLES AT COMPILE TIME This task will be performed immediately after the usual call to DOSCAN, and will generate a table using the SWTCHS macro. One must be careful to check to see if an absent default has indeed been given for each switch. Since the AD.ABBREV symbols are not used for any other purpose, the problem of determining whether or not a switch is eligible for defaulting is conveniently avoided. One possible macro might be the following, which generates the table "xxxxxA": DEFINE DODFLT(NAME),< DEFINE X($NAME,$PROC,$POINT,$DEFLT,$MAX,$FLAGS),< IFNDEF AD.'$DEFLT,< Z ;$NAME - NO ABSENT DEFAULT > IFDEF AD.'$DEFLT,< XWD 400000,AD.'$DEFLT ;$NAME > > ;END OF DUMMY MACRO "X" FOR SWTCHS NAME'A:: SWTCHS > ;END OF DODFLT MACRO The table "xxxxxA" is organized is such a manner that the sign bit indicates whether or not an absent default is applicable for this position's switch. When the sign bit is on, the right half of the same word is the absent default. If it is off, the rest of word is ignored. 7.4.2 EXECUTION TIME SUPPORT CODE The other task to be performed is the writing of code to be called at about the same time .APLST is called, but AFTER .OSDFS is called to apply .OSCAN's default values. The procedure to follow is simple. The following code gives a possible method. DEFAULT VALUE HANDLING Page 7-4 IMPLEMENTING SUPPORT OF ABSENT DEFAULTS 11 Jun 79 .APLDF::HRLZI T1,-xxxxxL LOOP: SKIPL T2,xxxxxA(T1) JRST ENDLUP MOVE T3,xxxxxP(T1) ;determine how to store value ;see the code around SWDPBE in SCAN ENDLUP: AOBJN T1,LOOP ;here with all absent defaults applied As this example indicates, some thought needs to be given at the point where the value in T2 is to be stored via the contents of T3. T3 can take various forms, although it is usually a standard byte pointer. The principle exception in this context is when the switch allows multiple arguments, and the STORAGE field in SWTCHS is used to specify the length and location of the area in which to store the values. The other exception is the case where a full word is to be stored for the value, in which case the left half of the "pointer" is zero, and the right half is the location to store the value. As the example also indicated, the method for properly handling this is in SCAN, in the routine SWDPBE, which is where all values for switches are stored. In this code, P2 is pointing to a 4 word table containing the addresses of the tables produced by DOSCAN. The offsets in this table are given the names: SWN==0 (xxxxxN) SWP==1 (xxxxxP) SWM==2 (xxxxxM) SWD==3 (xxxxxD) P1 is used to index into the "xxxxx?" tables to access the entries for the current command (ie: xxxxxN(P1) is the SIXBIT name of the current command, etc.). Knowing this, it is not difficult to follow the logic of the code. 7.5 SUMMARY The purpose of this chapter is to provide information on handling default values. The defaults catagorized as "present defaults," which are used whenever the switch is specified but its value is not, are already handled completely by SCAN. The other catagory - "absent defaults" - are not handled in any way be the current version of SCAN. The method in which this will be implemented in a future version of the modified DEC SCAN was presented. In addition, the general method for implementing this in a user program was given. CHAPTER 8 FILE-SPECIFICATION SCANNING 8.1 FILE-SPEC SCANNING An earlier section (The Command Scanners) gave a detailed description of what a file-specification is. What is of concern here is the use of .FILIN, the SCAN routine for inputting a file-spec. 8.2 SCAN BLOCKS 8.2.1 DEFINITION Crucial to this topic is a discussion of what is called a "Scan-Block," which is SCAN's internal (mostly) representation of the information relevant to the file-spec which was scanned. Appendix D ("SCNMAC") contains the exact definitions of the words and bits in a Scan-Block. Generally speaking, the information includes: o Device name. o Filename and its mask. o Extension and its mask. o PPN and its mask, along with any PATH information. o Selection criteria, based on switches encountered (dates, times, etc.). o Indications of the various switches' presence or absence. o Syntax representations. FILE-SPECIFICATION SCANNING Page 8-2 Scan Blocks 11 Jun 79 8.2.2 SCAN'S BUILT IN SWITCHES The switches referred to were mentioned earlier as "Internal SCAN Switches." These are mostly used to specify file selection criteria, especially for use by WILD (see Appendix B). The exact definitions are included in Appendix E as one of the examples of Switch definitions. Summarized, they are: /ABEFORE /ASINCE - specify access-date-time criteria /BEFORE /SINCE - specify creation-date-time criteria /ERNONE /OKNONE - specify if no file-match is an error /ERPROTECTION /OKPROTECTION - specify if access-protection failure is an error /ERSUPERSEDE /OKSUPERSEDE - specify if it is an error to overwrite an existing file /ESTIMATE - specify an estimated file size /EXIT - go to monitor /HELP - type a help message /NOOPTION - /OPTION - control the use of options file (see "OSCAN") /PHYSICAL - set the "physical only" bit on all OPENs. /PROTECTION - specify the protection of a file /VERSION - specify the version number of a file /RUN - /RUNCORE - /RUNOFFSET - control the running of a new program when done with this one (see "Routine Call Definitions.") 8.2.3 SYNTAX REPRESENTATIONS "Syntax Representations" refer to bits, used primarily by WILD, indicating what special constructs were seen. These are made up of usages of what SCAN terms "Guide Words," which are in a sense pseudo-characters. The legal Guide Words, and their pseudo-character values, are: 'AND' 4000 'INPUT' 4005 'OR' 4001 'OUTPUT' 4006 'NOT' 4002 'SOURCE' 4007 'FROM' 4004 'LIST' 4010 'TO' 4003 'OBJECT' 4011 These are used to express inter-filename relationships in a command string, along with the concatenation operator -- the plus sign. Refer to "INPUT ROUTINES - CHARACTER" in Chapter 2, and to Appendix D - "SCNMAC." FILE-SPECIFICATION SCANNING Page 8-3 Built-in Switches; Guide Words 11 Jun 79 8.2.4 SCAN BLOCKS: SUMMARY So much for Scan-Blocks. It is important to realize that they exist, especially if any of the switches listed are of use to the program, or if the user is interfacing with WILD (which requires Scan-Blocks for input). The .STOPB routine (see "Routine Definitions") is used to convert these blocks to OPEN and LOOKUP/ENTER blocks. 8.3 F.EZER & P.EZER The Scan-Block used by SCAN is located at the global symbol "F.ZER", and extends to "F.EZER". Associated with this is a "default region," into which the user places his default values, if any, before calling SCAN. The definitions of the offsets into those blocks are in SCNMAC, a listing of which is included in the appendices. These symbols have names of the format ".FX???". This area extends from "P.ZER" to ".EZER", and should be zeroed if no defaults exist. To have these defaults applied (after SCAN has returned), one issues the call: PUSHJ P,.APLST## to apply what SCAN calls "sticky defaults." This is covered future in a following Chapter, "DEFAULT AND MAXIMUM VALUE HANDLING." Once the Scan block at F.ZER has had the user's defaults applied, then it remains to: 1) apply SCAN's defaults, and 2) to move it to the user's area. This is done in the following manner: MOVEI T1, address ;user's Scan-Block address MOVEI T2, length ;length of same PUSHJ P,.GTSPC## After this, the area of F.ZER can then be reused for more file-specs. 8.4 .STOPB Once the scan blocks were created by SCAN, and possibly processed by WILD (to resolve wild card expressions), the problem remains of doing something with them. The TOPS-10 monitor will certainly not accept them to specify file operations. What needs to be done is to covert from the SCAN block format needed during scanning, to the standard OPEN and LOOKUP/ENTER block format needed during processing. The routine FILE-SPECIFICATION SCANNING Page 8-4 .STOPB 11 Jun 79 whhich performs this task is ".STOPB" (Scan To OPen lookup Block). The call on .STOPB is of the format: T1/ SCAN-block-len,,SCAN-block-address T2/ 0,,OPEN-block-address T3/ LOOKUP-block-len,,LOOKUP-block-address T4/ 0,,PATH-block-address (9 words) PUSHJ P,.STOPB## -error- (wildcards not yet resolved) -ok- SCAN block is translated 8.5 USING .FILIN Now that all else has been taken care of, the actual scanning of file-specifications is simple to explain. The routine responsible for this is .FILIN, which is called in the following manner: PUSHJ P,.FILIN## and returns with T1 containing: 0 if null expression -1 if file spec typed 1 if only switches seen FILE-SPECIFICATION SCANNING Page 8-5 SUMMARY OF FILE SPEC SCANNING 11 Jun 79 8.6 SUMMARY OF FILE SPEC SCANNING Summarizing the file-spec scanning process, we have seen that the following sequence is the general method used: o Setup defaults in P.ZER area o Call .FILIN o Call .APLST o Call .GTSPC o Call WILD o Call .STOPB o Process LOOKUP/ENTER and OPEN blocks CHAPTER 9 .ISCAN - SCANNER INITIALIZAITON 9.1 ISCAN - SCANNER INITIALIZATION Before calling one of the command scanners (or any input routine), it is necessary to give SCAN a set of parameters and other information describing how the user intends to go about doing things. In "ROUTINE CALL DEFINITIONS" a skeleton format of an ISCAN call was given, which is sufficient for a job interested in doing only simple TTCALL I/O, without any frills. Here will be described in detail all of the various options available via ISCAN. 9.2 INITIALIZATION CONCERNS A number of procedures are followed by SCAN during its internal initialization, via ISCAN. These tend to revolve around the one-time setting up of storage, for later use. The specific functions, which are covered in detail in the following paragraphs, include: Rescanning the command line which initiated the program being run, determining how the program was entered (CCL vs normal), what I/O routines to use, what indirect files (if any) to use, etc. Usually, many of these are not of great concern, and are either omitted or defaulted to. 9.3 RESCANNING THE COMMAND LINE While ISCAN is not a scanner, it will sometimes process part of the command line. This occurs for programs which accept input on the same line as the monitor line which activated them. In these cases, ISCAN is given a list of the valid monitor level commands to look for. It then RESCANS the command line, and positions the input routines to the end of that command. On return, T1 indicates whether a command was actually seen or not (see call description below). If no table of commands is .ISCAN - SCANNER INITIALIZAITON Page 9-2 RESCANNING THE COMMAND LINE 11 Jun 79 supplied, ISCAN will not do a RESCAN. One of the more common usages of this feature is in the writing of a program which is to be invoked by a spsecific monitor command. When commands are added to the monitor, in the module COMCON, their dispatch address in COMTAB can be to a routine which runs a program of the same name,, but starts it at the CCL entry point (see the following paragraphs). This makes it possible for a program MUMBLE to be invoked by commands of the format: .MUMBLE /switch:value /switch:value ... In this case, .ISCAN would be told to perform the rescan of the command line, in order to pick up the switches. This is the process used by programs such as DIRECT. 9.4 CCL MODE When a program is in what is usually termed "CCL mode," it was started with an offset other than 0 added to its start address. In these cases, input usually comes to SCAN from a "CCL file." In this case, ISCAN must be told: 1) the 3-character CCL name, and 2) the value of the starting offset. If not in CCL mode, then ISCAN is given a zero word. This feature is most useful for programs (such as DIRECT) which can be monitor commands. 9.5 I/O ROUTINES As was stated in the Introduction, SCAN defaults to TTCALL input and output. If the user wishes, the address(es) of special routine(s) for input or output may be given to SCAN. Input routines must leave their character in P4; output routines take theirs from T1. Neither may destroy any other accumulators. If the program knows ahead of time that indirect file input will be used, and the name of the file, then a Scan-Block form of the specification is passed to ISCAN. The .FXDEV word must be non-zero for ISCAN to honor it. .ISCAN - SCANNER INITIALIZAITON Page 9-3 PROGRAM TERMINATION 11 Jun 79 9.6 PROGRAM TERMINATION Sometimes, it is useful for a program to always be given control whenever SCAN would otherwise return to the monitor. In these cases, a "MONRET" ("MONitor RETurn") address is given to ISCAN. In the absence of this, SCAN will simply issue an EXIT UUO. 9.7 COMMAND PROMPTING Along the same lines, some programs have their own prompting schemes, and must supply ISCAN with the appropriate address, which will later be PUSHJed to. When it is called, T1 will be set up as follows: (RH) the normal prompt character: "*" for first lines "#" for continuation lines (LH) 0 for first lines; -1 for continuation lines A "continuation line" is one following a line which ended with a dash, which is SCAN's continuation character. 9.8 FLAGS This word specifies any special handling required. The possible flags are described below, and are also listed in the appendices for SCNMAC and $SCNDC. FS.ICL - If set, whis will cause SCAN to "Ignore Command Line" handling. In other words, if the command line is not in a format SCAN understands (such as LOGIN), but SCAN is used to handle parts of it, the setting of this bit causes SCAN to ignore the fact that it is actually a command line. The RESCAN will still be done, however. 9.9 CALLING .ISCAN This brings us now to an exact description, which should make sense in the light of the preceeding paragraphs. The calling format for .ISCAN is: .ISCAN - SCANNER INITIALIZAITON Page 9-4 Argument Block Definition 11 Jun 79 MOVE T1, [length,,argblock-address]. PUSHJ P, .ISCAN## -return- T1 = index into table of monitor commands, or -1 if none found The argument block at "argblock-address" has the following format: BLOCK: BLOCK + 0 = 0 or IOWD length, monitor-commands + 1 = (RH) 0 or address of starting offset (LH) 0 or SIXBIT CCL name + 2 = (RH) 0 or address of output routine (LH) 0 or address of input routine + 3 = 0 or XWD length, indirect-Scan-Block + 4 = (RH) 0 or address of MONRET routine (LH) 0 or address of PROMPT routine + 5 = FLAGS LENGTH==.-BLOCK CHAPTER 10 .TSCAN - THE TRADITIONAL SCANNER 10.1 .TSCAN - THE TRADITIONAL SCANNER The most common command formats are those with: 1) one output file-spec; 2) either one or more input-specs, or else no input spec at all; and 3) command switches somewhere on the line. This is the type of command line which TSCAN processes. As well as needing to know where DOSCAN's tables are, a few other issues come into play. 10.2 /HELP One of the built-in "Internal Switches" listed above (see "File-Spec Scanning") was /HELP. It now becomes necessary to tell SCAN how to find the "HELP file" to be typed. Four types of help are possible. o None o Type a preset string o Call a prenamed routine o Call HELPER It is necessary for the caller to tell TSCAN which of the above to use. 10.3 POST PROCESSING OF SWITCHES As a command line is processed, it is often desirable for the user to be given a chance to clear out various storage areas, before a new command line is processed. This is accomplished by passing to TSCAN the address of a routine to .TSCAN - THE TRADITIONAL SCANNER Page 10-2 POST PROCESSING OF SWITCHES 11 Jun 79 PUSHJ to at the end of each line. Along the same lines, there is often data to be cleared or reset as each file-spec is processed. SCAN will zero its F.ZER area, but the user may have other locations to worry about. It may also want to change the P.ZER default area. To do so, the user provides TSCAN with an address to PUSHJ to. 10.4 SCAN BLOCK ALLOCATION In the chapter on "FILE-SPEC SCANNING," it was indicated that SCAN assembles its data within its own core (F.ZER) since the command line may very well contain many file-specs. This means that some method must exist for moving the Scan-Blocks to a "safer" area. Since the input and output streams may require different handling, the user provides TSCAN with the addresses of two routines which will allocate space for a Scan-Block. These routines return the following information to SCAN: T1 = address of Scan-Block area T2 = length of Scan-Block area The P.ZER area, as was mentioned earlier, contains the default file-spec values. Often, information in one file-spec on a command line is the default for a later file-spec on that line. Because of this, SCAN will "memorize" this information by copying the F.ZER information into the P.ZER area. If the user would like control after this is done, an address to be PUSHJed to is passed to TSCAN. Also, whenever SCAN applies the P.ZER defaults, the user may want to be called. This is also done by giving TSCAN the address to be PUSHJed to. Finally, as the SCAN of a line is commenced, the P.ZER area is cleared. The user will then be called, if it had previously given TSCAN such an address. 10.5 STICKY DEFAULTS A "sticky" default is what SCAN terms general globals defaults for file specifications. These are applied by SCAN when .APLST is called. When .TSCAN is called, the user has the option of specifying a special routine to call whenever SCAN is going to apply sticky defaults. The left half of word number 6 contains the addresses of the routine to memorize sticky defaults for all files, and the address of the routine to apply these defaults to all succeeding file specifications: XWD MEMORIZE-ADDRESS, APPLY-DEFAULTS-ADDRESS The other routine which may be specified it the routine to clear .TSCAN - THE TRADITIONAL SCANNER Page 10-3 STICKY DEFAULTS 11 Jun 79 any sticky defaults at the end of a file-spec scan. This is given in the left half of word number 7: XWD CLEAR-DEFAULT-ADDRESS, flags If the user program has not sticky switches of its own, then these fields should be left zero. Otherwise, whenever SCAN does its own sticky default handling, it will also can on the user's routine to process the user's sticky defaults at the same time. 10.6 SCAN CONTROLLING FLAGS Although there is normally only one output file-spec, sometimes multiple output specs are quite valid. Also, many programs do not care if a switch associated with one side of the "=" actually appeared on the other side. To allow either (or both) of these special cases, flags are passed to TSCAN which control the scanning process. These flags are also listed in Appendix D ("SCNMAC"): FS.MOT - Multiple output file specifications allowed. FS.MIO - Input and Output specifications may be mixed on the command line, regardless of their relationships position-wise to the "=" character. 10.7 SWITCH PROCESSING Finally, it is sometimes the case that the user wants to be called whenever a switch value is to be stored, no matter how it was defined in SWTCHS. To do this, TSCAN is pointed at the routine to do this. When this routine is called, the following are set up: T1 = switch-value T2 = pointer into switch tables The routine, after doing what it may, non-skip returns if SCAN should not store the value, or skip-returns if SCAN should store it. In either case, all accumulators are to be left intact. .TSCAN - THE TRADITIONAL SCANNER Page 10-4 CALLING .TSCAN 11 Jun 79 10.8 CALLING .TSCAN To call TSCAN, one first sets up an argument block of the following form: BLOCK + 0 = IOWD xxxxxL, xxxxxN + 1 = XWD xxxxxD, xxxxxM + 2 = XWD 0, xxxxxP + 3 = XWD help-type, help-address ; help-type = 0 if none ; = 1 if string ; = 2 if subroutine ;if word = -1, use name in ;system table, and call HELPER ;if (LH) is greater than 77, ;but word is not -1, then word ;is the SIXBIT name to give HELPER. + 4 = (LH) 0 or routine to clear all answers (RH) 0 or routine to clear file answers + 5 = (LH) routine to allocate input file area (RH) routine to allocate output file area + 6 = (LH) 0 or routine to memorize defaults (RH) 0 or routine to apply defaults + 7 = (LH) 0 or routine to clear defaults (RH) flags: 1B18 multiple output specs are legal 1B19 switches may go anywhere on the line + 10 = (LH) 0 (reserved for future) (RH) 0 or routine to store switch values When "0" is given as an argument, then that option will not be used. The "xxxxx" fields are from the DOSCAN argument. To call TSCAN: MOVE T1, [LENGTH,, BLOCK] PUSHJ P, .TSCAN## -return- at end of line after something was typed 10.9 STORAGE INITIALIZATION When TSCAN returns, all of the switches and file-specs have been processed, and all values stored. All switch value cells should have an initial value of -1. This is because SCAN will detect attempts to give a switch more than one value on the same line. Unless a user routine intervened, the first value would be lost. If the user wants this -- multiple values -- then the .TSCAN - THE TRADITIONAL SCANNER Page 10-5 STORAGE INITIALIZATION 11 Jun 79 switch must have a routine to do the storing itself. In any event, -1 was chosen as an unlikely switch value, and therefore a reasonable initial value. N.B.: Read Appendix "A" ("Notes on Using SCAN") 10.10 SUMMARY This chapter has presented the use of SCAN's most often used scanner - .TSCAN. Much of what has been covered is relevant not only to .TSCAN, however, but also to the other scanners being discussed in the following chapters. CHAPTER 11 OSCAN - THE OPTIONS FILE SCANNER 11.1 OSCAN - THE OPTIONS FILE SCANNER It is often the case that a particular application has a set of defaults that change somewhat from user to user. In this case, it is not possible to define the defaults via DM, since each user has his own, but they all run the same program. A solution which is particularly useful is called an "Options File." This is a single file, under the user's PPN, which contains the default switch settings for that user. Since this is feasible for many programs, all use the same file, but preface their particular lines of defaults with their names. Finally, it is possible for one program to have multiple, named, sets of defaults. 11.2 FORMAT OF THE OPTIONS FILE This "Options File" is the file DSK:SWITCH.INI, on the user's PPN. Entries in SWITCH.INI are of the form: Program /SWITCH/SWITCH... or PROGRAM:OPTION /SWITCH/SWITCH where: PROGRAM is the program name. OPTION is the name of the set of defaults. This used as the value to the /OPTION: switch in the command line. /SWITCH are the switches and their values. Only switches are valid in the options file -- file-specs cannot be included. OSCAN - THE OPTIONS FILE SCANNER Page 11-2 FORMAT OF THE OPTIONS FILE 11 Jun 79 11.2.1 Options List Only one calling parameter for OSCAN has not been covered already under "TSCAN" -- the name(s) of options to select. The program passes to OSCAN: 1) the pointer to a list of options to be selected, or 2) the name to be selected, or 3) 0 to imply the use of the program's name as the object of the selection. 11.2.2 Argument Block The argument block for OSCAN closely resembles that for TSCAN: BLOCK + 0 = IOWD xxxxxL, xxxxxN + 1 = XWD xxxxxD, xxxxxM + 2 = XWD 0, xxxxxP + 3 = HELP WORD + 4 = OPTIONS WORD: SIXBIT/NAME/ or Z or XWD LEN, LIST LENGTH==.-BLOCK LIST: SIXBIT/OPT1/ SIXBIT/OPT2/ . . . SIXBIT/OPTn/ LEN==.-LIST 11.2.3 CALLING .OSCAN To call OSCAN: MOVE T1, [LENGTH,,BLOCK] PUSHJ P, .OSCAN## OSCAN - THE OPTIONS FILE SCANNER Page 11-3 APPLYING DEFAULTS FOR .OSCAN 11 Jun 79 11.3 APPLYING DEFAULTS FOR .OSCAN After OSCAN returns, it is usually necessary to have the switches applied to any file-specs which were scanned off by TSCAN (or VSCAN). This is the purpose of .OSDFS, which is called in the following manner: MOVEI T1, location of Scan-Block MOVEI T2, length of Scan-Block PUSHJ P, .OSDFS## Once this has been done for any or all file-specs desired, the scanning process is complete. CHAPTER 12 .VSCAN - THE VERB FORM SCANNER 12.1 VSCAN - THE VERB FORM SCANNER In some applications, it is desirable to have all command lines begin with a keyword which indicates some function or operation to be performed. This is then followed on succeeding lines by related commands and file-specs. In this case, the function-word is referred to as a "verb," and the associated scanner is therefore a "verb form scanner," or ".VSCAN." Normally, when VSCAN is used, the user enters his switches one-per-line. Although SCAN views these as switches no differently than it does with TSCAN, it appears to the user that he is actually inputting commands; this is especially true since it is not necessary with VSCAN to include the slash that normally indicates a switch. In some applications, this lends itself very well to user oriented dialogues. While it would be possible for switches to appear on the line with the "verbs," this would tend to contradict the philosophy behind using VSCAN in the first place. 12.2 USING .VSCAN From the programmer's point of view, there is really nothing new for VSCAN that was not also necessary for TSCAN. The only new calling values in the argument block are the addresses and lengths of the default and permanent switch areas for file-specs (a la P.ZER and F.ZER, respectively). .VSCAN - THE VERB FORM SCANNER Page 12-2 USING .VSCAN 11 Jun 79 12.2.1 Argument Block Format The exact argument block format for VSCAN is: BLOCK + 0 = IOWD xxxxxL, xxxxxN + 1 = XWD xxxxxD, xxxxxM + 2 = XWD 0, xxxxxP + 3 = HELP WORD + 4 = (LH) length of file-spec areas (RH) address of permanent area + 5 = (LH) 0 (reserved for future) (RH) address of default area + 6 = OPTION NAME, or 0 (to use program name) LENGTH==.-BLOCK 12.2.2 CALLING .VSCAN The VSCAN call is: MOVE T1, [LENGTH,,BLOCK] PUSHJ P, .VSCAN## CHAPTER 13 .PSCAN - THE PARTIAL SCANNER .PSCAN - THE PARTIAL SCANNER Page 13-2 PSCAN & QSCAN - INTRODUCTION 11 Jun 79 13.1 PSCAN & QSCAN - INTRODUCTION One of the drawbacks, in some applications, of having an all purpose scanner such as TSCAN is that it does not allow any flexability in the format of the command lines. ALL commands must conform to the sytax used by SCAN. Usually, this presents no problem, since SCAN's syntax is in itself quite flexable. However, when it is necessary for the format of a command line to be somewhat different, then another scanner is required. This is the usefulness of the so called "Partial Scanner." This scanner tends to operate as a co-operative effort between the user program and SCAN. Part of the command line is processed by the program, and the remainder is processed by .PSCAN or .QSCAN. The process is simple. Either .PSCAN or .QSCAN is called to initialize the scanning process, then the user program processes the command line to whatever extent it desires. The routine which is normally called to handle SCAN's side of the command line handling is ".FILIN", which will pick up any file specifications, as well as whatever switches it encounters. This makes for a relatively simple scanning process: o Call .ISCAN to initialize everything o CALL .PSCAN to initialize for partial scanning (or .QSCAN) o Call whatever input routines are appropriate for the user's portion of the command line (.SWDEC, .SWSIX, etc.). o Call .FILIN to handle the rest of the command line o Process the SCAN-blocks, if any, which were generated by .FILIN. o Process the data returned by the switches scanned off by .FILIN 13.2 PSCAN VS QSCAN Throughout the discussion so far, two routines have been referred to as the partial scanners -- .PSCAN & .QSCAN. These operate in identical fashions, so far as use within a program is concerned. Their only difference lies in their scope. .PSCAN sets up partial scanning on a global basis, which affects as input lines. .QSCAN, on the other hand, affects only the current line. Other than this, they are used identically. .PSCAN - THE PARTIAL SCANNER Page 13-3 SUMMARY 11 Jun 79 13.3 SUMMARY The purpose of this chapter has been to introduce the concept of a partial scanner, which is sometimes very well suited for a particular application. In addition, instruction on using the two routines supplied by SCAN -- .PSCAN and .QSCAN -- to handle this type of scanning has been given. An excellant example on the use of partial scanners is the Digital CUSP CREDIR. A part of this program, in fact, is included in a later chapter as a guide in writing programs which interface with SCAN. CHAPTER 14 ACCESSING SCAN 14.1 ACCESSING SCAN 14.1.1 ASSEMBLY TIME FILES All of the MACROS, symbols and routine names referenced in this document are a part of SCAN and its associated files. The following files are those used in the SCAN "system." o UUOSYM.UNV MACTEN.UNV These define symbols used in the DEC reference manuals to describe UUOs and their calling formats. Also defined are useful macros, such as: POINTR, TXxx, MOVx, etc. These are accessed by the MACRO-10 statement: SEARCH UUOSYM,MACTEN o SCNMAC.UNV $SCNDC.UNV These files define macros and symbol definitions for SCAN. SL, SN, SP, SS, DM, KEYS, DOSCAN, etc, are all defined here SCNMAC and $SCNDC are accessed by the MACRO-10 statement: SEARCH SCNMAC,$SCNDC ACCESSING SCAN Page 14-2 ACCESSING SCAN 11 Jun 79 14.1.2 LINK-TIME FILES o SCAN.REL This is SCAN itself. Contains all code described herein, including $SCNDC. SCAN.REL should be loaded in library search mode. o HELPER.REL This is a module for the /HELP switch, and is loaded as any other file. 14.1.3 SOURCE FILES Sources to SCAN, SCNMAC, HELPER, MACTEN and UUOSYM are currently distributed on the CUSP release tapes as: SCAN.MAC SCNMAC.MAC HELPER.MAC MACTEN.MAC UUOSYM.MAC Parts of $SCNDC and SCNMAC have been included as appendices D and E respectively. The universal (.UNV) files for SCNMAC, $SCNDC, MACTEN and UUOSYM are normally kept on ersatz device "UNV:." The .REL files for SCAN, WILD, and HELPER are usually on device "REL:." 14.1.4 SUMMARY In summary, the following would normally be seen at the start of a program using SCAN: SEARCH COLS,C,SCNMAC,$SCNDC .REQUEST REL:SCAN .REQUEST REL:WILD .REQUEST REL:HELPER ACCESSING SCAN Page 14-3 SEGMENT ALLOCATION 11 Jun 79 14.2 SEGMENT ALLOCATION All of the code in SCAN is high segment; no .LOW file will be generated unless the user's program needs one. As a general rule, when using the standard DEC SCAN, if any calling routine is in the low-segment, then the linked files should not be protected as "execute only" (i.e.: 166). This is because SCAN does not include PORTAL instructions at its entry points. All of the entries in the modified version of SCAN, however, do contain PORTALs, and may be entered from low segments as an execute only high segment. CHAPTER 15 EXAMPLE OF USING SCAN EXAMPLE OF USING SCAN Page 15-2 INTRODUCTION 11 Jun 79 15.1 INTRODUCTION This chapter will present two complete examples of using SCAN for command scanning. It will use much of the material presented in previous chapters. The basic purpose in this is to unite the concepts and routine descriptions presented into a cohesive structure. The first example chosen is from CREDIR, a Digital CUSP used to create directories on TOPS-10 systems. The scanners used are the Partial Mode scanners, .PSCAN & .QSCAN. A second example, from a private program, will present a use of .TSCAN, which is by far the most popular scanner. By examining closely both examples, the reader should gain a detailed understanding of the use of SCAN. EXAMPLE OF USING SCAN Page 15-3 EXAMPLE: CREDIR (.PSCAN/.OSCAN) 11 Jun 79 TITLE CREDIR -- ROUTINE TO CREATE A DIRECTORY %2(103) SEARCH C,SCNMAC ;SET FOR UNIVERSALS SUBTTL INITIALIZATION CREDIR: TDZA T1,T1 ;NOT CCL START MOVEI T1,1 ;CCL START MOVEM T1,OFFSET ;STORE IT RESET ;RESET ANY EXTERNAL I/O ;NEXT GO INITIALIZE THE COMMAND SCANNER. IN ;PARTICULAR, LOOK FOR A COMMAND ON THE SAME LINE OR A CCL ;FILE FULL OF COMMANDS. MOVE T1,[ 2,,[IOWD 1,['CREDIR'] OFFSET,,'CRR']] PUSHJ P,.ISCAN## ;INITIALIZE COMMAND SCANNER SUBTTL MAIN LOOP ;EACH PASS, WHETHER SUCCESSFUL OR NOT, ALWAYS ;ENDS BY RETURNING TO THE LABEL MAINLP. THIS CAUSES THE ;PROGRAM TO START OVER AGAIN. IT CAN BE EXITED BY THE ;USER BY EITHER A ^C OR A ^Z. IF THE PROGRAM HAD BEEN ;INVOKED BY A COMMAND OR CCL CALL, THEN SCAN WILL ;SIMULATE THE ^Z WHEN APPROPRIATE TO EXIT. MAINLP: PUSHJ P,.RUNCM## ;HANDLE /RUN IF SET MOVE T1,[ 4,,[IOWD SWTL,SWTN SWTD,,SWTM 0,,SWTP -1 ]] PUSHJ P,.PSCAN## ;INVOKE P-MODE SCANNER OUTSTR [ASCIZ \Create directory: \] CAMG P4,[.CHEOF] ;SEE IF EOF JRST [PUSHJ P,.ALDON## ;YES--HANDLE NORMAL CASES CAMG P4,[.CHEOF] ;THEN CHECK AGAIN PUSHJ P,.MNRET## ;YES--RETURN TO MONITOR JRST MAINLP] ;THEN START OVER AGAIN EXAMPLE OF USING SCAN Page 15-4 EXAMPLE: CREDIR (.PSCAN/.OSCAN) 11 Jun 79 ;HAVING INITIALIZED THE COMMAND SCAN FOR THIS LINE, ;NOW GET A FILE SPECIFICATION, WHICH MUST INCLUDE ;THE STRUCTURE AND DIRECTORY AND EXCLUDE THE FILE NAME AND ;EXTENSION. PUSHJ P,.FILIN## ;GET FILE SPEC JUMPN T1,GETOPT ;JUMP IF SOMETHING INPUT ;HERE IF NOTHING TYPED BEFORE THE SEPARATOR. THE ONLY ;LEGAL CASES ARE /RUN AND INDIRECT. CAIN P4,"@" ;SEE IF INDIRECT PUSHJ P,.GTIND## ;YES--SETUP INDIRECT JUMPLE P4,MAINLP ;IF END OF LINE, GO DO MORE PJRST E.ILSC## ;OTHERWISE, GIVE ERROR ;NOW CHECK OPTION FILE TO SEE IF ANY DEFAULT SWITCHES. GETOPT: JUMPG P4,E.INCL## ;ERROR IF MORE ON LINE MOVEI T1,SPEC ;POINT TO SPEC AREA MOVEI T2,.FXLEN ; .. PUSHJ P,.GTSPC## ;COPY TO US MOVE T1,[ 4,,[IOWD SWTL,SWTN SWTD,,SWTM 0,,SWTP -1 ]] PUSHJ P,.OSCAN## ;HANDLE OPTION FILE JRST GOTSOM ;THEN PROCEED EXAMPLE OF USING SCAN Page 15-5 EXAMPLE: CREDIR (.PSCAN/.OSCAN) 11 Jun 79 ;DEFINE SWITCH TABLE DEFINE SWTCHS,< SP IN,QTAIN,.SWDEC##,QTA,FS.LRG SP NAME,SPLNAM,SIXQWW,NUL, SP OUT,QTAOUT,.SWDEC##,QTA,FS.LRG > DM NUL,1,0,0 DM QTA,.INFIN,.INFIN,.INFIN DOSCAN (SWT) ;ROUTINE TO INPUT ONE WORD IN SIXBIT POSSIBLY QUOTED SIXQWW: PUSHJ P,.SIXQW## ;GET STRING MOVE P3,.NMUL## ;GET FIRST WORD POPJ P, ;RETURN RESULT GOTSOM: SKIPE T1,FLDIAL ;SEE IF DIALOG SKIPL SPEC+.FXMOD ;SEE IF DEVICE THIS TIME SKIPA ;OK--DO NOTHING MOVEM T1,SPEC+.FXDEV ;LAZY--DEFAULT HIS DEVICE ;fall into other code not of interest in ;this example case. EXAMPLE OF USING SCAN Page 15-6 EXAMPLE: CREDIR (.PSCAN/.OSCAN) 11 Jun 79 GOTDIR: MOVX T1,FX.PRO ;GET PROTECTION MASK TDNN T1,SPEC+.FXMOM ;SEE IF USER SET IT SKIPN FLDIAL ;OR NOT IN DIALOG JRST GOTDR1 ;ALL OK--PROCEED MOVE T1,[ 4,,[0 0 0 -1 ]] PUSHJ P,.QSCAN## ;INVOKE P-MODE SCANNER OUTSTR [ASCIZ \Protection: \] PUSHJ P,.OCTNW## ;GET OCTAL VALUE DPB P3,[POINTR (SPEC+.FXMOD,FX.PRO)] JUMPG P4,E.INCL## ;ERROR IF MORE ON LINE GOTDR1: SKIPGE SPLNAM ;SEE IF /NAME SKIPN FLDIAL ;NO--SEE IF DIALOGUE JRST GOTDR2 ;YES--PROCEED MOVE T1,[ 4,,[0 0 0 -1 ]] PUSHJ P,.QSCAN## ;INVOKE P-MODE SCANNER OUTSTR [ASCIZ \Name: \] PUSHJ P,SIXQWW ;GET SIXBIT NAME JUMPG P4,E.INCL## ;ERROR IF THAT'S NOT ALL MOVEM P3,SPLNAM ;SET NAME GOTDR2: MOVS T2,SPEC+.FXEXT ;GET EXTENSION TLC T1,-1 ;MASK SHOULD BE -1 CAIE T1,'UFD' ;SEE IF UFD CAIN T1,'SFD' ; OR SFD SETZB T1,SPEC+.FXEXT ;YES--CLEAR OUT SKIPN SPEC+.FXNAM ;SEE IF FILE NAME SKIPE SPEC+.FXEXT ; OR EXTENSION JRST E$$FNI ;YES--FILE NAME ILLEGAL MOVEI T1,SPEC ;POINT TO SCANNED SPEC MOVEI T2,OPNBLK ;POINT TO AN OPEN BLOCK MOVEI T3,ENTBLK ;POINT TO AN ENTER BLOCK PUSHJ P,.STOPN## ;CONVERT SCAN'S SPEC JRST E$$WCI ;WILD CARDS ARE ILLEGAL JRST DEVOK ;PROCEED ;fall into code which does actual processing of directories, ;etc., which is of no concern here as a SCAN example. EXAMPLE OF USING SCAN Page 15-7 TSCAN Example 11 Jun 79 The next example, of the use of TSCAN, is from a program written to count the number of form-feeds in an arbitrary set of files. No switches are used, but a dummy SWTCHS definition is used to keep TSCAN happy. The inclusion of additional switches would be trivial. The important parts to watch are the interfacing with TSCAN, and the processing of the SCAN blocks. The actual use of the converted OPEN and LOOKUP/ENTER blocks is left out. EXAMPLE OF USING SCAN Page 15-8 TSCAN Example 11 Jun 79 TITLE FINDFF - FIND NUMBER OF FORM-FEEDS IN GROUP OF FILES .REQUEST SCAN .REQUEST WILD SEARCH UUOSYM,SCNMAC,$SCNDC ;************************************************* ; INITIALIZATION ROUTINE ;************************************************* FINDFF: RESET MOVE P,[IOWD PDLSIZ,PDL] MOVEI T1,1 MOVEM T1,TOTFF ;STARTS AT 1 PAGE (NO INITIAL FF) MOVE T1,[ISCLEN,,ISCBLK] PUSHJ P,.ISCAN## ;INITIALIZE SCAN PUSHJ P,.TCRLF## SETZM WILDSW ;INDICATE NO WILD SPEC IN FORCE ;************************************************* ; ROUTINE TO GET NEXT FILE SPECIFICATION FROM SCAN ;************************************************* GETNAM: SKIPE WILDSW ;SKIP IF NO WILD SPEC IN FORCE JRST CALWLD ;JUMP IF A WILD SPEC IS CURRENT GETSPC: MOVE T1,[XWD P.ZER##,P.ZER##+1] SETZM P.ZER## BLT T1,P.EZER## ;INIT DEFAULT REGION FOR .TSCAN MOVE T1,[TSCLEN,,TSCBLK];ARGUMENT BLOCK PUSHJ P,.TSCAN## ;GET NEXT FILE SPECIFICATION ;FROM INPUT SOURCE SETOM WILDSW ;REMEMBER THAT A WILD ;SPEC IS CURRENT HLLZS WLDBLK+3 ;CLEAR WILD'S POINTER SETZ 0, ;FIX WILD BUG WHICH CLOBBERS 0 CALWLD: MOVEI T1,[SCNBLK] ;RESET SCAN BLOCK ADDRESS IN CASE HRLM T1,WLDBLK ;WE ALREADY CALLED .LKWLD BEFORE, MOVE T1,[OPNBLK,,LKPBLK] MOVEM T1,WLDBLK+1 ;FIX WILD BUG WHICH CLOBBERS MOVE T1,[WLDLEN,,WLDBLK] ;THIS WORD PUSHJ P,.LKWLD## ;GET NEXT FILE NAME FROM WILD SPEC JRST GETSPC ;HERE WHEN DONE WITH WILD SPEC POPJ P, EXAMPLE OF USING SCAN Page 15-9 TSCAN Example 11 Jun 79 ;************************************************* ; PROMPT ROUTINE FOR GETFIL ;************************************************* PROMPT: MOVEI T1,[ASCIZ /FILE: /] PUSHJ P,.TSTRG## ;TYPE STRING POPJ P, ;************************************************* ; ROUTINE TO ALLOCATE OUTPUT FILE SPACE FOR SCAN ;************************************************* GETOUT: MOVE T1,[XWD SCNBLK,SCNBLK+1] SETZM SCNBLK BLT T1,SCNBLK+SCNLEN-1 MOVEI T1,SCNBLK MOVEI T2,SCNLEN POPJ P, EXAMPLE OF USING SCAN Page 15-10 TSCAN Example 11 Jun 79 ;*********************************************************** ; DEFINITIONS AND WORKAREAS NEEDED BY SCAN AND WILD ;*********************************************************** .HELPR==:.TCRLF## ;ELIMINATE LINK10 DIAGNOSTIC ISCBLK: Z ;SCAN INITIALIZATION BLOCK Z Z ;DEFAULT TTY I/O ROUTINES ARE TTCALLS Z XWD PROMPT,MONRET ;PROMPT ROUTINE,,MONITOR RETURN ;ROUTINE Z ISCLEN=.-ISCBLK SCNBLK: BLOCK 20 ;COPY SCAN BLOCK INTO HERE SCNLEN=.-SCNBLK WLDBLK: XWD [SCNBLK],0 ;SCAN-BLOCK POINTER XWD OPNBLK,LKPBLK ;OPEN AND LOOKUP BLOCKS XWD SCNLEN,LKPLEN ;LENGTHS OF SCAN BLOCK ;AND LOOKUP BLOCK EXP 1B0 ;ALLOW ANY DEVICE EXP .POPJ## ;NO ROUTINE TO CALL AT END OF UFD WLDLEN=.-WLDBLK DEFINE SWTCHS< SP FOO,FOOLOC,.SIXSW##,,,0 ;DUMMY SWITCH FOR .TSCAN > DOSCAN (FOO) TSCBLK: IOWD FOOL,FOON ;ARGUMENT BLOCK FOR TSCAN XWD FOOD,FOOM XWD 0,FOOD Z Z XWD GETOUT,GETOUT Z Z Z TSCLEN=.-TSCBLK FOOLOC: Z CHAPTER 16 USING THE MISCELLANEOUS ROUTINES 16.1 INTRODUCTION The purpose of this chapter is to highlight the uses of some of the miscellaneous routines in SCAN. These are routines that are not directly related to the task of scanning command lines, but which often make writing programs simpler. The initial chapter, which listed the routines in SCAN, gave an adequate description of the Input and Output routines, which will not be covered here. 16.2 .LKNAM This routine is used to perform the commonly needed task of table searching. It is, in fact, the routine which the command scanners themselves use to lookup switch and command names. The argument, which must be in SIXBIT (like the table being searched), can be an abbreviation of an entry in the table. Exact matches will always be found, even if they constitute an abbreviation for another command. The lookup attempt into the table will fail for one of two reasons: 1) no match or abbreviation was found at all, or 2) more than one abbreviation, and no exact match, was found. The call on .LKNAM is as follows: MOVE T1,[IOWD len,address] MOVE T2,[SIXBIT/mumble/] PUSHJ P,.LKNAM## -here if failure- -here if success- USING THE MISCELLANEOUS ROUTINES Page 16-2 .LKNAM 11 Jun 79 where: len is the length of the table address is the address of the table mumble is the word being searched for On the failure return: T1<0 if no match was found T1>0 if multiple abbreviations were found On success return: T1<0 if exact match was found T1>0 if abbreviation was found (RH) of T1 = address of table entry matched 16.3 DATE AND TIME CONVERSION Since the conversion between Universal Date/Time and the DEC standard format is complex, a routine is provided within SCAN to perform this function. The Universal format contains the date in the left half, and the time in the right half. The DEC standard Format contains the date (derived in a different manner) in one word, and the time (also of a different derivation) in another unrelated word. Three routines are provided to handle these functions: o .CNTDT - convert from Universal to DEC o .CNVDT - convert from DEC to Universal o .GTNOW - get the current time in Universal format 16.3.1 .CNTDT To convert from universal format to DEC format, use the following calling specification: MOVE T1,universal date-time PUSHJ P,.CNTDT## -always returns here- USING THE MISCELLANEOUS ROUTINES Page 16-3 DATE AND TIME CONVERSION 11 Jun 79 with T1=time as MS past midnite and T2=DEC format date 16.3.2 .CNVDT This routine converts from DEC format to Universal format. The calling sequence for it is: MOVE T1,time MOVE T2,date PUSHJ P,.CNVDT## -always returns here- where "time" is the time in milleseconds past midnite "date" is the date in DATE UUO format On return, T1=Universal date/time, or T1=-1 if arguments were past Sept. 27,2217 An advantage of the Universal format is the ease of converting from date to day of week. The base for the Unviersal system, also referred to as the Astronomical Standard, was a Wednesday. Therefore, dividing the Universal date by seven yields a remainer that indicates the day of the week. Zero would be a Wednesday, and the others fall in sequence. 16.3.3 .GTNOW Since the only method of finding the current Universal date/time from the monitor if via a GETTAB, life is made a little simpler by using this routine. It takes no arguments, and simply returns the current date and time in universal format, in T1. 16.4 MANIPULATING LISTS OF DATA SCAN provides two routines useful when a list of data must be manipulated in a sequential fashion. One routine is used to remove a data word from the list, another to place data into the list. The accumulator usage for these routines is a follows: o T1 is the current address in the list USING THE MISCELLANEOUS ROUTINES Page 16-4 MANIPULATING LISTS OF DATA 11 Jun 79 o T2 is the number of words left in the list o T3 is the data being manipulated. To place data into the list, .PTWRD is called in the following manner: MOVE T1,address MOVE T2,length MOVE T3,datum PUSHJ P,.PTWRD## -always returns here- with T1 incremented to the next list address T2 decremented by 1 T3 contains the old data item To remove an item from the list, .GTWRD is called in a similar fashion: MOVE T1,address MOVE T2,length PUSHJ P,.GTWRD## -always returns here- with T1 incremented by 1 to the next location T2 decremented by 1 T3 data item, or zero if nothing left in list (T2<=0) Note that since the routines automatically update their pointers, the setup need only be done for the first usage of the routines. After that, they can be called successively to remove arguments (or whatever) from a list, and to place return values (or whatever) into the list. APPENDIX A NOTES ON USING THE SCANNERS APPENDICES A. NOTES ON USING THE SCANNERS B. NOTES ON USING WILD C. DIFFERENCES BETWEEN DEC AND OLS SCAN AND WILD D. SCNMAC - COMMAND SCANNER MACROS E. $SCNDC - COMMAND SCANNER DECLARATIONS F. EXAMPLE: SCAN G. EXAMPLE: ALKFIL H. LIST OF CUSPS AND THE SCANNERS WHICH THEY USE NOTES ON USING THE SCANNERS Page A-2 11 Jun 79 o When supplying a user-written character input routine, the character must be returned in P4. No other accumulator should be altered. o When supplying a user-written routine for processing a switch, SCAN will call it via a PUSHJ, with P1 containing the index into the tables generated by DOSCAN for the switch being processed. If it is desired that SCAN store the value, then the routine must leave the value in P3, and take a skip-return. A non-skip return to SCAN is an indication that SCAN should not store a value. o Initial values of the locations into which SCAN stores switch values should be -1. o The maximum value handled by DM is 3777777; the minimum is 0. If these are not suitable for a switch, then define the appropriate symbols before calling DM. o SCAN will generate a reference to the external symbol ".HELPR". This is normally resolved by loading REL:HELPER.REL, and is used for processing the /HELP switch. However, if no help processing is to be done, then the following is sufficient: .HELPR==:.TCRLF## APPENDIX B NOTES ON USING WILD For the most part, WILD is well documented in its write-up in the Software Notebooks. However, there are a few things to be aware of. 1. WILD has a bug which clobbers AC0 in a very orderly fashion; try to keep your own AC0 safe. 2. Because of the nature of #1, if multiple top-level calls to WILD are made (i.e.: multiple wild card specs not scanned off together), then WILD, after completely expanding the first spec, will forever after think it is done. This is because AC0 is clobbered to a file-spec pointer, later to something else, and then even later looked at in the context of a file-spec pointer. The "fix" is a simple SETZ of AC0 before each top-level call to .LKWLD is started. 3. The documentation says that .LKWLD only needs to be given the address of its argument block. WRONG! Like almost all other code, it expects to see a length in the left half of T1. 4. For an unknown reason, WILD will, on occasion, write into part of its argument block, usually to the OPEN block and LOOKUP block pointers. Beware. NOTES ON USING WILD Page B-2 11 Jun 79 The following subroutines are also documented in the Software Notebooks, but are included here for added exposure. To type a standard LOOKUP or ENTER error message, the following routines are quite useful: o To type out a message which includes the filename, error code, etc.: MOVEI T1, address of extended LOOKUP/ENTER block MOVEI T2, length of LOOKUP block MOVEI T3, address of SCAN block PUSHJ P, E.LKEN## o To type out only the code and its meaning (no filename, etc.): MOVE1 T1, error-code PUSHJ P, .LKERR## APPENDIX C CHANGES MADE TO SCAN & WILD Differences In SCAN & WILD Between the Digital Equipment Corp. Version and On-Line Systems, Inc. Version For the most part, no major changes have been made to the DEC released versions. Some code has been added, and the characteristics of other code have been slightly altered. In particular: o Modules for Space Allocation and Random Number Generation have been added to SCAN. o The subroutine .TRDXW in SCAN has been fixed to work correctly. The digits A,B,C,D,E,F,... used to come out one digit too high (B,C,D,E,F,G,...). o Code has been added to save any "T" accumulator into which a value is not being returned. (DEC clobbered the "T" accumulators at will, since they were "temporarY"). This makes it simpler to use SCAN with existing software, which may have a more or less arbitrary set of register conventions. o A number of additional single-character output routines have been added. These perform the task of printing a single special character, in the same way that .TCOLN is used to easily print a colon character. The routines which have been added are identifiable in the list given CHANGES MADE TO SCAN & WILD Page C-2 11 Jun 79 earlier (see Chapter Two) by the asterisk in the outside margin. APPENDIX D SCNMAC: COMMAND SCANNER MACROS This is a listing of the contents of SCNMAC.MAC, which is the file containing most of the MACROS and parameters used by SCAN's routines. It is accessed by the SEARCH SCNMAC statement at the beginning of a program using SCAN. SCNMAC - COMMAND SCANNER MACROS SUBTTL COMMAND SCANNER MACROS %7(105) 25-AUG-74 ;MACRO DEFINITIONS OF GENERAL USE ;DEFAULTS ;DM ABBREVIATION,MAX,ADEFAULT,PDEFAULT ; DEFINES SYMBOLS MX.ABBREVIATION, ; AD.ABBREVIATION, AND PD.ABBREVIATION TO ; BE THE MAXIMUM ALLOWED VALUE, THE ; DEFAULT IF THE KEYWORD IS ABSENT, AND ; THE DEFAULT IF THE KEYWORD IS PRESENT ; RESPECTIVELY UNLESS THE CORRESPONDING ; SYMBOL IS ALREADY DEFINED. DEFINE DM(ABBR,MAX,ADEF,PDEF),< ND MX.'ABBR,MAX ND AD.'ABBR,ADEF ND PD.'ABBR,PDEF> SCNMAC: COMMAND SCANNER MACROS Page D-2 11 Jun 79 ; KEYS (NAME,LIST) WILL DEFINE A LIST OF KEYS BY NAME NAME ; NAME CAN BE UP TO 4 CHARS. (DEFINES NAME.T AND NAME.L) ; LIST IS SIXBIT NAMES SEPARATED BY COMMAS. ; DEFINES NAME CONCATENATED WITH START OF ITEM IN LIST ; AS INDEX IN LIST UNLESS THE ITEM BEGINS WITH "*" ;SWITCH SCANNING MACROS AND TABLES ; SWTCHS IS THE MACRO LISTING ALL KNOWN ; SWITCHES. IT INCLUDES THE NAME AND ; STORAGE LOCATION FOR VALUE TYPES, IT ; ALSO HAS THE MAX AND DEFAULT AND ; PROCESSOR FOR KEY-VALUE TYPES, IT POINTS ; TO THE KEYS AND HAS THE DEFAULT IF ANY ; FOR STAND-ALONE TYPES, IT HAS THE VALUE. ;WHEN THE SWITCH SCANNING TABLES ARE TO BE BUILT, INVOKE ;THE MACRO DOSCAN WITH 5-CHAR ARGUMENT TO USE AS SYMBOL PREFIX ;IT WILL DEFINE XXXXXN,L,P,M,D SCNMAC: COMMAND SCANNER MACROS Page D-3 11 Jun 79 ; SL NAME,STORAGE,TABLE-NAME,DEFAULT,FLAGS ; DEFINES A LIST OF KEY-VALUES (SEE KEYS MACRO) ; DEFAULT IS THE ORDINAL OR 0 IF NO DEFAULT ; IF LH(STORAGE)=7777B11, STORAGE = ROUTINE TO PROCESS ; ; SP NAME,STORAGE,PROCESSOR,ABBREVIATION,FLAGS ; DEFINES A VALUE PARAMETER WHOSE DEFAULTS ; ARE DEFINED AT THE BEGINNING OF THE PROGRAM ; BY "DM" USING THE SAME ABBREVIATION ; PROCESSOR IS THE JUMP ADDRESS IN SWITCH PROCESSING ; IT WILL BE CALLED WITH P1=SWITCH OFFSET IN TABLE ; AND P2=POINTER TO 4-WORD BLOCK OF ; INTERNAL OR EXTERNAL STUFF ; IF MAX=0 AND FS.LRG, THEN ANY VALUE CAN BE STORED ; ELSE, 0.LE.VALUE.LE.MAX ; ; 0.LE.MAX,DEFAULT.LT.2**17 UNLESS FS.LRG ; ; IF MAX=0 AND NOT FS.LRG, THEN ; PROCESSOR IS AN IMMEDIATE ACTION ; WHICH WILL ALWAYS BE CALLED ; ELSE, PROCESSOR WILL BE CALLED ONLY IF ":" ; ; SS NAME,STORAGE,VALUE,FLAGS ; DEFINES A STAND-ALONE PARAMETER ; ; IN ALL CASES, STORAGE IS A BYTE POINTER. ; IF A FULL WORD, ONLY THE ADDRESS IS NEEDED ; IF A MULTIPLE WORD, THE BYTE SIZE IS 65-#WORDS ; (UP TO 28) ; IF A FILE SPECIFICATION, THE LENGTH IS HELD ; IN MX.ABBREVIATION ; IF POINTER IS 7777??,,?????? THEN RH(POINTER) ; IS DISPATCH ADDRESS OF PROCESSOR WHICH TAKES ; KEYWORD SWITCH VALUES ; ; SN NAME,STORAGE,FLAGS ; DEFINES A STAND-ALONE PARAMETER WHICH TAKES VALUE ; 1 IF /NAME, AND VALUE 0 IF /NONAME ;FLAGS WHICH CAN BE DEFINED IN SWITCH TABLE >FS.NFS==1B0 ;THIS SWITCH IS NEVER PART OF A ;FILE SPECIFICATION ; THIS SHOULD BE SET ON GLOBAL SWITCHES ; ** VERY IMPORTANT TO GET RIGHT ** >FS.LRG==1B1 ;THE MAX AND DEFAULT VALUES ARE 0 OR .GT. 2**17 >FS.NUE==1B2 ;NO USER EXIT ON THIS SWITCH >FS.VRQ==1B3 ;VALUE REQUIRED >FS.OBV==1B4 ;OR BIT VALUES TO RIGHT HALF >FS.NOS==1B5 ;SWITCH TAKES "NO" PREFIX ;(INTERNAL FOR SN MACRO ONLY) >FS.NCM==1B6 ;SWITCH DOES NOT CONSTITUTE A COMMAND [102] ; (FOR /RUN, /OPTION, /EXIT) SCNMAC: COMMAND SCANNER MACROS Page D-4 11 Jun 79 ;WORDS IN FILE SPEC AREA .FXDEV==0 ;DEVICE (NON-ZERO IF ANY PART OF SPEC) .FXNAM==1 ;NAME (NON-ZERO IF NAME PRESENT) .FXNMM==2 ;NAME MASK .FXEXT==3 ;EXTENSION,,EXTENSION MASK (NON-ZERO DOT PRESENT) .FXMOD==4 ;MODIFIER WORD .FXMOM==5 ;MODIFIER MASK .FXDIR==6 ;DIRECTORY WORD (EACH HALF=0 IF DEFAULT; ;SFD:0 IF END) .FXDIM==7 ;DIRECTORY MASK .FXBFR==22 ;/BEFORE .FXSNC==23 ;/SINCE .FXABF==24 ;/ABEFORE .FXASN==25 ;/ASINCE .FXFLI==26 ;FILE MIN SIZE (WORDS) .FXFLM==27 ;FILE MAX SIZE (WORDS) .FXEST==30 ;/ESTIMATE .FXVER==31 ;/VERSION ;LENGTHS OF FILE SPEC AREA .FXLEN==32 ;LENGTH OF ONE SPECIFICATION .FXLND==6 ;LENGTH OF DIRECTORY (UFD+SFD'S) ;BYTES IN SCAN MOD WORD FX.NDV==1B0 ;NULL DEVICE FX.NUL==1B1 ;NULL EXTENSION FX.DIR==1B2 ;DIRECTORY SPECIFIED (MOD=0 IF [-]) FX.PHY==1B3 ;/PHYSICAL FX.NOM==1B4 ;/OKNONE FX.DFX==1B5 ;DIRECTORY DOES NOT NEED FIX-UP BY WILD FX.TRM==7B8 ;CODE FOR SPEC'S TERMINATION .FXTRA==1 ;& (AND) .FXTRO==2 ;! (OR) .FXTRN==3 ;- (NOT) .FXTRC==4 ;+ (CONCATENATE) FX.STR==1B9 ;/STRS FX.PRT==1B10 ;/OKPROT FX.SUP==1B11 ;/ERSUPERSEDE FX.DEN==7B23 ;/DENSITY [105] FX.PAR==1B24 ;/PARITY FX.PRO==777B35 ;/PROTECTION SCNMAC: COMMAND SCANNER MACROS Page D-5 11 Jun 79 ;SPECIAL CHARACTERS FOR SCAN .CHALX==0 ;ALTMODE .CHEOL==-1 ;END OF LINE .CHEOF==-2 ;END OF FILE ;GUIDE WORDS (TURNED INTO PSEUDO CHARACTERS) .CHAND==4000 ;'AND' [101] .CHOR==04001 ;'OR' [101] .CHNOT==4002 ;'NOT' [101] .CHTO==04003 ;'TO' [103] .CHFRM==4004 ;'FROM' [103] .CHINP==4005 ;'INPUT' [103] .CHOUT==4006 ;'OUTPUT' [103] .CHSRC==4007 ;'SOURCE' [103] .CHLST==4010 ;'LIST' [103] .CHOBJ==4011 ;'OBJECT' [103] ;FLAGS FOR .ISCAN CALL FS.ICL==1B17 ;IGNORE SPECIAL COMMAND-LINE HANDLING ;FLAGS FOR .TSCAN CALL FS.MOT==1B18 ;MULTIPLE OUTPUT SPECS POSSIBLE FS.MIO==1B19 ;MIXED INPUT AND OUTPUT SPECS ;FLAGS FOR .TDIRB CALL TS.DRW==0 ;SINGLE WORD TS.DRP==1 ;PATH POINTER TS.DRB==2 ;BIWORD (IE, SCAN SPEC FORMAT) ;VALUES FROM .VERBO JWW.CN==1B33 ;/VERBOS:CONTINUATION JWW.FL==1B34 ;/VERBOS:FIRST JWW.PR==1B35 ;/VERBOS:PREFIX APPENDIX E $SCNDC: COMMAND SCANNER DECLARATIONS $SCNDC is a part of SCAN.MAC, which generates $SCNDC.UNV whenever SCAN is assembled. It contains the definitions of some SCAN/WILD related symbols, and the accumulators, for use by programs which must interface with SCAN & WILD. It is accessed by the SEARCH $SCNDC statement at the beginning of the program using SCAN or WILD. UNIVERSAL $SCNDC -- DECLARATIONS FOR COMMAND SCANNER SEARCH C,SCNMAC ;SEARCH PARAMETERS FOR THIS FILE ;AC NAMES T1=1 ;TEMPORARIES T2=2 T3=3 T4=4 P1=5 ;PRESERVED ACS FOR CALLING ROUTINES P2=6 P3=7 P4=10 P=17 ;PUSH-DOWN POINTER DM MSG,77777,0,7 ;MESSAGE DM PRO,777,0,277 ;PROTECTION $SCNDC: COMMAND SCANNER DECLARATIONS Page E-2 11 Jun 79 DM RNC,777777,0,0 ;RUN CORE DM RUN,7,-1,1 ;RUN OFFSET VRBADX==10 ;/MESSAGE:ADDRESS PRGEND APPENDIX F EXAMPLES: SCAN'S INTERNAL SWITCH TABLES It was mentioned at various points in the text that SCAN has certain switches built into it. As might be expected, SCAN uses itself to process htese switches. Therefore, it is interesting and useful to see just how SCAN defines its own switches, using the DOSCAN, SWTCHS, DM and KEYS macros. ;HERE WE DEFINE STANDARD SWITCHES PROCESSED IN SCAN DEFINE SWTCHS,< SP ABEFORE,F.ABF,.SWDTP,,FS.VRQ SP ASINCE,F.ASN,.SWDTP,,FS.VRQ SP BEFORE,F.BFR,.SWDTP,,FS.VRQ SL DENSITY,,DENS,DENSIN SS ERNONE,,0 SS ERPROTECTION,,0 SS ERSUPERSEDE,,1 SP ESTIMATE,F.EST,.BLOKW,,FS.VRQ SP EXIT,N.DEV,SWEXIT,,FS.NFS!FS.NCM SL *HELP,<-1,,.SWHLP>,HELP,HELPTEXT,FS.NFS!FS.NCM SP LENGTH,F.FLM,SWLEN,,FS.VRQ SL MESSAGE,<*F,.FLVRB##>,VRB,PD.MSG,FS.OBV!FS.NFS!FS.NCM SS NOOPTION,OPTION,0,FS.NFS!FS.NCM SS OKNONE,,1 SS OKPROTECTION,,1 SS OKSUPERSEDE,,0 SP OPTION,OPTION,.SWSIX,OPT,FS.NFS!FS.NCM EXAMPLES: SCAN'S INTERNAL SWITCH TABLES Page F-2 11 Jun 79 SL PARITY,,PAR,PARODD SN PHYSICAL, SP PROTECTION,,.SWOCT,PRO SP RUN,N.ZER,.SWFIL,RNL,FS.NFS!FS.NCM!FS.VRQ SP RUNCORE,N.CORE,.SWCOR,RNC,FS.LRG!FS.NFS!FS.NCM SP RUNOFFSET,N.OFFS,.SWOCT,RUN,FS.NFS!FS.NCM SP SINCE,F.SNC,.SWDTP,,FS.VRQ SN STRS, SP TMPFILE,,SWTMP,,FS.VRQ!FS.NFS!FS.NCM SP VERSION,F.VER,.VERSW,,FS.VRQ > EXAMPLES: SCAN'S INTERNAL SWITCH TABLES Page F-3 11 Jun 79 ;NOW BUILD THE TABLES FROM THE SWTCHS MACRO MX.OPT==1 PD.OPT==0 MX.RNL==N.EZER-N.ZER+1 PD.RNL==0 DOSCAN (STSWT) ;HERE WE BUILD THE KEYS KEYS (DENS,<200,556,800,1600,6250,%%,$$,INSTALLATION>) KEYS (HELP,) KEYS (PAR,) ; --DUMMIES-- [321] KEYS (VRB,) APPENDIX G EXAMPLES: ALKFIL ALKFIL is a non-DEC program written to perform the tasks of file space allocation. It uses SCAN to process the command lines, and is a useful example of the various options available to the SCAN & WILD user. DEFINE SWTCHS< SP SIZE,FILSIZ,.DECNW##,FIL,FS.VRQ!FS.NCM ;[#46] SP MINDRIVES,MINDRV,.DECNW##,MND,FS.VRQ!FS.NFS ;[#51] SP MAXDRIVES,MAXDRV,.DECNW##,MND,FS.VRQ!FS.NFS ;[#51] SP PARTITIONS,PARTNS,GETPRT##,PRT,FS.VRQ!FS.NFS SP REPEAT,RPTFCT,.DECNW##,RPT,FS.VRQ!FS.NFS ;[#33] SL SPLIT,SPLIND,SPLT,,FS.VRQ!FS.NFS SL ALLOCATE,ALCIND,ALOC,,FS.VRQ!FS.NFS SL ADDRESSING,ADRIND,ADRS,,FS.VRQ!FS.NFS SP BUFSIZ,BUFSIZ,.DECNW##,BUFS,FS.VRQ!FS.NFS SP UNIT,UNINAM,GETUNI##,,FS.VRQ!FS.NFS ;[#25] SP BLOCK,BLKNUM,GETBLK##,,FS.VRQ!FS.NFS ;[#23] SP LBN,LBNNUM,GETLBN##,,FS.VRQ!FS.NFS ;[#31] SP STATUS,STSOBJ,.SIXSW##,,FS.NFS ;[#25] SS STRSTS,,1 SS CREATE,,1 SS PREALLOC,,1 SS COPY,,1 SS NOLOG,,1 ;[#46] SP SPOOL,SPOOL,.SIXSW##,,FS.VRQ!FS.NFS ;[#57] SS DEBUG,,1 ;[#60] > EXAMPLES: ALKFIL Page G-2 11 Jun 79 ;EXPAND SWITCH TABLES FOR SCAN: DOSCAN(SWIT) ;DEFINE DEFAULTS AND KEY-LISTS ; NAME,MAX,ABSENT-DEFAULT,PRESENT-DEFAULT DM (MND,^D31,1,1) ;[#51] DM (MXD,^D32,32,32) ;[#51] DM (PRT,^D65,^D30,1) ;[#65] ;0 IMPLIES MINIMUM NEEDED INTERNAL MX.PRT,AD.PRT ;[#43] FOR USE ;[#43] BY OTHER ;[#43] MODULES DM (RPT,1,1,1) ;[#32] DM (BUF,^D100,^D25,^D5) ;[#52] DM (FIL,377777,^D1000,^D1000) ;[#40] ;******** IMPORTANT ********* ;IF THE ORDER OF ARGUMENTS TO THE KEYS MACRO ;IS CHANGED, THEN THE CORRESPONDING $$XXX ;TABLE MUST ALSO BE CHANGED. KEYS (SPLT,) ;[#61] KEYS (ALOC,) ;[#60] KEYS (ADRS,) ;[#22] APPENDIX H CUSPS & THEIR SCANNERS Not all DEC programs use SCAN & WILD. Most of the more recent (from about 1976 on) tend to use it, and some of the older ones use it. Many of the remaining programs, especially the very old CUSPS (REACT, SOUP, etc.) each have their own code to process their own (usually different) styles of commands. The list that follows indicates which DEC (and some non-DEC) programs use SCAN, and which use their own scanners. It should proves useful as a source of further information on using scan. In particular, the module LNKSCN of LINK-10 is an excellant reference to using the switch-defining macros. CUSP SCANNER COMMENTS ---------- ------------ ----------------------- ALGOL own BACKUP SCAN .VSCAN BASIC own BATCON (MPB) own BATCON (GALAXY) SCAN BLISS-10 own Compiler fake's it (no SFDs) BOOT11 own CHANGE own COBOL own COMPIL own CREDIR SCAN Uses .PSCAN CUSPS & THEIR SCANNERS Page H-2 11 Jun 79 CUSP SCANNER COMMENTS ---------- ------------ ----------------------- CREF own DAEMON old SCAN Has SCAN V2 built into it DIRECT SCAN FILCOM own FILEX own FORTRAN-10 SCAN GALAXY SCAN All components HELP SCAN INITIA own even simulates .OSCAN ISAM own JQ SCAN (non-DEC) uses .TSCAN KJOB (MPB) own LIBARY own LINED own LINK-10 SCAN Excellant example (LNKSCN) LOGIN SCAN LOGOUT (MPB) own LOGOUT (GALAXY) SCAN LPTSPL (MPB) own Same for other spoolers LPTSPL (GALAXY) SCAN -dittoe- MACRO own MAIL own (non-DEC) good job of faking it MAKLIB SCAN OMOUNT own OPSER own PIP own QUEUE (MPB) SCAN .TSCAN QUEUE (GALAXY) SCAN .TSCAN REACT own RERUN own RUNOFF SCAN .TSCAN SETSRC own SORT-10 SCAN SOS own SOUP own SYSTAT own TECO own UMOUNT own APPENDIX I INDEX Page Index-1 INDEX $scndc . . . . . . . . . . . . . E-1 .aplst . . . . . . . . . . . . . 7-2 .ascqw . . . . . . . . . . . . . 2-6 .asqcq . . . . . . . . . . . . . 2-6 .blokc . . . . . . . . . . . . . 2-9 .blokw . . . . . . . . . . . . . 2-9 .ch??? symbols . . . . . . . . . D-5 .clrbf . . . . . . . . . . . . . 2-13 .cntdt . . . . . . . . . . . . . 2-11 .cnvdt . . . . . . . . . . . . . 2-11 .corec . . . . . . . . . . . . . 2-9 .corew . . . . . . . . . . . . . 2-9 .datic . . . . . . . . . . . . . 2-6 .datif . . . . . . . . . . . . . 2-7 .datig . . . . . . . . . . . . . 2-7 .datim . . . . . . . . . . . . . 2-6 .datip . . . . . . . . . . . . . 2-6 .datiq . . . . . . . . . . . . . 2-6 .decnc . . . . . . . . . . . . . 2-6 .decnw . . . . . . . . . . . . . 2-6 .filin . . . . . . . . . . . . . 2-10, 6-2 .fx??? offsets . . . . . . . . . D-4 .gtnow . . . . . . . . . . . . . 2-11 .gtwds . . . . . . . . . . . . . 2-2 .gtwrd . . . . . . . . . . . . . 2-13 .iscan . . . . . . . . . . . . . 2-1, 9-1, D-5 .iscan flags . . . . . . . . . . D-5 .islgi . . . . . . . . . . . . . 2-14 .lknam . . . . . . . . . . . . . 2-11, 16-1 .mkmsk . . . . . . . . . . . . . 2-14 .mkpjn . . . . . . . . . . . . . 2-11 .namec . . . . . . . . . . . . . 2-6 .namew . . . . . . . . . . . . . 2-6 .octnc . . . . . . . . . . . . . 2-6 .octnw . . . . . . . . . . . . . 2-6 .oscan . . . . . . . . . . . . . H-2 .pop4t . . . . . . . . . . . . . 2-2 .popj . . . . . . . . . . . . . 2-2 .popj1 . . . . . . . . . . . . . 2-2 .pscan . . . . . . . . . . . . . 13-1, 15-3, H-1 .psh4t . . . . . . . . . . . . . 2-2 .ptwrd . . . . . . . . . . . . . 2-13 .qscan . . . . . . . . . . . . . 13-1, 15-3 .rand . . . . . . . . . . . . . 2-11 .randm . . . . . . . . . . . . . 2-11 .reeat . . . . . . . . . . . . . 2-13 .runcm . . . . . . . . . . . . . 2-11 .savex . . . . . . . . . . . . . 2-2 .savxt . . . . . . . . . . . . . 2-2 Page Index-2 .sixmc . . . . . . . . . . . . . 2-6 .sixmw . . . . . . . . . . . . . 2-6 .sixqc . . . . . . . . . . . . . 2-6 .sixqw . . . . . . . . . . . . . 2-6 .sixsc . . . . . . . . . . . . . 2-6 .sixsw . . . . . . . . . . . . . 2-6 .stopb . . . . . . . . . . . . . 2-13, 8-3 .t2crl . . . . . . . . . . . . . 2-4 .t2spc . . . . . . . . . . . . . 2-4 .t4crl . . . . . . . . . . . . . 2-4 .t4spc . . . . . . . . . . . . . 2-4 .tampr . . . . . . . . . . . . . 2-4 .tapos . . . . . . . . . . . . . 2-4 .tarow . . . . . . . . . . . . . 2-4 .tastr . . . . . . . . . . . . . 2-4 .tatsi . . . . . . . . . . . . . 2-4 .tbksl . . . . . . . . . . . . . 2-4 .tblok . . . . . . . . . . . . . 2-3 .tcart . . . . . . . . . . . . . 2-4 .tchar . . . . . . . . . . . . . 2-4 .tcoln . . . . . . . . . . . . . 2-4 .tcoma . . . . . . . . . . . . . 2-4 .tcorw . . . . . . . . . . . . . 2-3 .tcrlf . . . . . . . . . . . . . 2-4 .tdash . . . . . . . . . . . . . 2-4 .tdate . . . . . . . . . . . . . 2-3 .tdatn . . . . . . . . . . . . . 2-3 .tdec2 . . . . . . . . . . . . . 2-3 .tdecw . . . . . . . . . . . . . 2-3 .tdirb . . . . . . . . . . . . . 2-14, D-5 .tdirb flags . . . . . . . . . . D-5 .tdolr . . . . . . . . . . . . . 2-4 .tdttm . . . . . . . . . . . . . 2-3 .tequl . . . . . . . . . . . . . 2-4 .texcl . . . . . . . . . . . . . 2-4 .tfchr . . . . . . . . . . . . . 2-4 .thash . . . . . . . . . . . . . 2-4 .tican . . . . . . . . . . . . . 2-9 .tlang . . . . . . . . . . . . . 2-4 .tlbrk . . . . . . . . . . . . . 2-4 .tlpar . . . . . . . . . . . . . 2-4 .tmohw . . . . . . . . . . . . . 2-2 .toctw . . . . . . . . . . . . . 2-3 .toleb . . . . . . . . . . . . . 2-3 .tpcnt . . . . . . . . . . . . . 2-4 .tplus . . . . . . . . . . . . . 2-4 .tppnw . . . . . . . . . . . . . 2-3 .tquot . . . . . . . . . . . . . 2-4 .trang . . . . . . . . . . . . . 2-4 .trbrk . . . . . . . . . . . . . 2-4 .trdxw . . . . . . . . . . . . . 2-3 .trpar . . . . . . . . . . . . . 2-4 .tscan . . . . . . . . . . . . . D-5, H-2 .tscan flags . . . . . . . . . . D-5 Page Index-3 .tsemi . . . . . . . . . . . . . 2-4 .tsixn . . . . . . . . . . . . . 2-2 .tslsh . . . . . . . . . . . . . 2-4 .tspac . . . . . . . . . . . . . 2-4 .tstrg . . . . . . . . . . . . . 2-2 .ttabc . . . . . . . . . . . . . 2-4 .ttime . . . . . . . . . . . . . 2-3 .ttimn . . . . . . . . . . . . . 2-3 .tverw . . . . . . . . . . . . . 2-3 .txwdw . . . . . . . . . . . . . 2-3 .txwww . . . . . . . . . . . . . 2-2 .tyoch . . . . . . . . . . . . . 2-1 .verbo . . . . . . . . . . . . . D-5 .verbo flags . . . . . . . . . . D-5 .versc . . . . . . . . . . . . . 2-8 .versw . . . . . . . . . . . . . 2-8 .vscan . . . . . . . . . . . . . H-1 /run switch processing . . . . . 2-11 ????.l . . . . . . . . . . . . . 5-3 ????.t . . . . . . . . . . . . . 5-3 ?????d . . . . . . . . . . . . . 5-4 ?????l . . . . . . . . . . . . . 5-4 ?????m . . . . . . . . . . . . . 5-4 ?????n . . . . . . . . . . . . . 5-4 ?????p . . . . . . . . . . . . . 5-4 ????xx . . . . . . . . . . . . . 5-4 Accumulator names . . . . . . . E-1 Acessing scan . . . . . . . . . 14-1 Ad.??? . . . . . . . . . . . . . 5-1, 5-3 Ccl job number . . . . . . . . . 2-11 Chaining execution . . . . . . . 2-11 Character checking . . . . . . . 2-9 Character input . . . . . . . . 2-9, 2-13 Character output . . . . . . . . 2-4 Charater input - positioning . . 2-13 Clearing input buffers . . . . . 2-13 Command scanners . . . . . . . . 3-1 Conversion - scan blocks . . . . 2-13 Core sizes - inputting . . . . . 2-9 Core sizes - typing . . . . . . 2-3 Credir . . . . . . . . . . . . . 3-2, 13-3, 15-3 Date conversion routines . . . . 2-11 Date/time . . . . . . . . . . . 2-3, 2-6 Dec date/time - conversion . . . 2-11 Default values . . . . . . . . . 3-5 Defaults - absent . . . . . . . 5-3 Defaults - present . . . . . . . 5-3 Defining default values . . . . 5-1 Defining keywords for sl switches 5-2 Defining scanner tables . . . . 4-1 Defining switch parameters . . . 4-1 Page Index-4 Defining switches . . . . . . . 3-5 Defining the storage field . . . 6-1 Defining values for sl switches 5-1 Differences - dec/ols . . . . . C-1 Dm macro . . . . . . . . . . . . 5-1, 14-1, D-1 Dm macro definition . . . . . . D-1 Doscan macro . . . . . . . . . . 4-1 to 4-2, 5-4, 10-1, 10-4, 14-1, 15-5, 15-10, A-2, D-2, F-3, G-2 Enter/lookup blocks . . . . . . 2-14 Enter/lookup/open blocks - typing 2-3 Example - credir . . . . . . . . 15-3 File sizes - inputting . . . . . 2-9 File sizes - typing . . . . . . 2-3 File specification format . . . 3-4 File specification input . . . . 2-10 File specification inputting . . 2-10, 8-1 File specification output . . . 2-3 Fs.??? flags . . . . . . . . . . 4-4, D-3 Fs.??? symbols . . . . . . . . . D-4 Fs.icl . . . . . . . . . . . . . 9-3, D-5 Fs.lrg . . . . . . . . . . . . . 4-5 Fs.mio . . . . . . . . . . . . . 10-3, D-5 Fs.mot . . . . . . . . . . . . . 10-3, D-5 Fs.ncm . . . . . . . . . . . . . 4-5 Fs.nfs . . . . . . . . . . . . . 4-5 Fs.nos . . . . . . . . . . . . . 4-5 Fs.nue . . . . . . . . . . . . . 4-5 Fs.obv . . . . . . . . . . . . . 4-5 Fs.vrq . . . . . . . . . . . . . 4-5 Guide words . . . . . . . . . . 2-10, 8-2, D-5 Helper . . . . . . . . . . . . . 10-1, 10-4 Helper. . . . . . . . . . . . . 10-4 Helper.rel . . . . . . . . . . . 14-2 Initialization . . . . . . . . . 2-1 Input line positioning . . . . . 2-13 Input routines . . . . . . . . . 2-6 Input routines - character . . . 2-13 Input routines - characters . . 2-9 Input routines - clearing input buffers 2-13 Input routines - core & file sizes 2-9 Input routines - date/time . . . 2-6 Input routines - file specifications 2-10 Input routines - string and numeric 2-6 Input routines - version numbers 2-8 Inputting ascii strings . . . . 2-6 Inputting core sizes . . . . . . 2-9 Inputting dates - future . . . . 2-7 Inputting dates - general . . . 2-6 Page Index-5 Inputting dates - past . . . . . 2-6 Inputting dates - universal format 2-6 Inputting decimal numbers . . . 2-6 Inputting file sizes . . . . . . 2-9 Inputting file specifications . 8-1 Inputting file specificatons . . 2-10 Inputting numbers - decimal . . 2-6 Inputting numbers - octal . . . 2-6 Inputting octal numbers . . . . 2-6 Inputting sixbit strings . . . . 2-6 Inputting sixbit words . . . . . 2-6 Inputting sixbit words - wild . 2-6 Inputting version numbers . . . 2-8 Inputting words/strings - ascii 2-6 Inputting words/strings - sixbit 2-6 Inputting words/strings - wild sixbit 2-6 Iscan . . . . . . . . . . . . . 9-1 Iscan flags . . . . . . . . . . D-5 Jww.cn . . . . . . . . . . . . . D-5 Jww.fl . . . . . . . . . . . . . D-5 Jww.pr . . . . . . . . . . . . . D-5 Keys keys . . . . . . . . . . . 14-1 Keys macro . . . . . . . . . . . 5-1 to 5-2, D-2 Keys macro definition . . . . . D-2 Keyword table - address . . . . 5-3 Keyword table - entries . . . . 5-4 Keyword table - length . . . . . 5-3 Lookup/enter blocks . . . . . . 2-14 Lookup/open blocks - typing . . 2-3 Macros - dm . . . . . . . . . . 5-1, 14-1, D-1 Macros - doscan . . . . . . . . 5-4, 10-1, 10-4, 14-1, 15-5, 15-10, A-2, D-2, F-3, G-2 Macros - keys . . . . . . . . . 5-1 to 5-2, 14-1, D-2 Macros - sl . . . . . . . . . . 4-3, 6-2, 14-1, D-3 Macros - sn . . . . . . . . . . 4-3, 6-2, 14-1, D-3 Macros - sp . . . . . . . . . . 4-4, 6-2, 14-1 Macros - ss . . . . . . . . . . 4-2, 6-2, 14-1, D-3 Macros - swtchs . . . . . . . . D-2 Manipulating lists of data . . . 2-13 Masks . . . . . . . . . . . . . 2-14 Miscellaneous routines . . . . . 2-11 Mx.??? . . . . . . . . . . . . . 5-3 Mx.???? . . . . . . . . . . . . 5-1 Numeric output . . . . . . . . . 2-3 Open/lookup blocks - typing . . 2-3 Options scanner . . . . . . . . 11-1 Oscan . . . . . . . . . . . . . 3-2, 11-1, H-2 Output routines - core size . . 2-3 Page Index-6 Output routines - date/time . . 2-3 Output routines - file size . . 2-3 Output routines - file specifications 2-3 Output routines - numeric output 2-3 Output routines - open/lookup block 2-3 Output routines - ppn . . . . . 2-3 Output routines - text . . . . . 2-2 Partial scanner . . . . . . . . 13-1 Pd.??? . . . . . . . . . . . . . 5-3 Pointr macro . . . . . . . . . . 6-1 Ppns - typing . . . . . . . . . 2-3 Pscan . . . . . . . . . . . . . 3-2, 13-1, 15-3, H-1 Qscan . . . . . . . . . . . . . 13-1, 15-3 Random number generator . . . . 2-11 Register mnemonics . . . . . . . 1-2, E-1 Register saving . . . . . . . . 2-2 Register-saving . . . . . . . . 2-2 Run uuo . . . . . . . . . . . . 2-11 Scan block conversion . . . . . 2-13 Scan blocks . . . . . . . . . . 2-13 to 2-14, 6-2 Scan controlling flags . . . . . 4-4 Scan flags - fs.lrg . . . . . . 4-5 Scan flags - fs.ncm . . . . . . 4-5 Scan flags - fs.nfs . . . . . . 4-5 Scan flags - fs.nos . . . . . . 4-5 Scan flags - fs.nue . . . . . . 4-5 Scan flags - fs.obv . . . . . . 4-5 Scan flags - fs.vrq . . . . . . 4-5 Scan switches - sl . . . . . . . 6-2 Scan switches - sn . . . . . . . 6-2 Scan switches - sp . . . . . . . 6-2 Scan switches - ss . . . . . . . 6-2 Scnmac . . . . . . . . . . . . . D-1 Sixbit masks . . . . . . . . . . 2-14 Sl . . . . . . . . . . . . . . . 14-1 Sl macro . . . . . . . . . . . . 4-3, 6-2, D-3 Sl macro definition . . . . . . D-3 Sn . . . . . . . . . . . . . . . 14-1 Sn macro . . . . . . . . . . . . 4-3, 6-2, D-3 Sn macro definition . . . . . . D-3 Sp . . . . . . . . . . . . . . . 14-1 Sp macro . . . . . . . . . . . . 4-4, 6-2 Space allocation . . . . . . . . 2-2 Ss . . . . . . . . . . . . . . . 14-1 Ss macro . . . . . . . . . . . . 4-2, 6-2, D-3 Ss macro definition . . . . . . D-3 Storage field - file specification 6-2 Suffixes - decimal & octal input 2-6 Switch formats . . . . . . . . . 3-3 Switch tables - defaults . . . . 5-4 Page Index-7 Switch tables - length . . . . . 5-4 Switch tables - names . . . . . 5-4 Switch tables - processors . . . 5-4 Switch tables - storage . . . . 5-4 Switch types - sl . . . . . . . 4-3 Switch types - sn . . . . . . . 4-3 Switch types - sp . . . . . . . 4-4 Switch types - ss . . . . . . . 4-2 Swtchs macro . . . . . . . . . . 3-5, D-2 Swtchs macro - definition . . . 4-2 Swtchs macro - usage . . . . . . 4-1 Swtchs macro definition . . . . D-2 Table searching . . . . . . . . 2-11 Testing for logged-in jobs . . . 2-14 Traditional scanner . . . . . . 10-1 Ts.drb . . . . . . . . . . . . . D-5 Ts.drp . . . . . . . . . . . . . D-5 Ts.drw . . . . . . . . . . . . . D-5 Tscan . . . . . . . . . . . . . 3-1, 10-1, H-2 Tscan flags . . . . . . . . . . D-5 Typing directory information . . 2-14 Typing lookup/enter blocks . . . 2-14 Typing open/lookup blocks . . . 2-3 Typing path blocks . . . . . . . 2-14 Typing ppns . . . . . . . . . . 2-3 Typing scan blocks . . . . . . . 2-14 Universal date/time - conversion 2-11 Universal date/time - current . 2-11 Unversal date/time input . . . . 2-6 Using the miscellaneous routines 2-11, 2-13 to 2-14 Using the miscellaneous routines. 2-11, 2-14 Using wild . . . . . . . . . . . B-1 Verb form scanner . . . . . . . 12-1 Version numbers - inputting . . 2-8 Version numbers - typing . . . . 2-3 Vscan . . . . . . . . . . . . . 3-2, 12-1, H-1 Wild . . . . . . . . . . . . . . 8-2 to 8-3, 8-5