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 13-Oct-80: pages 18-21,70 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(57) 13-Oct-80 Page 18 ***** SETUP commands | ;Define [/save] 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. | The optional switch /SAVE causes the value of this constant to be | "remembered" permanently so that it can be retrieved with a ;GET command | in a different MCF. This function is analogous to the /SAVE switch on | the ;DEFINE VARIABLE command except that a previously saved value is not SETUP %5(57) 13-Oct-80 Page 19 ***** SETUP commands | shown to the user. This command is also equivalent to the SETUP/VARIABLE | command described in section IV except that the constant value is | generated within the MCF and the constant name itself is defined and will | be substituted in the remainder of the MCF. **** Note **** The special constants , , , , , , and should not be used in a ;Define variable or a ;Define constant 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(57) 13-Oct-80 Page 20 ***** SETUP commands | ;Define [/save] 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? | The optional switch /SAVE causes the value of this option to be | "remembered" permanently so that it can be retrieved with a ;GET command | in a different MCF. This function is analogous to the /SAVE switch on | the ;DEFINE OPTION command except that a previously saved value is not | shown to the user. This command is also equivalent to the SETUP/OPTION | command described in section IV except that the option value is generated SETUP %5(57) 13-Oct-80 Page 21 ***** SETUP commands | within the MCF and the option itself is defined and may be referenced in | the remainder of the MCF. 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 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(57) 13-Oct-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 that is not supported. Currently only | the /SAVE switch may be used on these two commands. % 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.