SETUP Documentation Alan Guenther (revised by Joe Payne 4-Jul-75) (revised by Ralph Swick 18-Oct-78 through 12-Oct-79) Third Revision This manual describes version 5(56) of the SETUP program released in March, 1980. This manual supersedes the previous manuals of 20-Jun-79 and 12-Oct-79. All changes to this manual since the previous edition are noted with a vertical bar in the margin. Updated 23-Jan-80: pages 4,8,9,13-16,26.1,54,56 Updated 16-May-80: pages 2,4,5,6,12,18,19,23,29-33,35-39,45,46, 49-54,58,59,62,77-79 The SETUP program was originally developed at the University of Montana and is distributed by Carnegie-Mellon University, Pittsburgh, Pennsylvania under the agreement that any modifications be communicated back to C-MU and that no such modified versions be distributed to other installations except by C-MU. SETUP %5(56) 20-May-80 Page 2 ***** Introduction Table of Contents I. Introduction 3 II. SETUP Editing Commands 4 Notation used in this manual 5 ;Type 7 ;Ask 8 ;Select option 9 ;Option 11 ;No-option 13 ;Define variable 14 ;Select variable 16 ;Define constant 18 ;Define option 20 ;Include 22 ;File 24 ;Abort 25 ;Get 26 ;If 27 ;Error 29 ;Perform for lists 31 ;Perform for files 33 | ;Begin 36 | ;End 38 | ;Leave 39 Conditional commands 40 III. SETUP Features 42 Job Identifier 42 Restarting jobs 43 | Control-C 45 Pre-defined options and variables 46 Line continuation 48 | Blocks 49 | Tracing and Logging 52 IV. Running SETUP from command level 55 Alternate uses of SETUP 57 V. MCF Example 59 VI. Example Dialog 61 VII. Resulting CTL File 62 VIII. Error Messages 65 SETUP %5(56) 20-May-80 Page 3 ***** Introduction ******Comments will be appreciated. I. Introduction SETUP is a program designed to facilitate the creation of frequently modified data processing batch job control files. SETUP uses a previously created master control file (MCF) and user responses to produce the batch control file (CTL). The MCF may contain yes/no options which the user may select, variables for which he may define arbitrary replacement values, and questions which she may answer by supplying whole lines of text. The principal benefit of such a program is that files prepared for use with it may be modified quickly, easily, and with less chance for error at job submission. Also, it does not require a skilled user to operate it effectively once the MCFs are created. SETUP is normally run interactively and, using special commands previously placed into the Master Control File, prompts the user for various yes/no options and for variable parameters to substitute for dummy parameters in the MCF. SETUP then creates the batch control file based upon these responses from the user. When SETUP is complete, the user must give a SUBMIT command to enter the batch control file into the batch processing queue. In addition to constructing batch job streams, SETUP provides facilities for controlling inter-job dependencies, handling job restarts, and consolidating common sequences of job steps into a minimum of disk files. SETUP also provides convenient methods for isolating occasionally-changed parameters such as year-end dates and semester names. SETUP allows the user to specify two types of fields for storing information. "Options" are fields that may have only one of the values "yes" or "no" (or "true" and "false"). "Variables" and "constants" are fields that may hold arbitrary text strings (character strings containing zero or more characters). Values for both options and variables may be set via user input or via other SETUP functions, however, values of constants are set without user interaction. SETUP %5(56) 20-May-80 Page 4 ***** SETUP commands II. SETUP editing commands SETUP ignores all lines in the MCF which do not start with a SETUP command after substituting the values of replacement strings. All lines in the MCF are copied to the CTL file, although those containing SETUP commands may be altered, thus the batch LOG file will show the SETUP commands and their result as well as the batch statements, providing for easier maintenance of the MCF and for better audit tracking. All the SETUP commands are of the form: ;Word ... where "word" is the command. All commands must be the first non-blank characters on a line and the command name must immediately follow the semicolon. With this syntax, all SETUP commands appear as comments to the batch system and are copied intact to the batch LOG file. The commands are: ;Abort [] ;Ask [/verify] | ;Begin [ []] ;Define Constant ;Define Option ;Define [/allow][/default:""][/save][/verify] Variable | ;End [ []] ;Error [//]... | ;Error block [ []] ;File Found/ ;File Not-found/ ;Get [/define][/noecho] Option ;Get [/define][/noecho] Variable ;If "" [not] = ""/ ;If "" [not] < ""/ ;If "" [not] > ""/ ;If "" [not] numeric/ ;Include [/begin] | ;Leave [ []] ;Option / ;No-option / | ;Perform | block [] | =(""[,""]...) ... | ;Perform [/verify] | block [] | [,[,]]=[,]... ;Select [/allow][/default:""][/save][/verify] Option ;Select [/allow][/default:""][/save][/verify] Variable ("",...,"") ;Type [] where refers to any string of characters including special characters is any string of letters, digits and/or hyphens SETUP %5(56) 20-May-80 Page 5 ***** SETUP commands optionally enclosed in parentheses("(" and ")"), square brackets ("[" and "]") or angled brackets ("<" and ">"); and are any string of letters, digits and/or hyphens beginning with "<" and ending with ">". is any valid Tops-20 filespec including structure, directory, filename and filetype and is a block name consisting of any combination of letters, digits and the | hyphen character. is a block name containing 1 to 36 letters, | digits or hyphens in any combination. All items in square brackets ("[" and "]") are optional and will modify the effect of the command if specified. If specified, they must be typed exactly as given without the square brackets, but may usually be abbreviated. All abbreviations of one or more characters are valid; for example, ;define variable may be abbreviated as ;def var or as just ;d v, though it is recommended that the full spelling be used in production MCFs to reduce effects of future enhancements to SETUP. It is also suggested that the exclamation point character be used to identify true comments in the MCF rather than semicolon, to avoid confusion between comments and SETUP commands. The SETUP commands are described in detail on the following pages. Notation All characters used in this manual must be typed exactly as shown. The following meta-symbols are used: [] An item enclosed in square brackets is optional but must be typed exactly as shown if used. If the item is another SETUP reserved word (i.e. not enclosed in other meta-symbols), then it may be abbreviated. <> An item enclosed in brackets is a generic term for a specific value that may be chosen by the user. For example; "" means the user should place in this position a valid TOPS-20 file specification. Generally, the actual value is not enclosed in angle brackets, however, in the special case of variable names the angle brackets are also required as part of the name. (That is, the notation <> might be more consistent, but has been shortened to simply for convenience). ... Ellipses indicate that the preceding element may be repeated one or more times. If a special delimiter (e.g. a comma) appears before the item, then it should be used to separate every SETUP %5(56) 20-May-80 Page 6 ***** SETUP commands occurrence of the repeated item. (space) Wherever a single space character is shown, one or more occurrences of space and/or tab characters may be used (in any combination). Generally, spaces and/or tabs may precede any occurrence of a slash ("/") and are not always indicated in this manual. SETUP %5(56) 20-May-80 Page 7 ***** SETUP commands ;Type [] - - - - - - - - - - - The ";Type" command is used to type arbitrary text to the user. The text is usually informative in nature to assist the user in selecting the options, defining the variables, and answering the questions given later in the MCF. The lines are typed in the same order as they appear in the master control file and any previously defined variables or constants appearing in the command will be substituted before the command is executed, thus showing the user their value. The following example illustrates the use of the ;Type command. MCF contents ;Type The options are: Alpha-sort, Account-sort, Dept-sort Terminal typescript The options are: Alpha-sort, Account-sort, Dept-sort Although a ;Type command normally specifies some text to be displayed, the command may be specified without any text in order to cause vertical paper motion. On a video terminal (e.g. VT52, Perkin-Elmer 1100, etc) a ;Type command without any text will clear the terminal screen. If a blank line is desired in all situations, a slash may be included after the command; for example, ;Type/ If line continuation (see page 40) is used in a ;Type command, the displayed text will be divided into separate lines as it appears in the MCF. SETUP %5(56) 20-May-80 Page 8 ***** SETUP commands ;Ask [/verify] - - - - - - - - - - - The ";Ask" command is used to ask the user the question contained in the and accept a one-line answer. The answer obtained is placed by itself on the next line following the question. The optional switch "/VERIFY" causes SETUP to repeat the question and display the user's response back on the terminal and request a yes/no verification that the response is correct. If the user responds "no", then the question is repeated and the user may correct his response. This cycle will repeat until the user responds "yes" to the verification request. If the /VERIFY switch is specified, it must immediately follow the command ;Ask (intervening spaces or tabs are permitted), and may be abbreviated to just /V. The prompt may contain a double slash ("//") anywhere within it and SETUP will display the text following the double slash on a new line. This may be used to display a columnar guide to the user for assistance in completing the response. The CTL file will contain the ;Ask command exactly as it appears in the MCF. For example: MCF contents ;Ask Please enter the option card//*|-start-||--end--||-date-| Terminal typescript Please enter the option card *|-start-||--end--||-date-| CTL contents ;Ask Please enter the option card//*|-start-||--end--||-date-| Line continuation (see page 40) may also be used to display multi-line prompts. It is strongly suggested that the response to ;Ask begin with one of the characters "@" or "*" as appropriate for the context, although SETUP will not enforce this standard. The response to ;Ask must contain at least one character. If the user wishes to enter a blank line, one or more spaces must be typed in the response. SETUP %5(56) 20-May-80 Page 9 ***** SETUP commands ;Select [/allow] [/default:""] [/save] [/verify] option - - - - - - - - - - - The ";Select option" command is used to ask the user which yes/no options she wishes to use. The describing the option is typed to the user, then " (y or n)? ". The user then must respond "y" (or "yes") if he wishes the option to be used or "n" (or "no") if not. Once the option is selected, its value is then tested with ;Option and ;No-option commands (see below). The following example illustrates the use of the ;Select command. MCF contents ;Select option Print-report Should the report file be printed? Terminal typescript Should the report file be printed? Print-report (y or n)? The optional switch "/ALLOW" in the command specifies that defaulting may be employed in responding to this command. That is; if a default value has been previously defined (see the discussion of Defining defaults in section IV), the user will be shown the default value and may take the default by typing only RETURN to the prompting message. In the following example, the default (yes) is shown in square brackets just before the question mark. MCF contents ;Sel/all opt Asort Do you want the report sorted alphabetically? Terminal typescript Do you want the report sorted alphabetically? Asort (y or n) [Y]? The optional switch "/DEFAULT:" specifies the "normal value" of the option. Its effect is identical to the /ALLOW switch with the difference that the default value is specified "in-line" in each MCF rather than externally in a special file of defaults. The default value is specified in quotes after the switch and must begin with one of the letters "y" or "n". The /DEFAULT: switch is preferred over /ALLOW when the option is "local" to a specific MCF rather than "global" to several MCFs; that is, if the same option is used in many MCFs and has the same meaning and normal response in all of these MCFs then the /ALLOW switch permits the default to be specified externally to the MCFs and provides a simple mechanism for making a single change to modify the default response for all the MCFs. When the option has no such over-all significance, then the /DEFAULT: switch is the preferred choice as it provides better "in-line" documentation for the MCF. The /DEFAULT: switch may not be used with either /ALLOW or /SAVE. SETUP %5(56) 20-May-80 Page 10 ***** SETUP commands The optional switch "/SAVE" in the command causes SETUP to save whatever response the user gives for the purpose of displaying it the next time a ;Select/save command is executed with the same option name. Thus, the switch will also cause the previously entered response to be displayed. Note that a response (either yes or no) must always be entered; that is, the response may only be defaulted if the /ALLOW switch is also specified. The following example illustrates the use of this switch. MCF contents ;Sel/save opt Full-report Do you want the full report this time? Terminal typescript Do you want the full report this time? Full-report (y or n) [N]? The optional switch "/VERIFY" after the word ;Select will cause SETUP to repeat the user's response and ask her to verify that it is correct by again typing "yes" or "no" (yes it is correct, or no it is not). If the user responds "no" (the previous response was not correct), SETUP will again display the prompting text and ask the user for the value of the option. This option-value/verify cycle will be repeated until the user responds "yes" to the verification request. Any switches specified must immediately follow the word ;Select (preceding spaces or tabs are allowed). Any combination of switches is permitted and all switches may be abbreviated to uniqueness; that is, /A, /S and /V. NOTE Any option that is not defined in a ;Select option or ;Define option statement will be treated as false ("no") if it is tested in an ;Option or ;No-option command. The option Restart is pre-defined by SETUP to be Yes if a /TAG: switch was given (see SETUP Features below) or No otherwise and thus should not be used in a ;Select option command. If the /ALLOW switch is specified, but no default value has been defined for the option (see "Defining defaults" in Section IV) then SETUP will not allow only a carriage return, but will require a yes or no answer. SETUP %5(56) 20-May-80 Page 11 ***** SETUP commands ;Option / - - - - - - - - - - - The ";Option" command is used to specify that the following is to be left justified at the beginning of the line if the option specified by has the value "yes". For example, if the control file contains: ;Option this-one/@Do this and option "this-one" was chosen in a ;Select option or ;Define option command then the resulting control file will contain: ;Option this-one/ @Do this If option "this-one" had the value "no", then the resulting CTL file would contain: ;Option this-one/@Do this (no change from the MCF) Note that the "left justification" is done by making the start a new line, following the philosophy that everything in the MCF should appear in the CTL file. Note also that if the option was selected, the remaining text is scanned again for a SETUP command as in ;Option this-one/;Define variable How many of this one? If option this-one were selected, then the user would be prompted for a value for the variable "". If option this-one were not selected, variable would not be defined. Please see the additional comments below under "Conditional Commands". The may contain several "logical" lines by inserting a double slash ("//") at the line boundaries. If the command is true (the option is yes), then SETUP will break the text into multiple physical lines wherever the double slashes are specified and then will remove the double slashes. For example: ;Option No-report/@Delete report.tmp//@Goto Next SETUP commands may not be specified following a double slash; that is, in order to execute two ;Type commands if the option Sort is yes, the MCF must specify ;Option Sort/;Type The report will be sorted on department ;Option Sort/;Type rather than on identification number SETUP %5(56) 20-May-80 Page 12 ***** SETUP commands CAUTION: Double slashes also should not be used if the command line contains multiple conditional commands in sequence. In this case, the double slashes are replaced when the first True condition is found without regard to a following test which might be False. The following example is an incorrect usage of double slashes. ;No r1/;No r2/@Del report.tmp//@Goto Rep3 In this example, the "@Goto Rep3" will appear on a new line if option r1 is no regardless of the value of option r2. In certain situations it might be convenient to do the following: ;No r1/;No r2/;Def opt no-r-12 yes ;Op no-r-12/@Del report.tmp//@Goto Rep3 | In this case, the ;Begin command can serve | the same purpose and leads to a "cleaner | looking" MCF. SETUP %5(56) 20-May-80 Page 13 ***** SETUP commands ;No-option / - - - - - - - - - - - The ";No-option" command is the converse of the ;Option command. The text following the "/" is placed at the beginning of the next line when the is not chosen as one of the options to be used. For example, if the control file contains: ;No-option this-one/@Do this and option "this-one" had the value "no", the control file will contain: ;No-option this-one/ @Do this If option "this-one" had the value "yes" the resulting control file would contain: ;No-option this-one/@Do this (no change from the MCF). Just as in ;Option, the may be another SETUP command and may include double slashes to define multiple physical lines (see the caution on the preceding page regarding multiple conditional commands in sequence). Please refer to the Conditional Command section below. SETUP %5(56) 20-May-80 Page 14 ***** SETUP commands ;Define [/allow] [/default:""] [/save] [/verify] variable - - - - - - - - - - - The ";Define variable" command prompts the user for a value to replace the string "" wherever that string appears in the MCF following the ;Define command. The is typed on the user's terminal followed by "=". The user then types the value of the variable. The string "" may appear anywhere in the master control file following the ;Define command, and all occurrences of the variable are replaced with the new value. Note that only the variable is replaced, nothing else on the line is touched. For example, one place a variable would be useful is in a PRINT command: ;Def var How many copies of the eom report? . . . @Print eom.rpt/copies:/forms:eom/delete If the user answered 5 to the "How many copies" question, the batch control file would contain: @Print eom.rpt/copies:5/forms:eom/delete The optional switches /ALLOW, /DEFAULT:, /SAVE and /VERIFY function in a manner very similar to their function in the ;Select command. The /ALLOW switch causes a default value to be displayed and the user may define the variable to be the default by typing only RETURN when prompted. For example: MCF contents ;Define/allow var What is the report heading? Terminal typescript What is the report heading? [Student Bill Summary]= Note that if no default value is defined (see page 43), then SETUP will always require the user to enter a value. The /DEFAULT: switch specifies a "normal value" for the variable that will be displayed just as for /ALLOW and may be entered by simply typing carriage-return in response to the prompt. The default value is specified in quotation marks following the switch. /DEFAULT: is preferred over /ALLOW when the variable is "local" to a specific MCF rather than "global" to several MCFs; that is, if the same variable is used in many MCFs and has the same meaning and normal response in all of these MCFs then the /ALLOW switch permits the default to be specified externally to the MCFs and provides a simple mechanism for making a single change to modify the default response for all the MCFs. When the variable has no such over-all significance, then the /DEFAULT: switch is the preferred choice as it provides better "in-line" documentation for SETUP %5(56) 20-May-80 Page 15 ***** SETUP commands the MCF. The /DEFAULT: switch may not be used in the same command with /ALLOW and /SAVE. The /SAVE switch causes SETUP to display the previous response to a ;Define/save variable command for the same variable and to save the current response to be displayed the next time a ;Define/save command is executed for this variable. Note that the user must always type a value unless the /ALLOW switch is also specified. If both /ALLOW and /SAVE are specified, then the previous value given for the variable may be used again by simply typing RETURN to the prompt. The /SAVE switch would be useful in an environment where the value of a variable must be incremented by 1 each time a job is submitted; SETUP will show the user the previous value, but will still require him to enter a value. The "/VERIFY" switch causes SETUP to repeat the user's response on her terminal and asks him to verify its correctness by typing either yes or no. If the user responds "no" (the previous response was not correct) then SETUP will display the prompting text again and give the user another opportunity to give the variable a value. This cycle will repeat until the user responds "yes" to the verification request. If switches are specified they must immediately follow the word ";Define" (intervening spaces or tabs are permitted). Any combination of switches is permitted and all switches may be abbreviated to uniqueness; e.g. /A, /S and /V. NOTE Unless the /ALLOW switch is specified the answer to a ;Define variable or a ;Select option may not be null. That is, there must be at least one character in the answer. If the user wants a blank for the answer to a ;Define variable command, he must type one. SETUP %5(56) 20-May-80 Page 16 ***** SETUP commands ;Select [/allow] [/default:""] [/save] [/verify] variable ("value1","value2",...,"valueN") - - - - - - - - - - - The ";Select variable" command provides a means to prompt the user for one of several possible choices for a variable. Whereas the ;Define variable command allows the user to provide a completely general replacement string for the variable, the ;Select variable command shows the user a list of values and asks her to choose one of them. The list of possible choices for the variable is enclosed in parentheses after the variable name and each individual choice is enclosed in quotation marks separated by a comma. SETUP will construct a tabular prompt from this list assigning a letter to each possible choice and ask the user to enter the letter corresponding to the value he wishes to choose. Up to 26 possible values may be given for each variable. The following example illustrates the use of the ;Select variable command. MCF contents ;Select variable ("1-UP-STICKY","3-UP-STICKY", "3-UP-HEATSEAL","1-UP-LARGE") What type of mailing labels do you want? ;Type You chose Terminal typescript What type of mailing labels do you want? A. 1-UP-STICKY B. 3-UP-STICKY C. 3-UP-HEATSEAL D. 1-UP-LARGE =c You chose 3-UP-HEATSEAL CTL contents ;Select variable ("1-UP-STICKY","3-UP-STICKY", "3-UP-HEATSEAL","1-UP-LARGE") \3-UP-HEATSEAL\ What type of mailing labels do you want? ;Type You chose 3-UP-HEATSEAL Notice that as for ;Select option and ;Define variable commands, SETUP inserts the selected value into the command line in the CTL file as well as substituting it for the variable name in following lines. The optional "/ALLOW" switch specifies that the user may use a previously defined default value by simply typing carriage-return in response to the prompt. SETUP will show the user the full default value (not the corresponding letter) in brackets just as for the ;Define variable command. Notice that it is possible for the default to not be included in the list of choices. SETUP %5(56) 20-May-80 Page 17 ***** SETUP commands The optional switch "/DEFAULT:" performs a function almost identical to /ALLOW. It specifies the "normal response" to the ;Select command and the user may choose this response by typing only a carriage-return when the prompt is issued. The "normal value" is specified in quotation marks immediately after the /DEFAULT: switch. /DEFAULT: is preferred over /ALLOW when the variable is "local" to a specific MCF rather than "global" to several MCFs; that is, if the same variable is used in many MCFs and has the same meaning and normal response in all of these MCFs then the /ALLOW switch permits the default to be specified externally to the MCFs and provides a simple mechanism for making a single change to modify the default response for all the MCFs. When the variable has no such over-all significance, then the /DEFAULT: switch is the preferred choice as it provides better "in-line" documentation for the MCF. The /DEFAULT: switch may not be used in the same ;Select command with /ALLOW and /SAVE. The optional "/SAVE" switch causes SETUP to save the actual value chosen by the user (not the corresponding letter). In addition, if a value was previously /SAVEd, SETUP will show the previous value in brackets. The optional switch "/VERIFY" causes the variable value to be displayed and the user is prompted for a yes/no answer as to whether the value is correct. If the response is "no", then SETUP will re-display the list and ask for another choice. SETUP %5(56) 20-May-80 Page 18 ***** SETUP commands ;Define constant - - - - - - - - - - - The ";Define constant" command fulfills a function very similar to the ;Define variable command. In the ;Define constant statement no prompt is typed to the user, but the string "" is replaced by "" wherever it appears in the MCF. The ;Define constant command would be useful in situations where the author of a MCF wanted to allow a simple method for changing a common parameter, but not require the SETUP user to type in a value every time the MCF is read. For example, a directory-name might be a constant so that it could be easily changed in the MCF at a later time. (A unique "trick" of constants follows from the fact that constant/variable names look like Tops-20 directory names: if the MCF contains the directory-name in several places, it can be changed by simply defining the constant to be a different directory!) For example: MCF contents ;Define constant FALL . . . @Run Update * . . . @Print .rpt CTL contents ;Define constant FALL . . . @Run Update *FALL . . . @Print FALL.rpt This example assumes that the constant changes periodically but remains fixed for long periods before being modified again. Using the ;Define constant command in this manner allows the periodic changes to be made quickly and with less chance for error. **** Note **** The special constants , , , | , , , and should not be used in a ;Define variable or a ;Define constant SETUP %5(56) 20-May-80 Page 19 ***** SETUP commands command. is automatically defined by the /JOB-ID: switch at exec command level. See section III SETUP features for a complete explanation of the /JOB-ID: switch and the constant. The constant is pre-defined by SETUP to be the file-name of the MCF, not including the file-type; thus, if the MCF is named REPORT-GENERATION.MCF will have the value REPORT-GENERATION. , , and are defined to have the corresponding numeric values of day, month, year, and | day-of-year respectively. contains the 2-digit hour of | the day and contains the logged-in username of the | current job. See Section III for more details. SETUP %5(56) 20-May-80 Page 20 ***** SETUP commands ;Define Option - - - - - - - - - - - The ";Define Option" command is very similar in function to the ;Define Constant command; that is, no prompt is issued, but the option given in will be given the value "Y" or "N" depending upon the first character of the . For example, ;Define option yes would have the same end result as the command ;Select option Please type "YES" here except that the second command would request the user to type something, and the first would not. This command might be useful to "recode" the user's previous responses rather than stringing out several ;Option and ;No-option commands (see the ;Option and ;No-option commands below). For example, if the sequence of tests ;Option opta/;Option optb/;Option optc/... were to be used several times, the MCF (and CTL file) could be made more concise by doing the following: ;Option opta/;Option optb/;Option optc/;Define option optabc yes ;Option optabc/... In this example, if any of the options "opta", "optb" or "optc" had the value "no", then option "optabc" would not be defined and therefore treated as having the value "no". ;Define option might also be used to reduce the number of prompts issued to the user; for example, ;Select option All-reports Do you want all the reports? ;Option all-reports/;Define option account-report yes ;Option all-reports/;Define option dept-report yes ;Option all-reports/;Define option ssn-report yes ;No-option all-reports/;Sel opt Account-report Do you want the account sequence report? ;No-option all-reports/;Sel opt Dept-report Do you want the department sequence report? ;No-option all-reports/;Sel opt SSN-report Do you want the social-security number sequence report? NOTE The options Restart, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday and Sunday should not be used in a ;Select option or ;Define option command. SETUP SETUP %5(56) 20-May-80 Page 21 ***** SETUP commands provides values for these options as defined in Section III. SETUP Features. ;Define option may also be used to set values for options that were not requested from the user due to a restart (/TAG: switch). See page 36, restarting jobs, for more details. SETUP %5(56) 20-May-80 Page 22 ***** SETUP commands ;Include [/begin] - - - - - - - - - - - The ";Include" command causes SETUP to process the entire text of another file as if it were present in the original MCF just after the ;Include command. All SETUP commands, program data, etc. in the included file will be placed into the CTL file just as for commands in the original MCF. The ;Include command could be used, for example, if several MCF procedures were to execute a common sort procedure and the system designer wanted to be able to modify that sort procedure in a single disk file rather than modifying all the MCF procedures that use that sort. The sort procedure could be written in a separate file and ;Include'd in each MCF that needed it. When SETUP executes an ;Include command it suspends processing of the original MCF, processes the entire ;Include'd file and then resumes processing the original MCF with the line following the ;Include command (which may be the end-of-file). If no device field is specified, the logical device MCF: will be used. If no file type is specified SETUP will first look for a file with the extension ".SCF" (Sub Control File). If this file does not exist SETUP will look for a file with the extension ".MCF". If neither file is found an error message will be printed and SETUP will abort the CTL file. ;Include commands may be nested to as many levels as desired; that is, an ;Include'd file may ;Include another file and so on. There is no limit to the number of files that may be ;Include'd in a single MCF. For example, MAIN.MCF ;Include courier-definition . . . @Print report.fil/courier: COURIER-DEFINITION.SCF ;Define constant 9900 MAIN.CTL ;Include courier-definition \PS:COURIER-DEFINITION.SCF.1\ ;Define constant 9900 ; end of PS:COURIER-DEFINITION.SCF.1 . . . @Print report.fil/courier:9900 Note that SETUP inserts the full filespec of the included file into the CTL file and indicates the last line of the included file with a comment. SETUP %5(56) 20-May-80 Page 23 ***** SETUP commands Included files may reference variables, constants and/or options that have been previously defined in the original MCF or in other ;Included files just as for statements in the original MCF. The optional switch /BEGIN will cause SETUP to execute this same ;Include command if the job is restarted at a tag following the ;Include/begin command via the /TAG: SETUP switch. This feature would be used in constructing a job that was to execute a series of commands once and only once each time it was submitted by the user, regardless of any batch CHKPNT commands in the job stream. In addition, these same commands should be executed in the job stream if the user submits the job at an alternate entry point (tag). SETUP will execute the ;Include/begin command normally, but will "remember" the filespec given. If the /TAG: switch was also given the same file will be included immediately following the specified tag in the CTL file. If another ;Include/begin command is executed before reaching the tag, then the old filespec is "forgotten" and replaced by the filespec in the current ;Include/begin command. The ;Include/begin command must be in the MCF prior to the tag it is intended to affect. The following example illustrates a situation in which the /BEGIN switch might be used. ;Include/begin Job-startup-procedure . . . ! Restartable here if machine now crashes Step2:: @Chkpnt Step2 . . . If the job restarts automatically at tag STEP2, it should not execute the contents of JOB-STARTUP-PROCEDURE.SCF; on the other hand, if a user submits the job manually to restart at tag STEP2, then the contents of JOB-STARTUP-PROCEDURE.SCF should be executed. | Occasionally it is desirable to terminate an ;Included file prior to | the physical end-of-file. In this case, the ;Leave command (without a | block name) may be used to simulate an end-of-file. Of course, the | ;Leave may be preceded by condition-testing commands to conditionally | terminate the ;Included file. SETUP %5(56) 20-May-80 Page 24 ***** SETUP commands ;File found | not-found/ - - - - - - - - - - - The ";File" command causes SETUP to look for the specified file and left-justify the text after the slash if the file is or is not present, depending on the option "found" or "not-found". The text may be another SETUP command, such as a ;Type command to give a warning message to the user that a necessary file is missing. If the command ";File ... not-found" is used and the file is present, then SETUP leaves the command untouched in the CTL file. Thus, the following commands would display the message "Warning: this file is not present" if the filename given by the user in response to the first prompt was not found. ;Define variable What file is to be processed? ;File not-f/;Type Warning: this file is not present In the previous example, the variable in the ;File command will be replaced by the value specified by the user for the ;Define variable command before SETUP executes the ;File command. Conversely, if the command ";File ... found" is used and the file specified exists, then the will be placed at the beginning of a new line. If the file does not exist, the entire line will be placed in the CTL just as it appears in the MCF. If the file specified in a ";File ... not-found" command is present and the is a ;Select option command, the option will not be defined (the command will not be executed) and thus the option will be treated as having the value "no" when tested later in the MCF. Thus, assuming the file test.dat was present, the commands ;File test.dat not-f/;Sel opt Should I abort this job? ;Option /;Abort TEST.DAT is missing would not abort SETUP. Conversely, the same result occurs if the file specified in a ;File .. found command is not present; the option will be treated as false. The file specification may be any valid TOPS20 filespec optionally including device and directory. Wildcard characters ("*" and "%") may be included if desired. The may include double slashes to indicate more than one logical line. When the is left-justified, it will be divided into physical lines at the double slash and the double slashes will be deleted. Please read the caution regarding multiple conditional commands in sequence at the end of the ;Option command description on page 11. SETUP commands may not follow a double slash. The default device is DSK:, the default directory is the user's connected directory. There are no defaults for file name and file type. If the file is in a different directory from the user's connected directory, then the ;File ... found command will fail (the file will be "not found") unless the user has read access to it. SETUP %5(56) 20-May-80 Page 25 ***** SETUP commands ;Abort [] - - - - - - - - - - - The ";Abort" command may be used to cause SETUP to not write a CTL file if certain circumstances are encountered. Such a situation might be a missing file from a ;File command or an inconsistent set of responses to several ;Select option commands. When this command is executed, SETUP will display the message "?SETUP aborted" and immediately terminate. If the optional is present, it will be displayed after the "?SETUP aborted" message. If the SETUP command is being executed from a .CMD file via the TAKE exec command, and the .CMD file contains a SUBMIT command following the SETUP command, the SUBMIT command will still be executed, but will fail with the message "?File not found". SETUP accomplishes an abort by deleting all generations of the CTL file before it begins reading the MCF file. This also means that there can never be more that one generation of the CTL file at any time. The name of the CTL file being created is a function of the name of the MCF and the value of the /JOB-ID: switch (see Section III SETUP features) and ;Abort ignores any other CTL files generated from the current MCF but with different job-identifiers. If the job is being restarted (via a /TAG: switch) and the ;Abort command is after the first batch tag in the MCF, but prior to the restart point then the ;Abort command will not be executed and SETUP will continue with the next line of the MCF. SETUP %5(56) 20-May-80 Page 26 ***** SETUP commands ;Get [/define][/noecho] option | variable [] - - - - - - - - - - - The ;Get command may be used to retrieve the default or /SAVEd value of an option or variable without user interaction. This provides another means of defining constant values of frequently used parameters similar to the use of the ;Include command to include a ;Define option or ;Define constant command. When SETUP retrieves the value of the option or variable, it displays a message of the form "=" on the terminal as a confirmation to the user. If the specified option or variable does not have a default value, SETUP will issue an appropriate message and ignore the ;Get command. For example, if the variable had been defined to be "7980" with a Setup/variable command, the following MCF could be used: MCF contents ;Get variable @Copy GL.SEQ GLTEMP.SEQ Terminal Typescript =7980 CTL contents ;Get variable \7980\ @Copy GL7980.SEQ GLTEMP.SEQ Note that SETUP includes the retrieved value in the CTL file in addition to displaying it on the user's terminal. The optional switch /DEFINE causes SETUP to retrieve the saved value of the first variable or option listed, but rather than defining the same name to have the retrieved value, the second variable or option is defined to have the value and the first name is left undefined. This might be used, for example, to compare the current value of a variable or option with its previous (default) value. The optional switch /NOECHO suppresses the displaying of the retrieved value on the user's terminal. It is recommended that this switch be used only when a later ;Type command will show the retrieved value to the user. SETUP %5(56) 20-May-80 Page 27 ***** SETUP commands ;If "" [not] = | [not] < | [not] > "" / - - - - - - - - - - - The ;If command provides a general way to test the value of constants and variables against other predefined values. ;If does a left-to-right string comparison of the two text strings given in quotation marks and places the at the beginning of a new line if the specified condition is true. The defined conditions are is equal to ("="), is less than ("<") or is greater than (">"). The sense of any of these conditions may be reversed by including the word "not" before the condition. The comparison is made using the ASCII collating sequence, with lowercase letters equivalent to uppercase letters and padding the shorter string on the right with spaces if necessary. The following example illustrates the use of this command. MCF contents ;Define var Enter the test value ;If "" not = "testval" /;Type You entered a bad value Terminal typescript Enter the test value =foo You entered a bad value Note that when the ;If command in this example is actually executed, the command will appear as ';If "foo" not = "testvalue" /;Type...' and will appear in the CTL file this way after the variable value is substituted. As in other conditional commands, if the test is false and the contains a ;Select option command, the specified option will be treated as false ("no"). If specified, the modifier "not" may not be abbreviated, but may be preceded and/or followed by any number of spaces or tabs. The may include double slashes to indicate more than one logical line. When the ;If command is true, the will be divided into physical lines where the double slashes are specified and the double slashes will be removed. Please read the caution on page 11. SETUP commands may not be specified following a double slash. Double slashes also should not be used when multiple conditional commands are used in sequence. SETUP %5(56) 20-May-80 Page 28 ***** SETUP commands ;If "" [not] numeric / - - - - - - - - - - - This form of the ;If command allows a variable value to be tested for non-numeric characters. The only characters that will pass the numeric test are the digits 0 through 9. If the string contains only these digits then the will be placed at the beginning of a new line; otherwise the line will remain unchanged. If the optional keyword "not" is included, then the will be placed on a new line if any non-digit appears in the string. For example: MCF contents ;Define variable What is the report date (YYMMDD)? ;If "" not numeric/;Abort Invalid date entered Terminal typescript What is the report date (YYMMDD)? =foo ?SETUP aborted: Invalid date entered CTL contents (if ;Abort were not used) ;Define variable \foo\ What is the report date (YYMMDD)? ;If "foo" not numeric/ ;Abort Invalid date entered Note that only the digits are considered to be numeric characters; leading or trailing spaces, minus signs, etc. will cause the string to be considered "not numeric". SETUP %5(56) 20-May-80 Page 29 ***** SETUP commands ;Error [//]... | ;Error block [ []] | . | . | . | ;End [] - - - - - - - - - - - The ;Error command causes SETUP to construct an "error block" of commands that will be executed when the job runs in the event that the preceding job command causes an error in the batch job. In the current implementation, ;Error is very similar to the batch @If (ERROR) command. The batch command, however, allows only a single command to be executed if an error occurs, and frequently it is desirable to execute multiple commands. SETUP provides a concise syntax for performing this function, making the MCF more readable. The following the command name are batch statements to be placed on separate lines within the error block. Two consecutive slashes in the ;Error command indicate where the command is to be broken into separate statements. The following example illustrates the use of this command. MCF contents . . . @Copy daily.fil trans.fil ;Error @Journal "Daily.fil does not exist"//@Goto Abort . . . CTL contents . . . @Copy daily.fil trans.fil ;Error @If (noerror) @Goto XX0001 @Journal "Daily.fil does not exist" @Goto Abort XX0001:: . . . Note that in the current implementation, SETUP inserts the batch converse command "@If (noerror)" to skip over the block. SETUP will construct a unique batch tag name for each ;Error command, thus removing the possibility of error in matching tag names and inadvertently skipping SETUP %5(56) 20-May-80 Page 30 ***** SETUP commands to the wrong part of the CTL file. It is strongly urged that the statements begin with one of the characters "@" or "*" as appropriate for the context, although SETUP will not enforce this standard. In order to make the MCF more readable, it is suggested that line continuation be used to indicate the logical line breaks. For example: ;Error - ;+ @Journal "FILE-MAINTENANCE.DAT is missing"//- ;+ @Delete work.fil//- ;+ @Goto Abort Note that even when line continuation is used it is necessary to include the double slashes to indicate line breaks. | The "block" keyword allows a block structure to be used in | formatting the commands to be executed upon an error rather than the line | continuation syntax. The previous example written as a block would | appear as follows: | | ;Error block No-maint | @Journal "FILE-MAINTENANCE.DAT is missing" | @Delete work.fil | @Goto Abort | ;End No-maint | | The keyword "block" and the ;End command define the commands to be | included in the error handling procedure. The optional block name after | the word "block" and after the ;End command serves as documentation to | match the start and end of the block. SETUP compares block names for | validation purposes as described under the ;End command. | | The block structure allows additional SETUP commands (such as | ;Option and ;No-option) to be used within the block. Refer to Section | III for a complete description of blocks. SETUP %5(56) 20-May-80 Page 31 ***** SETUP commands ;Perform =("",...) [=...]... | ;Perform block [] =("",...) [=...]... - - - - - - - - - - - The ;Perform command provides a function very similar to the ;Include command. Whereas the ;Include command only "inserts" the contents of another file into the text of the CTL file, the ;Perform command in addition allows substitution of the values of a list of variables used in that inserted file. The ;Perform command provides a means of inserting the same skeleton file into the CTL several times with differing values of several variables. The full syntax of the ;Perform command is: (1) the command ";Perform", (2) a TOPS-20 filespec (device and file type default to MCF: and .SCF or .MCF respectively), (3) one or more of (3a) variable name, (3b) equals sign, (3e) list of values to replace the variable, each value in quotes and the entire list in parentheses. For example: MAIN.MCF contents: ;Perform sub = ("file1","file2") =("type1","type2") SUB.SCF contents: @Directory . Will produce: ;Perform sub \PS:SUB.SCF.1\ = ("file1","file2" ) =("type1","type2") @Directory file1.type1 ; end of PS:SUB.SCF.1 @Directory file2.type2 ; end of PS:SUB.SCF.1 Note that the full filespec of the inserted file is displayed by SETUP on the command line in the CTL file, and that SETUP inserts a comment line indicating the end of the inserted file. If no file type is specified, SETUP will look for a file with the type ".SCF". If no such file exists, SETUP will look for a file with the type ".MCF". If neither file exists SETUP will display an error message and abort the CTL file. Currently, SETUP allows up to five variables to be listed in a ;Perform command. As for ;Include, ;Perform commands may be nested to any depth; that is, a ;Performed SCF may ;Perform another SCF. ;Perform and ;Include commands may both be used in the same MCF. After the ;Perform command is complete, the variables listed in the command will be left undefined and therefore may be used again in another ;Perform command. SETUP %5(56) 20-May-80 Page 32 ***** SETUP commands | The keyword "block" when used in place of a file specification | allows the text of the performed file to be written "in-line" in the MCF | rather than in an external file. The optional block name after the | keyword will be matched with a following ;End command to determine the | start and end of the block. The block structure would be used in cases | where the sequence of commands is executed only by this MCF and therefore | does not warrant being written as a separate disk file. | | The previous example written as a block would appear as follows: | | MAIN.MCF contents: | ;Perform block dir = ("file1","file2") = | ("type1","type2") | @Directory . | ;End Dir | | Will produce: | ;Perform block dir = ("file1","file2") = | ("type1","type2") | @Directory file1.type1 | ;End Dir | @Directory file2.type2 | ;End Dir | | The optional block name is used to document the start and end of a | particular block and is verified by SETUP as described under the ;End | command. | | Performed blocks may be nested just as performed files may be | nested. Refer to the description of blocks in Section III for a more | detailed explanation. SETUP %5(56) 20-May-80 Page 33 ***** SETUP commands ;Perform [/verify] [, [,]]=filespec[,filespec] | ;Perform [/verify] block [] [, | [,]]=filespec[,filespec] - - - - - - - - - - - This form of the ;Perform command includes another SCF for every occurrence of a disk file matching one of the file specifications listed following the equals sign. For example, to run a pre-edit program on all files whose names end in .DAT, the command might be ;Perform Pre-edit =*.dat In this example the contents of PRE-EDIT.SCF will be included in the CTL file once for every occurence of a file whose name ends in .DAT. Each time the contents of PRE-EDIT.SCF are read, the variable will be defined to have a new value, the value being one of the matching filenames. The first variable specified in the command will be defined to have the full file name, minus generation number, of the file matching the specification. This value will always include the filename and filetype and will include the structure and directory if they are not the user's connected structure or directory. A second variable may be given that will be defined to have the characters of the filename that match the wildcard characters (if any) in the file specification. For example, if the file AD001.DAT exists then the command ;Perform pre-edit ,=AD*.dat would cause PRE-EDIT.SCF to be included once with the variable having the value "AD001.DAT" and the variable having the value "001". SETUP determines the value of the second variable by comparing the specific file name with the matching filespec in the ;Perform command. The comparison is done left to right until the first mismatch is detected; next the names are compared right to left until a mismatch is found again. The value of the variable is all the characters between the first and second positions defined by these comparisons. Thus, the filespec may contain multiple wildcard characters and a unique value of the second variable will still be defined. (Note that if the wildcards are on opposite sides of the "." in the file name then the variable value will include the period also. If a structure and/or directory was specified in the command, then the determination of the second variable value will include these fields in the comparison; thus the specification "<*>MAINT.DAT" will retrieve all the directory names of the matching files as the values of the second variable. SETUP %5(56) 20-May-80 Page 34 ***** SETUP commands The third variable, if specified, will be defined to be a unique three-digit sequence number for every iteration of the included SCF. This sequence number starts at zero for each invocation of SETUP and is incremented every time a file is found matching the file specification in the command. This number is never reset, thus a second ;Perform will again increment this sequence number. The third variable may be used to construct unique tags for checkpointing purposes. If the optional switch /VERIFY is specified, SETUP will display the file name and request a yes or no response from the user prior to including the SCF for that file. If the user responds with "no", then SETUP will ignore the file and skip to the next matching file name. For the following example, assume the files AD054.DAT and DL068.DAT exist. PRE-EDIT.SCF EDT:: @Chkpnt EDT @Vdirectory @Copy editin.seq @Run Predit !PREDIT reads file id for report title * @Vdirectory predit.rpt @Append predit.rpt pre-edit.report @Delete predit.rpt,editin.seq MAINT.MCF . . . ;Perform pre-edit ,, =AD*.DAT,DL*.DAT . . . CTL file . . . ;Perform pre-edit \PS:PRE-EDIT.SCF.5\ , ,=AD*.DAT,DL*.DAT EDT001:: @Chkpnt EDT001 @Vdirectory AD054.DAT @Copy AD054.DAT editin.seq @Run Predit !PREDIT reads file id for report title *054 @Vdirectory predit.rpt @Append predit.rpt pre-edit.report @Delete predit.rpt,editin.seq ; End of PS:PRE-EDIT.SCF.5 EDT002:: SETUP %5(56) 20-May-80 Page 35 ***** SETUP commands @Chkpnt EDT002 @Vdirectory DL068.DAT @Copy DL068.DAT editin.seq @Run Predit !PREDIT reads file id for report title *068 @Vdirectory predit.rpt @Append predit.rpt pre-edit.report @Delete predit.rpt,editin.seq ; End of PS:PRE-EDIT.SCF.5 . . . If there are no existing files to match the specification in the ;Perform command, SETUP will print an error message and abort the CTL file. This error may be trapped by including a ;File command prior to the ;Perform command. When all matching filespecs have been found, the variables used in the ;Perform command are left undefined and may be used in a second ;Perform command. | The keyword "block" when used in place of a file specification | allows the text of the performed file to be written "in-line" in the MCF | rather than in an external file. The optional block name after the | keyword will be matched with a following ;End command to determine the | start and end of the block. The block structure would be used in cases | where the sequence of commands is executed only by this MCF and therefore | does not warrant being written as a separate disk file. | | The optional block name is used to document the start and end of a | particular block and is verified by SETUP as described under the ;End | command. | | Performed blocks may be nested just as performed files may be | nested. Refer to the description of blocks in Section III for a more | detailed explanation. As for ;Include and the variable-list format of ;Perform, the default device for the performed file is MCF: and the default file type is ".SCF". If the file type is defaulted and no file with the extension ".SCF" exists, SETUP looks for a file with the extension ".MCF". If neither file exists SETUP displays an error message and aborts the CTL file. SETUP %5(56) 20-May-80 Page 36 ***** SETUP commands | ;Begin [ []] | | - - - - - - - - - - - | | The ;Begin command defines the start of a block of lines in the MCF | written to execute a particular function. A line contained within the | block is treated just as every other line in the MCF; that is, the line | may be either a SETUP command to be executed or a line to be copied | verbatim to the control file. Variables, constants and options | referenced within a block will be treated exactly the same as outside a | block. | | The block structure is used after a conditional command (;Option, | ;No-option, ;If and/or ;File) to define an entire sequence of lines to be | analyzed if and only if the condition is true. This concept is | particularly useful when other SETUP commands are included in the block. | | The following example illustrates two forms of the same MCF, the first | without blocks and the second using the block structure. | | Example 1: without blocks | ;Select option Do you want a sorted report? | ;Option /;Select option - | ;+ Do you want the name sort (yes) or the department sort (no)? | ;Option /;Option / - | ;+ ;Define constant NAME | ;Option /;No-option / - | ;+ ;Define constant DEPARTMENT | ;No-option /@Goto Nosort | @Run SRTRPT | * | @Print SRTRPT.PRT | Nosort:: | | Example 2: using blocks | ;Select option Do you want a sorted report? | ;Option sorted-report/;Begin Sorted-report | ;Select option Do you want the name sort | (yes) or the department sort (no)? | ;Option /;Define constant NAME | ;No-option /;Define const DEPARTMENT | @Run SRTRPT | * | @Print SRTRPT.RPT | ;End Sorted-report | | In the second example, the lines following the ;Begin command up to | the ;End command will not be executed (in particular, the ;Select option | will not be executed) if the response to the first select is | "no". | | When a block is not executed, the control file will contain the | ;Begin and ;End commands but none of the lines between these two. All | SETUP commands will be ignored with the exception of other block SETUP %5(56) 20-May-80 Page 37 ***** SETUP commands | definition commands (i.e. ;Begin, ;Error block, ;Perform block) where | SETUP will further validate the inner block boundaries. Indentation may | be used as in the previous example to offset the contents of the block | and SETUP will remove the indentation (any number of spaces or tabs) | before writing the line(s) to the CTL file. | | An optional block name may be specified after the command to briefly | document the function of the block and to allow SETUP to compare block | names when the ;End command is reached. That is, if the corresponding | ;End command specifies a different block name than the current block | name, SETUP will print an error message. The block name also makes the | MCF easier to follow, as ;Begin and ;End commands can be more easily | matched. | | Following the block name, the MCF may contain a comment to further | document the function of the block. SETUP will copy the comment to the | CTL file, but otherwise ignore it. | | Refer to Section III for a more complete description of blocks. SETUP %5(56) 20-May-80 Page 38 ***** SETUP commands | ;End [ []] | | - - - - - - - - - - - | | The ;End command serves to document the end of a block that was | started with a ;Begin, ;Error block or ;Perform block command. If a | block name is specified, SETUP will compare the given name with the | current block name and print an error message if the names do not match | (un-named blocks are assumed to have an "empty" name and thus no name | will be permitted on the corresponding ;End command). | | Following the block name the MCF may contain a comment. SETUP will | copy the comment to the CTL file but otherwise ignore it. | | If no block name is specified, then the current block is ended | regardless of its name; that is, not specifying a block name effectively | defeats the block boundary validation performed by SETUP. | | Normally the ;End command is copied to the control file exactly as | it appears in the MCF, however, if the block being ended is nested within | another block that is not being executed (such as an ;Option .../;Begin | sequence) then the ;End command will not appear in the CTL file although | it will still be executed in order to validate the block boundaries. | | Refer to Section III for a complete description of blocks. SETUP %5(56) 20-May-80 Page 39 ***** SETUP commands | ;Leave [ []] | | - - - - - - - - - - - | | The ;Leave command causes SETUP to ignore the following line(s) of | the MCF until the end of the current block is reached. ;Leave may be | specified following a conditional command in order to suppress execution | of the remainder of a block in a specified circumstance. | | If a block name is specified on the ;Leave command SETUP will | compare the given name to the name of the current block and print an | error message if the names do not match. Following the name, the MCF may | contain a comment describing the reason for suppressing the remainder of | the block. SETUP will copy the entire line to the CTL file, ignoring the | comment. If the current block is un-named, then no name or comment may | be specified on the ;Leave command. | | The ;Leave command may also be used within ;Included or ;Performed | files to terminate processing of the file prior to the physical end of | the file. In this case, no block name or comment should be specified. | | Refer to Section III for a more complete description of blocks. SETUP %5(56) 20-May-80 Page 40 ***** Conditional Commands The ;Option / and ;No-option / commands may be used to reduce the amount of user dialog necessary to create the control file by selectively prompting for options and variables and/or effectively assigning default values to options. For example, in an older version of SETUP the following MCF: ;Select option rpt Do you want to produce the report? ;Select option sort Does the report file need sorting? ;Define variable What date goes on the report? would produce this dialog: Do you want to produce the report? rpt (y or n)? n Does the report file need sorting? sort (y or n)? n What date goes on the report? =none If option rpt did not need to be selected on this run then the next two lines of the MCF should not even be considered. To avoid these extra inquiries the MCF could be re-written to look like this: ;Select option rpt Do you want to produce the report? ;Option rpt/;Sel opt sort Does the report file need sorting? ;Option rpt/;Def var What date goes on the report? the user dialog would be: Do you want to produce the report? rpt (y or n)? n Since option rpt was not selected above, the questions concerning sort and were not asked but the ;Option command caused the option sort to default automatically to a "no" answer and the variable to not being replaced when encountered in the MCF. However, if rpt had been selected then the dialog would have been exactly the same as if there had been no ;Option commands present. Since ;Option and ;No-option commands can be nested to any level (limited only by the maximum length of a MCF line) the selection of options and definition of variables can be made to depend on which of several other options have already been defined. A logical AND is performed on all the s following each ;Option and ;No-option command until one of the s is false. In the following example: SETUP %5(56) 20-May-80 Page 41 ***** Conditional Commands ;Opt a/;No-opt b/;Opt c/;Def var
What kind of forms? The variable would only be defined if option a was selected, option b was not selected, and option c was selected. If any other condition were to exist for options a, b, or c then would not be defined. If the option-name in an ;Option command is not selected, or the option-name in an ;No-option command is selected, then options, variables, and constants will be handled as follows on commands given on the same line following the ;Option or ;No-option command: ;S o - The following the ;Select will be treated in all succeeding occurrences as if it were not selected. That is a ;No-option / would be successful but an ;Option / would be ignored. ;S v - The will not be defined and the string "" will not be replaced if it is found in the MCF. ;D c - The ;Define constant command will be effectively ignored, and the string "" will not be replaced if it is found in the MCF. ;D v - The ;Define variable command will be ignored just as ;Define constant and no attempt to replace "" in the MCF will be made. ;D o - The ;Define option command will also be ignored and the named option will default to the value "no". Normally each in the ;Option or ;No-option command has been previously selected in a ;Select statement, defined in a ;Define option statement, or been retrieved with a ;Get option statement, however, an option may be tested in an ;Option or ;No-option command without having been defined and the command will be executed as if the option were defined to be "no". SETUP %5(56) 20-May-80 Page 42 ***** Features III. SETUP features SETUP inserts the value of a selected option or a defined variable into the control file immediately following the option or variable. A backslash ("\") is used to delimit this value. For example if option a was selected and the variable was defined as 10-22-52 then the control file might look like this: ;Select option a \Y\ Want to run opt a? ;No-option a/;Select option b Want to run opt b? ;Define variable \10-22-52\ Insert your birth date? ;No-option a/;Define variable How many copies? This is very useful when trying to debug a MCF because the option and variable values appear just as they were selected and defined. - - - - - - - - - - - SETUP looks for the MCF file on logical device MCF: if no other device is specified. If this device is not defined, the message % MCF file not found will be printed and SETUP will abort. The file specification to SETUP may also include the directory in which the MCF file resides. The CTL file will always be written into the device DSK: (normally the connected directory). - - - - - - - - - - - SETUP processes the MCF in a single pass on a line by line basis. Therefore any options selected or constants and variables defined may be used immediately on following lines. - - - - - - - - - - - In many cases it is desirable to be able to submit several versions of the same job at once. For example, a reporting program may be run several times with different report options. SETUP always chooses the name of the CTL file it creates based upon the name of the MCF file it is reading. In addition, in order to make the ;Abort command function properly (see the description of this command in section II.) SETUP always deletes any previous generations of the CTL file before it begins writing the new file. Therefore, a facility exists to allow the same MCF file to be used to produce several different CTL files at the same time. This facility is the "/JOB-ID:" switch which may be given at the exec command level when SETUP is called (see section IV. Running SETUP). If /JOB-ID: is specified it may be followed by a 1-to-6 character word (any combination of letters, numbers and hyphens). This word will be appended to the name of the MCF file, separated by a hyphen, to produce the name of the CTL file. Thus, different /JOB-ID:'s may be used with the same MCF file to produce different CTL files. In addition to producing the name of the CTL file, the /JOB-ID: switch causes SETUP to internally execute a ;Define constant command where the value of the SETUP %5(56) 20-May-80 Page 43 ***** Features constant is the 1-word job-id specified. This allows the text of the MCF file to use the job identifier in any manner desired (as for example, a DELETE FOO-.CTL command at the end of the file). If no /JOB-ID: switch is specified at command level, then the CTL file name will be exactly the same as the MCF file name with the file type of .CTL, and the constant will have a null value. The following example assumes the file REPORT.MCF exists. @SETUP REPORT . . . (SETUP runs) . . . [REPORT.CTL.1 created] @ ---------------------------------------------- @SETUP REPORT/JOB-ID:ALPHA . . . (SETUP runs) . . . [REPORT-ALPHA.CTL.1 created] @ Corresponding to the constant defined by SETUP is the constant. The value of is defined to be the name of the MCF; in the preceding example, would be "REPORT". - - - - - - - - - - - It is frequently necessary (unfortunately) to restart long jobs from a checkpoint. In these cases, the normal user prompts issued from the MCF may not be entirely applicable (the job may have already completed the transaction edit step, for example so there is no point asking the user the name of the transaction file). To handle this situation, a /TAG: switch may be specified after the MCF name in the SETUP command line and SETUP will suppress all terminal activity occurring after the first occurrence of a batch label but before the specified tag. Thus, ;Ask, ;Define variable, ;Select option, ;Select variable ;Type and ;Abort commands will all be ignored. These commands will truly be ignored; that is, variables will not be defined and therefore not substituted and options will not be defined (and will therefore default to "no"). All commands not involving the terminal (e.g. ;Define constant, etc.) will be executed as normal. SETUP %5(56) 20-May-80 Page 44 ***** Features SETUP will also define the option RESTART to be "yes" if a /TAG switch was entered, and "no" otherwise. The option Restart may be used to control execution of other commands such as ;file that are not automatically suppressed by SETUP. Note that the option Restart is defined by SETUP when a /TAG: switch is specified to SETUP, not when a job is restarted automatically by the batch system. If SETUP reaches the end of the MCF without finding the specified tag, an error message will be issued and SETUP will abort the CTL file. The following example illustrates the use of the /TAG: switch. TEST.MCF ;Type This is an example of the use of the /TAG: switch ;Option restart /;Type Terminal i/o will now stop Begin:: ;Type This line will not be seen if /TAG: was specified ;Define variable This variable will not be defined Step2:: ;Option restart /;Type Terminal i/o will now resume ;Type The value of variable "test" is Terminal typescript @SETUP TEST SETUP version 5(56) This is an example of the use of the /TAG: switch This line will not be seen if /TAG: was specified This variable will not be defined =no tag The value of variable "test" is no tag [TEST.CTL.1 complete] - - - - - - - - - - - - - - - - - - - - - - - - - - - @SETUP TEST/TAG:STEP2 SETUP version 5(56) This is an example of the use of the /TAG: switch Terminal i/o will now stop Terminal i/o will now resume The value of variable "test" is [TEST.CTL.2 complete] SETUP %5(56) 20-May-80 Page 45 ***** Features In addition to the option Restart, SETUP defines the option RESTART- to be yes where is the tag specified in the /TAG: switch. This may be used as in the following MCF. . . . Step2:: . . . ;Select option Detail-report Do you want the posting detail? ;Option restart-dtlrpt/;Define option detail-report yes ;Option detail-report/;Include Detail-report . . . In this example, if the user specifies SETUP.../TAG:DTLRPT, then SETUP will not execute the ;Select command. Therefore the value of the option Detail-report would be "no". If the first ;Option command were not present then DETAIL-REPORT.SCF would not be included and the tag DTLRPT (which is inside DETAIL-REPORT.SCF) would not be found. The first ;Option command solves this problem by including DETAIL-REPORT.SCF when the user requests a restart a a tag within DETAIL-REPORT.SCF. | - - - - - - - - - - - | | If the user types control-C while SETUP is running, SETUP will | display the message "Yes?" and wait for the user to respond with either | "ABORT" or "CONTINUE". If the user types CONTINUE, SETUP will resume | processing at the point from which it was interrupted; that is, if it | was waiting for the response to a ;Define variable or a ;Select option | command, it will continue to wait for that response (without re-typing | the prompt). If the user types ABORT, then SETUP will immediately | execute an ;Abort command, thus discarding the CTL file that was being | built. | | When the "Yes?" prompt is displayed, the user may type "?" to get a | list of the possible responses. SETUP %5(56) 20-May-80 Page 46 ***** Features - - - - - - - - - - - Pre-defined options and variables SETUP provides several options and variables that may be referenced without executing a command that assigns a value (e.g. a ;Select or ;Define command). The pre-defined options are: Restart Restart has the value "yes" if a /TAG: switch was given on the SETUP command line and "no" otherwise. Restart- "yes" for the tagname specified in the /TAG: switch; "no" for any other . Monday has the value "yes" if the current weekday is a Monday; "no" otherwise. Tuesday "yes" if the current weekday is a Tuesday. Wednesday "yes" if the current weekday is a Wednesday. Thursday "yes" if the current weekday is a Thursday. Friday "yes" if the current weekday is a Friday. Saturday "yes" if the current weekday is a Saturday. Sunday "yes" if the current weekday is a Sunday. The pre-defined variables are: The current two-digit numeric day of the month. | The 2-character hour of the day on a | 24-hour time clock. | | The 3-character abbreviation for the | name of the current month. (The first three | characters of the month.) The current numeric month of the year (January = 01). | The logged-in username of the job | currently running SETUP. The two-digit year of the century. The value of the /JOB-ID: switch. The filename of the MCF specified in the SETUP command line. SETUP %5(56) 20-May-80 Page 47 ***** Features The three-digit julian day of the year (February 1st = 032). SETUP %5(56) 20-May-80 Page 48 ***** Features - - - - - - - - - - - Line continuation All logical lines in the MCF are limited to a maximum of 500 characters, regardless of whether or not they are SETUP command lines, however, it is often desirable to divide a single logical line into two or more physical lines in the MCF. Line continuation may be used to break long MCF lines at logical points in order to make the MCF more readable. Standard TOPS-20 commands may be divided into multiple MCF lines by simply typing a hyphen at the end of each line to be continued. Each continuation line should also begin with an "@" to indicate that it is to be read by the job at EXEC command level. SETUP command lines are continued in a similar fashion. Each line to be continued should end with a hyphen. The continuation lines should begin with a semi-colon and a plus sign. For example: ;Define variable - ;+ Enter the transaction posting date (MMDDYY) Line continuation may be used in a SETUP command anywhere between words; that is, anywhere a space or tab is legal in a SETUP command. The character string '(tabs or spaces), hyphen, new line, semi-colon, plus, (tab or space)' is treated by SETUP as a single occurrence of a space. Note that any number of tabs or spaces immediately before the hyphen and a single occurrence of a tab or a space after the plus-sign are included in the "line continuation syntax". When determining the total number of characters in a logical SETUP command, the continuation characters must be included; that is, you must add 5 to the actual count of characters for each continuation line. In most cases, the continuation characters will be removed from the logical SETUP command prior to executing the command and thus are transparent to the command itself. In certain cases, particularly where the continuation is in the middle of a prompt text string, the prompt will be divided into multiple lines on the user's terminal at the continuation break points. (Note that it is important here to remember that one space or tab character after the plus-sign will be "eaten up" by the continuation). Therefore, a multi-line prompt may be issued from a ;Define command as in the following example: ;Define variable - ;+ Enter the report heading; may be one of the following - ;+ Standard Account Report - ;+ Department Head Report - ;+ (or your own heading) SETUP %5(56) 20-May-80 Page 49 ***** Features | - - - - - - - - - - - | | Blocks | | The block concept in SETUP is used to define a sequence of lines | that perform a specific function. The block structure may be used to | cause that sequence to be executed more than once, and/or to be bypassed | entirely if certain conditions are satisfied. | | Blocks are defined by including one of the block start commands | ";Begin", ";Error block" and ";Perform block..." followed by any number | of lines and ending with an ";End" command. Blocks may be named or | un-named. When a named block is defined, SETUP provides a block | validation test. This test compares the name specified on the ;End | command with the name of the current block and prints an error message if | the names do not match. | | The most common use of blocks is to bypass sequences of SETUP | commands and control file data under certain pre-specified conditions. | For example, | | ;Select option Do you want the detail report? | ;Option ("NAME","SSN","DEPT") - | ;+ Enter the sort order desired: | ;Define variable How many printed copies? | ;Select variable ("NORMAL","XEROX") - | ;+ Enter the output form desired: | | @Vdirectory input.fil | @Run DTLRPT | * | @Vdirectory dtlrpt.prt | @Print dtlrpt.prt/copies:/form: | ;End Detail-report-block | | In this example the user is first asked whether or not s/he wants a | detail report produced this time. If the response is affirmative, SETUP | will then request the necessary information to produce the desired | report. If the reponse is negative, SETUP will ignore all the lines | following the command ";Begin Detail-report-block" until the command | ";End Detail-report-block" is reached. Note that SETUP commands and | control file data are ignored equally; it is not necessary to place | ;Option commands in front of the SETUP commands inside | this block. | | The second form of block usage is to repeat one or more commands several | times. For example, | | ;Perform block Append-transactions =trans-in.* | @Vdirectory | @Empty-check | ;Error @Journal "-: is | empty" SETUP %5(56) 20-May-80 Page 50 ***** Features | @Append transin.fil | @Delete | ;End Append-transactions | | In this case, the block of lines will be repeated once for every | file that matches the wildcard "trans-in.*" with the variable | being replaced with the name of a particular file. Note | that this same function could be executed with a ;Performed external file | but that the block structure provides better in-line documentation for | this MCF. The ;Performed file would be appropriate to use when the block | is to be executed in more than one MCF. | | The two examples shown give the text of the block indented with a | tab character. When the lines are copied to the control file, SETUP will | remove all tabs and spaces at the beginning of the line so that the line | is left-justified. The indentation in the MCF is not required, but is | suggested in order to make the MCF more readable. | | Whenever indentation is used, SETUP immediately removes the | indentation before any other operation; thus both SETUP and EXEC | continuation lines may be indented at any level (that is, the ";+" may be | preceded with any number of spaces and/or tabs.) | | Blocks may be nested; that is, a ;Begin command may be followed by | a second ;Begin command (or any other block definition command) prior to | the ;End command for the first block. In this case, SETUP simply saves | the name of the first block, executes the inner block normally (that is, | all the rules of matching block names are applied), and then restores the | first block name as the "current block name" when the inner block is | ;Ended. Nesting may be applied to any level; for example: | | ;Perform block Edit-trans ,,=*.trn | @Vdirectory | @Empty-check | ;Error block Empty-trans | @Journal "-: | empty" | @Delete | @Goto Nextrn | ;End Empty-trans | @Run edttrn | @Vdirectory edttrn.prt | @Print edttrn.rpt/delete | | ;Select option > - | ;+ Is to be posted after editing? | ;Option >/;Begin Post-trans | @Run psttrn | @Vdirectory psttrn.rpt | @Print psttrn.rpt/delete | ;End Post-trans | Nextrn:: | ;End Edit-trans SETUP %5(56) 20-May-80 Page 51 ***** Features | In this example, two blocks ("Empty-trans" and "Post-trans") were | nested within block "Edit-trans". Notice the use of the third variable | in the ;Perform command to construct a unique option-name on each | iteration of the block. (This technique will work only for options - it | will not work for variables or constants). | | Once a block is defined, it is sometimes desireable to suppress | processing of the remainder of the block if certain conditions are met. | The ;Leave command provides this capability. For example, the previous | example could also have been written as: | | ;Perform block Edit-trans ,,=*.trn | @Vdirectory | @Empty-check | ;Error block Empty-trans | @Journal "-: | empty" | @Delete | @Goto Nextrn | ;End Empty-trans | @Run edttrn | @Vdirectory edttrn.prt | @Print edttrn.rpt/delete | | ;Select option > - | ;+ Is to be posted after editing? | ;No-option >/;Leave Edit-trans | | @Run psttrn | @Vdirectory psttrn.rpt | @Print psttrn.rpt/delete | Nextrn:: | ;End Edit-trans | | Here the inner "Post-trans" block has been incorporated into the | "Edit-trans" block and is bypassed via the ;Leave command if the user | responds "no" to the ;Select command. Notice that the ;Leave command | suppresses only the remainder of the current iteration of the block; the | ;Perform command will continue to search for more files and will repeat | the block if another file matches the wildcards. | | ;Included and ;Performed files are very similar in concept to the | block structure. The primary difference is that the end of a file that | is ;Included or ;Performed is defined by the physical end-of-file; that | is, these files may not contain an ;End command to terminate processing | of the file. They may, however, use the ;Leave command to suppress | processing of the remainder of the file. | | If the ;Leave command is used to terminate an ;Include or ;Perform | file, it should not specify a block name. In fact, SETUP constructs a | block name for such files from the full file specification (including | generation number) of the file. In the event of an ;End within such a | file that was not matched by a block start command, SETUP prints an error | message that contains the file specification as the name of the current SETUP %5(56) 20-May-80 Page 52 ***** Features | block. | | The ;Begin, ;Leave and ;End commands may also contain a descriptive | comment after the block name if (and only if) the block name is | specified. This allows the programmer to further document the function | of the block. | | | - - - - - - - - - - - | | Trace and Log facility | | When initially debugging an MCF it is often difficult to determine | exactly what sequence of events occured while SETUP was running. | Mis-spelled variables, constants and options will cause much different | results than what was intended. | | For these reasons, the programmer can take advantage of the trace | facility in SETUP. When SETUP is run, it will test to see if the logical | name MCFTRACE: is defined. If this logical name is not defined, the | trace facility is disabled and MCF processing occurs normally. If, | however, MCFTRACE: is defined then SETUP will append to it lines that | indicate "events of special interest" while processing the MCF. | | The definition of logical name MCFTRACE: may include any of the | fields of a TOPS-20 file specification; that is, device, directory, file | name and file type. If only the device is specified (e.g. DEFINE | MCFTRACE: DSK:) the filename will default to SETUP.TRACE. The lines | appended to this file are of the form | | Line n [tag + o]: message :: text | | where 'n' is a physical line number that is incremented by 1 whenever | SETUP reads a line from the MCF, from an ;Included or ;Performed file or | repeats a line via a ;Perform block command; 'tag' is the last batch | label found in the MCF and will not be printed if no tag has been reached | yet; 'o' is the offset in physical lines after the indicated batch | label; 'message' is a SETUP message describing the interesting event | (listed below) and 'text' is the contents of the current MCF line | (possibly with some variable and constant substitutions already made). | | The messages that SETUP currently issues are: | | Undefined reference to | Variable defined as | Option defined as | Reading file | Return from | | The first message indicates an unrecognized variable or constant | name in context (that is, a string that looks like a variable or constant | but has no substitution value) or an undefined option in a ;Option or | ;No-option command. The second and third messages indicate definitions | of variables, constants and options. The last two messages indicate an SETUP %5(56) 20-May-80 Page 53 ***** Features | ;Include or ;Perform of another MCF. The final line will always be a | return from the original MCF. | | For example, the MCF | | ;Type Test MCF | ;Select option Testing This is an option | ;Define variable This is a variable | | might generate the trace | | SETUP version 5(56) input from PS:TESTING.MCF.1 on | 19-May-80 12:01:06 | | Line 2 [ + 2]: Undefined reference to Testing :: ;Select | option Testing This is an option | Line 2 [ + 2]: Option Testing defined as Yes | Line 3 [ + 3]: Undefined reference to :: ;Define | variable This is a variable | Line 3 [ + 3]: Variable defined as "value" | Line 3 [ + 3]: Return from PS:TESTING.MCF.1 | | The first trace message appears when SETUP checks to be certain that | option Testing does not already have a value. The undefined reference to | variable occurs when SETUP attempts to substitute a value for | what appears to be a variable immediately after reading the MCF line but | prior to executing the ;Define command. | | Other messages may be added to the trace facility as the occasion | warrants. | | | | | | The SETUP logging facility allows the user to keep a disk log of the | values entered to SETUP for all variables, constants and options for each | invocation of SETUP. If the logical name MCFLOG: is defined then, after | writing the CTL file, SETUP will append to the specified file a formatted | report listing all variables, constants and options that were given | values during this run. | | The SETUP log report will include all the SETUP pre-defined | constants and options in addition to those explicitly defined in the MCF | (in fact, this is a good, fast way to find out the pre-defined constants | if you forget them!). | | Just as for MCFTRACE:, the definition of MCFLOG: may include any | fields of a valid TOPS-20 file specification. If only the device is | specified, the file name will default to SETUP.LOG. Also, as for the | trace facility, if the specified file already exists then the new | information will simply be appended to the existing data. | | for example, the MCF SETUP %5(56) 20-May-80 Page 54 ***** Features | ;Type Test MCF | ;Select option Testing This is an option | ;Define variable This is a variable | | might generate the log | | SETUP version 5(56) input from PS:TESTING.MCF.1 on | 19-May-80 12:10:14 | | Defined Variables: | "19" | "12" | "May" | "05" | "RS3M" | "80" | "" | "FOO" | "140" | "value" | Defined Options: | Monday Yes | Testing Yes | | The first line appended to the trace and/or log files indicates the | SETUP version number, the full specification of the MCF file being read | and the current date and time. SETUP %5(56) 20-May-80 Page 55 ***** Running SETUP IV. Running SETUP from command level There are two very similar methods for running SETUP to produce the CTL file. The beginning user will probably want to use the "prompting" mode in which the full command recognition facilities of the TOPS-20 operating system are available. To run SETUP in this manner, the user simply types the command SETUP to the EXEC prompt ("@"). SETUP will then respond with it's name and version number and give the "SETUP>" prompt. The user may now type "?" at each field of the command line and SETUP will give a help message briefly describing what should be entered at that point. The ESCape key may also be used to complete a partial response if the response is unique among all the possible responses for that field (as in MCF file names, for instance). For example, a simple terminal session might look like the following: @setup SETUP Version 5(56) SETUP>? one of the following: SETUP SETUP>sETUP ? input filespec or one of the following /DELETE /LIST /OPTION /VARIABLE SETUP>sETUP fILE-MAINT.MCF.5 ? confirm with carriage return or one of the following: /JOB-ID: /TAG: SETUP>sETUP fILE-MAINT.MCF.5 /jOB-ID:? 1-word identifier for this job SETUP>sETUP fILE-MAINT.MCF.5 /jOB-ID:test ? confirm with carriage return or one of the following: /JOB-ID: /TAG: SETUP>sETUP fILE-MAINT.MCF.5 /jOB-ID:test In the preceding example, all lowercase commands were typed by the user, and all uppercase was typed by SETUP either as a prompt or in response to the ESCape key. All text after the question mark was typed by SETUP in response to the question mark. SETUP will proceed to read the MCF file when the user finally types a carriage-return. If the user makes a mistake before the carriage-return is typed, then the standard correction techniques apply; DELete (RUBout) to delete the last character typed, control-W to delete the last word, etc. If the user types carriage-return before he realizes the mistake, SETUP will likely give some erroneous error message, will repeat the command line as it read it, and then exit to exec command level (the "@" prompt). In most applications, the SETUP command line and the SUBMIT command will be executed from a command file such as with the TAKE exec command. In this case, the alternate form of running SETUP may be used to allow the MCF file name to be given from the command file and thereby not requiring the user to remember it. This form has exactly the same syntax as the preceding example, but the entire line in its final form is typed at exec command level just as if the SETUP> prompt had been given. Thus, SETUP %5(56) 20-May-80 Page 56 ***** Running SETUP the preceding example could have been typed as just @setup file-maint/job-id:test In this mode no recognition is available and the full file name of the MCF file must be specified (although the ".MCF" extension may be defaulted). The /JOB-ID: and /TAG: switches may, however, be abbreviated to just "/J:" and "/T:" respectively. Again, if there is an error in the command it may be corrected with DELete and control-W before carriage-return is typed and SETUP will give an error message and exit if any errors are detected. SETUP %5(56) 20-May-80 Page 57 ***** Running SETUP Alternate uses of SETUP In addition to running SETUP to generate a CTL file from a MCF, SETUP may be used to define default values for options and variables that are to be used in ;Select/allow, ;Define/allow commands and ;Get commands, to list the default and /SAVE'd values of all options and variables and to remove unneeded defaults. ---- Defining default values for options and variables Setup/option YES | NO Setup/variable The preceding two formats of the SETUP command line will define default values for, respectively, options and variables. Options may be given only the values YES or NO. Variable names must follow the standard format; that is, they must be enclosed in "<" and ">". ---- Listing default values of options and variables Setup/list [all | empty | options | variables] The /LIST switch of the SETUP command will list the contents of the default list for options and/or variables. If /LIST OPTIONS is specified, all option defaults will be displayed in the form "=Yes" or "=No". If /LIST VARIABLES is specified, all variable defaults will be displayed in the form "=". /LIST EMPTY gives a single line indicating the amount of free space in the default list file. If /LIST ALL or simply /LIST is specified, all the options, variables and free space will be listed. SETUP %5(56) 20-May-80 Page 58 ***** Running SETUP ---- Deleting defaults for options and variables Setup/delete option | variable The /DELETE switch of the SETUP command may be used to recover the file space taken by default values of options and variables that are no longer needed. This free space is not actually returned to the file system, but is retained for use by SETUP the next time an option or variable is to be stored. ---- Making the default list file accessible after aborting SETUP Setup/reset This command is an "emergency-only" command. If SETUP is aborted via control-C in certain critical sections, the default list file will be locked against modification. If the file is locked, SETUP will display the message ? SETUP.BIN file is in use by another job and will abort. If the user receives this message several times in succession, he should verify that there are no other jobs on the system connected to the same directory and running SETUP, then use the SETUP/RESET command to clear the lock on the file. If this command is used while another job is running SETUP in the same directory, it is likely that the default list file will be destroyed. | In newer versions of SETUP, typing control-C will cause SETUP to | issue the prompt "Yes?" to which the user may type either ABORT or | CONTINUE. In this case, SETUP will only allow the user to abort in | non-critical areas, thus control-C is no longer a dangerous feature to | use while running SETUP. SETUP %5(56) 20-May-80 Page 59 ***** MCF example V. An example of a master control file- SAMPLE.MCF ;Type S A M P L E . M C F ;Type This is a sample master control file. Its purpose is to ;Type demonstrate how the SETUP commands work and how they might be ;Type used in a MCF. ;Type ;Select/verify option maint Do you want to run the maintenance option? | ;Option maint/;Begin Maint1 | ;Type | ;Type The maintenance option requires that there be two | ;Type files present: | ;Type MASTER.NEW | ;Type TRAN.IN | ;File tran.in not-found/;Abort TRAN.IN is missing | ;End Maint1 ;No-option maint/;Select/allow option rpt Do you want to run the report phase? ;No-option maint/;No-option rpt/;Abort Neither maintenance nor reporting was selected | ;Option rpt/;Begin Rpt1 | ;Type | ;Type The report phase requires only that there be one | ;Type file present; MASTER.NEW and that it be in social security | ;Type number sequence. | | ;Select option sort Does the master file need sorting? | ;Define variable How many copies of the report? | ;Define/allow variable What kind of forms for the | report? | ;Define/verify variable What date goes on the report | (mo-da-yr)? | ;End Rpt1 @Journal " is now running" ;No-option maint/@Goto Sort @Error % @Directory MASTER.NEW,TRAN.IN | ;Error block NoFiles | @Journal "SAMPLE: All the files for maint. are not present" | @Please hold all jobs for this userid^[ | @Goto Eojx | ;End NoFiles @Error @Delete master.old @Rename master.new master.old @Run update ;Error @Journal "SAMPLE: Error while running maintenance phase"// - ;+ @Goto Eojx Sort:: ;Option sort/;Include sort-proc SETUP %5(56) 20-May-80 Page 60 ***** MCF example ;No-option rpt/@Goto Eojx Runrpt:: @Run Makrpt ;Option rpt/;Ask Insert amount report should balance to; format 999.99 ;Option rpt/;Ask Which report phase a or b? ;Error @Journal ": Error while producing report"//@Goto Eojx @Print output.rpt/copies:/forms:/delete Eojx:: @Set file protection master.*,tran.* 775252 @Logoff SETUP %5(56) 20-May-80 Page 61 ***** Operator dialog VI. The editing dialog to produce the CTL file from SAMPLE.MCF @SETUP SETUP version 5(56) SETUP>s sample S A M P L E . M C F This is a sample master control file. Its purpose is to demonstrate how the SETUP commands work and how they might be used in a MCF. Do you want to run the maintenance option? maint (y or n)? n maint n OK?y Do you want to run the report phase? rpt (y or n) [Y]? The report phase requires only that there be one file present; MASTER.NEW and that it be in social security number sequence. Does the master file need sorting? sort (y or n)? y How many copies of the report? =5 What kind of forms for the report? [NORMAL]= What date goes on the report (mo-da-yr)? =6-30-74 =6-30-74 OK? n What date goes on the report (mo-da-yr)? =6-30-79 =6-30-79 OK? y Insert amount report should balance to; format 999.99 567.89 Which report phase a or b? b [PS:SAMPLE.CTL.1 complete] SETUP %5(56) 20-May-80 Page 62 ***** Resulting control file VII. The resulting batch control file SAMPLE.CTL.1 ; SETUP version 5(56) input from PS:SAMPLE.MCF.1 ;Type S A M P L E . M C F ;Type This is a sample master control file. Its purpose is to ;Type demonstrate how the SETUP commands work and how they might be ;Type used in a MCF. ;Type ;Select/verify option maint \N\ Do you want to run the maintenance option? | ;Option maint/;Begin Maint1 | ;End Maint1 ;No-option maint/ ;Select/allow option rpt \Y\ Do you want to run the report phase? ;No-option maint/ ;No-option rpt/;Abort Neither maintenance nor reporting was selected ;Option rpt/ | ;Begin Rpt1 | ;Type | ;Type The report phase requires only that there be one | ;Type file present; MASTER.NEW and that it be in social security | ;Type number sequence. | | ;Select option sort \Y\ Does the master file need sorting? | ;Define variable \5\ How many copies of the report? | ;Define/allow variable \NORMAL\ What kind of forms for the | report? | ;Define/verify variable \6-30-79\ What date goes on the report | (mo-da-yr)? | ;End Rpt1 @Journal "SAMPLE is now running" ;No-option maint/ @Goto Sort @Error % @Directory MASTER.NEW,TRAN.IN | ;Error block NoFiles | @If (noerror) @Goto XX0001 | @Journal "SAMPLE: All the files for maint. are not present" | @Please hold all jobs for this userid^[ | @Goto eojx | ;End NoFiles XX0001:: @Error @Delete master.old @Rename master.new master.old @Run update ;Error @If (noerror) @Goto XX0002 @Journal "SAMPLE: Error while running maintenance phase" @Goto Eojx XX0002:: SETUP %5(56) 20-May-80 Page 63 ***** Resulting control file Sort:: ;Option sort/ ;Include sort-proc \PS:SORT-PROC.SCF.1\ @Sort *Sort/rec:100/key:1,9 master.new master.new ;Error @If (noerror) @Goto XX0003 @Journal "SAMPLE: Error during Sort" @Goto Eojx XX0003:: ; end of PS:SORT-PROC.SCF.1 ;No-option rpt/@Goto Eojx Runrpt:: @Run makrpt 6-30-79 ;Option rpt/ ;Ask Insert amount report should balance to; format 999.99 567.89 5 ;Option rpt/ ;Ask Which report phase a or b? b ;Error @If (noerror) @Goto XX0004 @Journal "SAMPLE: Error while producing report" @Goto eojx XX0004:: @Print output.rpt/copies:5/forms:NORMAL/delete Eojx:: @Set file protection master.*,tran.* 775252 @Logoff SETUP %5(56) 20-May-80 Page 64 ***** Resulting control file Things to note: The first line of the CTL file giving the version of SETUP and the complete MCF filespec was added by SETUP for ease in correcting any errors found. The full filespec of the ;Include'd file is given after the ;Include command, and a note is inserted after the last line of the ;Included file. If MCF:SORT-PROC.SCF did not exist, SETUP would have looked for the file MCF:SORT-PROC.MCF. The "Journal" command in the ;Included sort file uses the constant "" which was replaced by "SAMPLE" in the journal message. Note the effect of the /verify switch on the ;Select option and ;Define variable commands. SETUP %5(56) 20-May-80 Page 65 ***** SETUP error messages VIII. Error Messages The following is a list of all error messages that SETUP can generate. They are grouped by the SETUP command to which they refer. In each grouping the errors are divided into warnings and fatals. Warnings (% ) usually indicate some sort of syntactical error and in all cases SETUP will continue processing the MCF after listing and ignoring the line in error. Fatals (? ) usually indicate that the finiteness of SETUP has been violated and that parameters in the program or the command in the MCF will have to be changed. Command string errors % MCF file not found The specified MCF file does not exist on the given device/directory; possibly device MCF: is not defined or is defined to be a directory to which the user does not have access. % Directory full Your connected directory has too many files in it; there was not enough room to create the CTL file. % Quota exceeded or disk full The quota of disk space allowed for your connected directory has been reached while creating the CTL file. You may DELETE and EXPUNGE other files and CONTINUE without starting from the beginning. % Read access required The protection code of the MCF file does not allow you to read it; either the protection code must be changed or you must use the ACCESS system command. ? File not opened for reading The protection code of the MCF file does not allow you to read it, or you have forgotten to ACCESS a private structure. ? Error initializing command line parse This is a SETUP internal error. If it appears, notify the Administrative Systems Department. ? Unrecognized parameters at end of command A SETUP command has been given that has extraneous characters before the carriage-return that SETUP does not recognize as part of the immediately preceding field. Possibly due to a mis-spelled switch as in "SETUP FOO/JOBID:BAR" (should be .../JOB-ID:BAR). ? Invalid or missing option or variable name A SETUP/OPTION, SETUP/VARIABLE, or SETUP/DELETE command has been given without an option or variable name. SETUP %5(56) 20-May-80 Page 66 ***** SETUP error messages ? Option value is not YES or NO A SETUP/OPTION command has been given, but the word following the option name is not "yes" or "no". ? Invalid or missing variable name A SETUP/VARIABLE command has been entered without a variable name, or the specified variable name is not enclosed in "<" and ">". ? Invalid LIST option A SETUP/LIST command has been entered but the word following /LIST is not ALL, EMPTY, OPTIONS, or VARIABLES. ? No default value for this option/variable The option or variable name given in a SETUP/DELETE command was not found in the default list file. Possibly, a name was mis-spelled or the brackets ("<" and ">") around a variable name were not given. ? Invalid option after /DELETE switch The word following /DELETE in a SETUP/DELETE command was not OPTION or VARIABLE. SETUP %5(56) 20-May-80 Page 67 ***** SETUP error messages ;Select command errors % Incomplete SELECT command One or more of the required fields at the end of the ;Select command is missing. The word "option" or "variable", the option or variable name, and the prompting text must all be entered. % Unknown SELECT command The word "option" or "variable" is missing or misspelled after the word ;Select. % No text to describe SELECT option name The prompting text after the option name is missing. This text is required. % Option name too long in SELECT command Option names must be 36 characters or less. ? Exceeded option storage space The total length of the names of all the options has exceeded SETUP's internal storage. The names must be shortened or SETUP must be modified. % Invalid switch modifying SETUP command The only switches supported after a ;Select command are the /allow, /save and /verify switches. % Option name missing in SELECT command The option name in a ;Select command must immediately follow the word "option". % Option has already been selected The specified option has already been used in a previous ;Select or ;Get command. Options may not be "re-defined" in the current version of SETUP. % No value list for variable The list of possible variable values in a ;Select variable command must follow the variable name on the same line of the MCF. % Left paren missing in value list The list of possible variable values in a ;Select variable command must be enclosed in parentheses. % Invalid variable value in list Each of the values in the value list for a ;Select variable command must be enclosed in quotation marks and may not contain embedded carriage-return/line-feed characters. The values must be separated from each other with a single comma (surrounded by zero or more spaces or tabs). SETUP %5(56) 20-May-80 Page 68 ***** SETUP error messages % Too many values in list: cannot be more than 26 SETUP only allows up to 26 possible values in a ;Select variable command. % Response must be a single character in the range A to Q The user has entered a response of more than one character, or has entered a letter not given in the value list for a ;Select variable command. The letter "Q" will be the letter corresponding to the last entry in the list. ? Default value file has grown too large The new value of the option or variable cannot be /SAVEd because the default file has reached its maximum size. If the number of empty words (indicated by SETUP/LIST EMPTY) is very large, then the file should be rebuilt by listing the contents (SETUP/LIST), deleting SETUP.BIN and redefining all the values with SETUP/OPTION and SETUP/VARIABLE. % Switch missing after SETUP command SETUP has found a slash after a command indicating a switch, but no switch name. No spaces or tabs may be typed between the slash and the switch name. % /DEFAULT: switch not allowed in combination with /ALLOW and /SAVE Neither the /ALLOW nor the /SAVE switches may be used if the /DEFAULT: switch is specified. % Default value must be Y or N The quoted text after a /DEFAULT: switch in a ;Select option command must begin with either "y" or "n". % Value is required after this switch A quoted string must be specified after the colon on the /DEFAULT: switch. % Missing quote to delimit switch value The string following the colon on the /DEFAULT: switch must be enclosed in quotation marks. SETUP %5(56) 20-May-80 Page 69 ***** SETUP error messages ;Define command errors % No name specified in DEFINE command The constant or variable name is missing after the word "constant" or "variable" % Illegal first character in constant or variable Constant names and variable names must begin with "<". % Name is too long Constant, variable and option names must be less than 36 characters long. % No text describing name The prompting text is missing after the constant or variable name in a ;Define command. This text is required. % Incomplete DEFINE command The ;Define command was given without any other parameters. All parameters must be given on the same line as the word ;Define. % Unknown DEFINE command The word "constant", "option" or "variable" is missing or misspelled after the word ";Define". % Invalid variable or constant name: does not end with ">" A variable or constant name must begin with "<" and end with ">" and contain only letters, digits, and hyphens. ? Internal error: probably due to a variable value looking like another variable This message really means that SETUP has tried to define the same variable twice, however, this is situation not normally possible and can happen only when the value of a variable begins with "<", ends with ">" and matches another variable-name. ? Exceeded variable and constant storage space The total length of the constant and variable names and their replacement strings has exceeded SETUP's internal storage space. The names of the constants and variables should be shortened or SETUP should be modified. % The value may not be longer than 150 characters; please re-enter A variable value must be 150 characters or less. % A value must be entered for this variable The /ALLOW switch has not been given for this variable, so the user must type more than just carriage-return in response to the prompt for this variable. This message can also appear when the /ALLOW switch has been specified, but no default value was defined for the variable. SETUP %5(56) 20-May-80 Page 70 ***** SETUP error messages % No option name found after ;Define option command An option name must immediately follow the word "option" in a ;Define option command and must be entered on the same line. % No option value found in ;Define option command The option name must be followed by text beginning with either a "y" or "n" in a ;Define option command and must be entered on the same line. % Option value is not "y" or "n" The text following the option-name in a ;Define option command must begin with either the letter "y" or the letter "n". % Switch in ;Define command is only valid for ;Define Variable The programmer has entered a switch in a ;Define constant... or ;Define option..., command, neither of which is permitted by SETUP. % Invalid switch modifying SETUP command The only supported switches after a ;Define variable command are the /allow, /save and /verify switches. ? Default value file has grown too large The new value of the option or variable cannot be /SAVEd because the default file has reached its maximum size. If the number of empty words (indicated by SETUP/LIST EMPTY) is very large, then the file should be rebuilt by listing the contents (SETUP/LIST), deleting SETUP.BIN and redefining all the values with SETUP/OPTION and SETUP/VARIABLE. % Switch missing after SETUP command SETUP has found a slash after a command indicating a switch, but no switch name. No spaces or tabs may be typed between the slash and the switch name. % /DEFAULT: switch not allowed in combination with /ALLOW and /SAVE Neither the /ALLOW nor the /SAVE switches may be used if the /DEFAULT: switch is specified. % Value is required after this switch A quoted string must be specified after the colon on the /DEFAULT: switch. % Missing quote to delimit switch value The string following the colon on the /DEFAULT: switch must be enclosed in quotation marks. SETUP %5(56) 20-May-80 Page 71 ***** SETUP error messages ;Get command errors % Incomplete ;GET command A ;Get command has been entered without the word "option" or "variable" and the option/variable name. These must follow the word ";get" on the same line of the MCF. % Type is not OPTION or VARIABLE in ;GET command The word ;GET must be followed by one of "option" or "variable" in a ;Get command. % Name is missing in ;GET command The word "option" or "variable" in a ;Get command must be followed by the option or variable name on the same line of the MCF. % Variable name must be enclosed in "<" and ">" All variable names must begin with "<" and end with ">" and contain only letters, digits, and hyphens. % Variable does not have a default value The variable specified in a ;Get variable command has not been given a value with a SETUP/VARIABLE command or a ;DEFINE/SAVE VARIABLE command in an MCF. % Option does not have a default value The option specified in a ;Get option command has not been given a value with a SETUP/OPTION command or a ;SELECT/SAVE OPTION command in an MCF. % Invalid switch modifying SETUP command The only supported switches after the ;Get command are /DEFINE and /NOECHO. % Too many fields in ;Get command (missing "/DEFINE"?) SETUP has found a second option or variable name in a ;Get command where it was not expecting one. Only a single name may be given in the command unless the /DEFINE switch was specified to define the value of a second option or variable. % Switch missing after SETUP command SETUP has found a slash after a command indicating a switch, but no switch name. No spaces or tabs may be typed between the slash and the switch name. % No second option or variable name in ;Get/define command A second option or variable name is required when the /DEFINE switch is specified to receive the default value of the first option or variable name. SETUP %5(56) 20-May-80 Page 72 ***** SETUP error messages ;Include command errors % Invalid ;Include command The name of the file to be included was not specified on the same line following an ;Include command. % ;Include file not accessible: No file matching the specification given in an ;Include command was found. This error might be caused due to device MCF: being undefined. % Cannot open ;Include file The user does not have read access to the file given in an ;Include command. Possibly, the user forgot to ACCESS a private structure. % Invalid switch modifying SETUP command The only supported switch after the ;Include command is /BEGIN. % Switch missing after SETUP command SETUP has found a slash after a command indicating a switch, but no switch name. No spaces or tabs may be typed between the slash and the switch name. ;Option and ;No-option errors % Option name not specified The option name is missing after the word "option" or "no-option". The option name and prompting text must be entered on the same line as the command. % Option name too long Option names must be less than 36 characters long. % No slash '/' following option name The user has forgotten to put the delimiting slash after the . The slash indicates where the ends and the text to be left justified begins. SETUP %5(56) 20-May-80 Page 73 ***** SETUP error messages ;File found | not-found errors % File name missing in ;File command The programmer has forgotten to enter a file specification. The file specification must immediately follow the command on the same line. % Option missing in ;File command The file name must be followed by one of the options "found" or "not-found" on the same line of the MCF. % Invalid option in ;File command Only the word "found" or "not-found" may follow the file name. Possibly the option is mis-spelled. % No "/" following option in ;File command A slash must be entered after the "found" or "not-found" option in order to delimit the text to be left-justified. ;Ask errors % Answer may not be longer than 150 characters; please re-enter The answer the user has typed in response to the question has exceeded the maximum number of characters allowed. The current version of SETUP allows 150 characters for the response. % No text found following ;Ask command Some prompting text must be given in an ;Ask command. This text must be entered on the same line of the MCF as the command name. % No answer given; please give a response SETUP will not allow simply a carriage-return in response to an ;Ask command. If the desired response is a blank line, at least one space or tab must be typed. % Invalid switch modifying SETUP command The only supported switch after the ;Ask command is /VERIFY. % Switch missing after SETUP command SETUP has found a slash after a command indicating a switch, but no switch name. No spaces or tabs may be typed between the slash and the switch name. SETUP %5(56) 20-May-80 Page 74 ***** SETUP error messages ;Error errors % No text in ;Error command SETUP found an ;Error command with nothing following the command name. The ;Error command requires at least one batch statement that will be placed in the error block constructed by SETUP. ;If command errors % String missing in ;If command The ;If command must be followed by two quoted strings on the same line of the MCF. % Closing quotation missing on string in ;If command SETUP found the end of the MCF line before the closing quotation mark in one of the strings. Embedded carriage-returns are not permitted. % Incomplete ;If command The condition (=,<,>,NOT) must follow the first quoted string on the same MCF line. % Invalid condition type in ;If command The only supported conditions are "=", "<" and ">" possibly preceded by "not". % Slash missing to delimit text in ;If command A slash must be entered between the second string and the following text to delimit that text on the same line of the MCF. SETUP %5(56) 20-May-80 Page 75 ***** SETUP error messages ;Perform command errors % Filespec was not given The ;Perform command was not followed by the name of the file to ;Perform. The ;Perform command must be entered on a single line of the MCF. % Invalid filespec A filespec was found in the ;Perform command, but it is invalid, probably due to being longer than 39 characters. % ;Perform file not accessible The filespec given in the ;Perform command does not match any file on the system. Possibly the device MCF: is not defined. % Read access required to ;Perform file The file specified in the ;Perform command exists, but the user running SETUP does not have read access to it. % No variable name(s) given for ;Perform command The ;Perform command requires one or more variables to be replaced in the inserted file. The ;Include command may be used if no variables are to be substituted. % Invalid variable name specified in ;Perform command All variable names must begin with "<", end with ">" and contain less than 36 letters, digits and/or hyphens. % No variable value list specified in ;Perform command The equals sign and the corresponding list of replacement values must be entered on the same line of the MCF as the ;Perform command. % Equals sign missing in ;Perform command The variable name and the list of replacement values must be separated by an equals sign, optionally surrounded by spaces or tabs. % Left parenthesis missing before value list The replacement value list in a ;Perform command must be enclosed in parentheses. % Invalid variable value; beginning or ending quote missing Each replacement value in the ;Perform command must be enclosed in quotation marks and may not contain embedded carriage-return or line-feed characters. % Comma to delimit values is missing The values in the replacement list for a ;Perform command must be separated by commas and the entire list must be terminated with a right parenthesis. SETUP %5(56) 20-May-80 Page 76 ***** SETUP error messages % Right parenthesis missing at end of value list The list of replacement values in a ;Perform command must be enclosed in parentheses. % Variable value lists are not the same length If two or more variables are specified for replacement in a ;Perform command, the number of replacement values for each variable must be identical. % Too many variables specified for replacement Currently, SETUP allows only 5 variable names to be specified for replacement in a ;Perform command. ? Internal error: probably due to a variable value looking like another variable SETUP has attempted to define the same variable twice. This situation can occur only when the value of one variable exactly matches the name of another variable or constant. % No files match filespec in ;Perform command The file specification after the equals sign does not match any existing files on the disk. This error may be trapped with a ;File ... command if the circumstance is non-fatal. % Invalid file list in ;Perform command More than three variable names were given prior to the equals sign, or the file specification after the equal sign is not a valid TOPS-20 file specification. Also check for commas between all file specifications in the list if more than one filespec was given. % Invalid switch modifying SETUP command The only supported switch after the ;Perform command is /VERIFY. This switch may only be specified for a file-list form of the ;Perform command, not the value-list form. % No switches permitted in this form of ;Perform The value-list form of the ;Perform command does not have any switches. Only the file-spec form allows the /VERIFY switch. % Switch missing after SETUP command SETUP has found a slash after a command indicating a switch, but no switch name. No spaces or tabs may be typed between the slash and the switch name. SETUP %5(56) 20-May-80 Page 77 ***** SETUP error messages | ;Leave command errors | | | ? Cannot ;Leave top level of MCF | The master control file named on the SETUP command line as the | original input file to SETUP must be processed to the end-of-file; | that is, a ;Leave command may not be used to prematurely end | processing of this file. This error might also appear if a ;Leave | command without a block name is reached after the ;End command | defining the end of a block was processed. | | ? Cannot end or leave this block from block "" | A ;Leave command with a specific block name given was encountered | within a block of a different name. "" is the name of the | block currently being processed. | | ? Invalid block name | Block names must be 1 to 35 characters long containing only letters, | hyphens and digits. | | | | | | ;Begin command errors | | | ? Invalid block name | Block names must be 1 to 35 characters long containing only letters, | hyphens and digits. | | ? Push-down list overflow: Too many levels of nesting | This is a general error probably indicating too many levels of | nested blocks, ;Include or ;Perform commands. | | | | | | ;End command errors | | | ? Invalid block name | Block names must be 1 to 35 characters long containing only letters, | hyphens and digits. | | ? No block to ;End | An ;End command was found that did not match a corresponding ;Begin, | ;Error block or ;Perform block command. | | ? ;End command may not follow a conditional command | The ;End command may not be a part of the text of an ;Option, | ;No-option, ;File or ;If command; that is, the ;End command must | "stand-alone" on an MCF line. SETUP %5(56) 20-May-80 Page 78 ***** SETUP error messages | ? May not ;End an ;Include or ;Perform of a file | An ;Included or ;Performed file may only be terminated by the | physical end-of-file or by a ;Leave command. The ;End command is | reserved for blocks. Input-output errors ? MCF line too long The length of a line from the MCF has exceeded the internal processing storage area. SETUP allows a maximum of 500 characters on a line. % Undefined SETUP command A line beginning with a semi-colon was read from the MCF, but the word following the semi-colon was not a valid SETUP command. % Ambiguous SETUP command A line beginning with a semi-colon was read from the MCF and the word following the semi-colon is not an unambiguous abbreviation for a SETUP command. It is strongly suggested that abbreviations not be used in production MCFs, as all system software is dynamic and abbreviations are not guaranteed to remain unique over time. ? Error reading input file This is another one of those errors that should never occur. Try reading the file again; if the error persists contact the Administrative Systems Department. ? Error writing output file Another error that should never happen. If it persists contact the Administrative Systems Department. ? Specified tag not found in file The label given in a /TAG: switch does not exist in the MCF. Possibly the tag has been mis-spelled. ? Unable to create SETUP.BIN An unusual error occurring the first time a SETUP/OPTION, SETUP/VARIABLE, ;DEFINE/SAVE, or ;SELECT/SAVE command is executed. Possibly due to the connected directory having too many files. ? SETUP.BIN file is in use by another job An interlock for option and variable defaults has been set and not cleared by another job. Possibly due to another user using control-C while SETUP was trying to access an option or variable default. SETUP will try to access this file for 2 seconds before giving this message. SETUP %5(56) 20-May-80 Page 79 ***** SETUP error messages ? Cannot open SETUP.BIN An unusual error indicating a problem with the option/variable default file. Possible due to this file having been protected read-only to the current user. | ? Push-down list overflow: Too many levels of nesting | This is a general error probably indicating too many nested levels | of ;Include, ;Begin, ;Error block and/or ;Perform commands. % No continuation chars on continuation line (";+") SETUP has read an MCF line beginning with semi-colon and terminating with a hyphen, but the following line does not begin with a semi-colon and a plus-sign to complete the continuation syntax. | ? Block "" does not end | SETUP has reached the physical end of an MCF or SCF (;Included or | ;Performed file) without finding the end of a block that was started | in that file. All ;Begin, ;Perform block and ;Error block commands | must be matched by an ;End command in the same MCF or SCF.