Trailing-Edge
-
PDP-10 Archives
-
decus_20tap5_198111
-
decus/20-0151/setup.doc
There is 1 other file named setup.doc in the archive. Click here to see a list.
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 [<text>]
;Ask [/verify] <text>
| ;Begin [<name> [<text>]]
;Define Constant <constant-name> <text>
;Define Option <option-name> <text>
;Define [/allow][/default:"<text>"][/save][/verify] Variable
<variable-name> <text>
| ;End [<name> [<text>]]
;Error <text> [//<text>]...
| ;Error block [<name> [<text>]]
;File <file-spec> Found/<text>
;File <file-spec> Not-found/<text>
;Get [/define][/noecho] Option <option-name>
;Get [/define][/noecho] Variable <variable-name>
;If "<string1>" [not] = "<string2>"/<text>
;If "<string1>" [not] < "<string2>"/<text>
;If "<string1>" [not] > "<string2>"/<text>
;If "<string1>" [not] numeric/<text>
;Include [/begin] <filespec>
| ;Leave [<name> [<text>]]
;Option <option-name>/<text>
;No-option <option-name>/<text>
| ;Perform <file-spec> | block [<name>]
| <variable-name>=("<text>"[,"<text>"]...) ...
| ;Perform [/verify] <filespec> | block [<name>] <variable-name>
| [,<variable-name>[,<variable-name>]]=<filespec>[,<filespec>]...
;Select [/allow][/default:"<text>"][/save][/verify] Option
<option-name> <text>
;Select [/allow][/default:"<text>"][/save][/verify] Variable
<variable-name> ("<text>",...,"<text>") <text>
;Type [<text>]
where <text> refers to any string of characters including special
characters <option-name> 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 ">"); <constant-name> and
<variable-name> are any string of letters, digits and/or hyphens
beginning with "<" and ending with ">". <file-spec> is any valid Tops-20
filespec including structure, directory, filename and filetype and <name>
is a block name consisting of any combination of letters, digits and the
| hyphen character. <name> 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; "<filespec>" 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 <<variable-name>> might
be more consistent, but has been shortened to
simply <variable-name> 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 [<text>]
- - - - - - - - - - -
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] <text>
- - - - - - - - - - -
The ";Ask" command is used to ask the user the question contained in
the <text> 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 <text> 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:"<text>"] [/save] [/verify]
option <option-name> <text>
- - - - - - - - - - -
The ";Select option" command is used to ask the user which yes/no
options she wishes to use. The <text> describing the option is typed to
the user, then "<option-name> (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 <option-name>/<text>
- - - - - - - - - - -
The ";Option" command is used to specify that the following <text>
is to be left justified at the beginning of the line if the option
specified by <option-name> 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 <text> 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 <number> How many of this one?
If option this-one were selected, then the user would be prompted for a
value for the variable "<number>". If option this-one were not selected,
variable <number> would not be defined. Please see the additional
comments below under "Conditional Commands".
The <text> 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 <option-name>/<text>
- - - - - - - - - - -
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 <option-name> 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 <text> 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:"<text>"] [/save] [/verify]
variable <variable-name> <text>
- - - - - - - - - - -
The ";Define variable" command prompts the user for a value to
replace the string "<variable-name>" wherever that string appears in the
MCF following the ;Define command. The <text> is typed on the user's
terminal followed by "<variable-name>=". The user then types the value
of the variable. The string "<variable-name>" 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 <copies> How many copies of the eom report?
.
.
.
@Print eom.rpt/copies:<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 <Report-heading> What is the report heading?
Terminal typescript
What is the report heading?
<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:"<text>"] [/save] [/verify] variable
<variable-name> ("value1","value2",...,"valueN") <text>
- - - - - - - - - - -
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 <label-type> ("1-UP-STICKY","3-UP-STICKY",
"3-UP-HEATSEAL","1-UP-LARGE") What type of mailing labels do you want?
;Type You chose <label-type>
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
<label-type>=c
You chose 3-UP-HEATSEAL
CTL contents
;Select variable <label-type> ("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 <constant-name> <text>
- - - - - - - - - - -
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 "<constant-name>" is replaced
by "<text>" 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 <Smith> in several places, it can be changed by simply
defining the constant <Smith> to be a different directory!)
For example:
MCF contents
;Define constant <semester> FALL
.
.
.
@Run Update
*<semester>
.
.
.
@Print <semester>.rpt
CTL contents
;Define constant <semester> FALL
.
.
.
@Run Update
*FALL
.
.
.
@Print FALL.rpt
This example assumes that the constant <semester> 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 <current-day>, <current-month>, <current-year>,
| <current-user-name>, <current-hour>, <julian-date>, <job-id> and
<job-name> should not be used in a ;Define variable or a ;Define constant
SETUP %5(56) 20-May-80 Page 19
***** SETUP commands
command. <job-id> 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 <job-id> constant. The
constant <job-name> 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 <job-name> will have the value REPORT-GENERATION.
<Current-day>, <current-month>, <current-year> and <julian-date> are
defined to have the corresponding numeric values of day, month, year, and
| day-of-year respectively. <Current-hour> contains the 2-digit hour of
| the day and <current-user-name> 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 <option-name> <text>
- - - - - - - - - - -
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 <option-name> will be given the value "Y" or "N" depending upon
the first character of the <text>. For example,
;Define option <this-is-yes> yes
would have the same end result as the command
;Select option <this-is-yes> 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] <filespec>
- - - - - - - - - - -
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>
COURIER-DEFINITION.SCF
;Define constant <courier> 9900
MAIN.CTL
;Include courier-definition \PS:<DC00>COURIER-DEFINITION.SCF.1\
;Define constant <courier> 9900
; end of PS:<DC00>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 <filespec> found | not-found/<text>
- - - - - - - - - - -
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 <file-name> What file is to be processed?
;File <file-name> not-f/;Type Warning: this file is not present
In the previous example, the variable <file-name> 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 <text> 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 <text> 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 <abort> Should I abort this job?
;Option <abort>/;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 <text> may include double slashes to indicate more than one
logical line. When the <text> 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 [<text>]
- - - - - - - - - - -
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 <text> 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 <name> [<name>]
- - - - - - - - - - -
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 "<name>=<value>" 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 <fiscal-year> had been defined to be
"7980" with a Setup/variable command, the following MCF could be used:
MCF contents
;Get variable <fiscal-year>
@Copy GL<fiscal-year>.SEQ GLTEMP.SEQ
Terminal Typescript
<fiscal-year>=7980
CTL contents
;Get variable <fiscal-year> \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 "<string1>" [not] = | [not] < | [not] > "<string2>" /<text>
- - - - - - - - - - -
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 <text> at the beginning of a new line if
the specified condition is true. The defined conditions are <string1> is
equal to <string2> ("="), <string1> is less than <string2> ("<") or
<string1> is greater than <string2> (">"). 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 <variable> Enter the test value
;If "<variable>" not = "testval" /;Type You entered a bad value
Terminal typescript
Enter the test value
<variable>=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 <text> 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 <text> may include double slashes to indicate more than one
logical line. When the ;If command is true, the <text> 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 "<string>" [not] numeric /<text>
- - - - - - - - - - -
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 <text> 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 <text> will be placed on a new line if any
non-digit appears in the string. For example:
MCF contents
;Define variable <date> What is the report date (YYMMDD)?
;If "<date>" not numeric/;Abort Invalid date entered
Terminal typescript
What is the report date (YYMMDD)?
<date>=foo
?SETUP aborted: Invalid date entered
CTL contents (if ;Abort were not used)
;Define variable <date> \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 <text> [//<text>]...
| ;Error block [<name> [<comment>]]
| .
| .
| .
| ;End [<name>]
- - - - - - - - - - -
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 <text> 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 <filespec> <variable>=("<text>",...) [<variable>=...]...
| ;Perform block [<name>] <variable>=("<text>",...) [<variable>=...]...
- - - - - - - - - - -
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 <name> = ("file1","file2") <type>=("type1","type2")
SUB.SCF contents:
@Directory <name>.<type>
Will produce:
;Perform sub \PS:<DC00>SUB.SCF.1\ <name> = ("file1","file2"
) <type>=("type1","type2")
@Directory file1.type1
; end of PS:<DC00>SUB.SCF.1
@Directory file2.type2
; end of PS:<DC00>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 <name> = ("file1","file2") <type>=
| ("type1","type2")
| @Directory <name>.<type>
| ;End Dir
|
| Will produce:
| ;Perform block dir <name> = ("file1","file2") <type>=
| ("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> <variable>[,<variable>
[,<variable>]]=filespec[,filespec]
| ;Perform [/verify] block [<name>] <variable>[,<variable>
| [,<variable>]]=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 <input-file>=*.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 <input-file>
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 <input-file>,<file-id>=AD*.dat
would cause PRE-EDIT.SCF to be included once with the variable
<input-file> having the value "AD001.DAT" and the variable <file-id>
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<sequence-number>::
@Chkpnt EDT<sequence-number>
@Vdirectory <input-file>
@Copy <input-file> editin.seq
@Run Predit
!PREDIT reads file id for report title
*<file-id>
@Vdirectory predit.rpt
@Append predit.rpt pre-edit.report
@Delete predit.rpt,editin.seq
MAINT.MCF
.
.
.
;Perform pre-edit <input-file>,<file-id>,<sequence-number>
=AD*.DAT,DL*.DAT
.
.
.
CTL file
.
.
.
;Perform pre-edit \PS:<DC00>PRE-EDIT.SCF.5\ <input-file>,
<file-id>,<sequence-number>=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:<DC00>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:<DC00>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 [<name> [<comment>]]
|
| - - - - - - - - - - -
|
| 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 <sorted-report> Do you want a sorted report?
| ;Option <sorted-report>/;Select option <name-dept> -
| ;+ Do you want the name sort (yes) or the department sort (no)?
| ;Option <sorted-report>/;Option <name-dept>/ -
| ;+ ;Define constant <order> NAME
| ;Option <sorted-report>/;No-option <name-dept>/ -
| ;+ ;Define constant <order> DEPARTMENT
| ;No-option <sorted-report>/@Goto Nosort
| @Run SRTRPT
| *<order>
| @Print SRTRPT.PRT
| Nosort::
|
| Example 2: using blocks
| ;Select option <sorted-report> Do you want a sorted report?
| ;Option sorted-report/;Begin Sorted-report
| ;Select option <name-dept> Do you want the name sort
| (yes) or the department sort (no)?
| ;Option <name-dept>/;Define constant <order> NAME
| ;No-option <name-dept>/;Define const <order> DEPARTMENT
| @Run SRTRPT
| *<order>
| @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
| <name-dept> 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 [<name> [<comment>]]
|
| - - - - - - - - - - -
|
| 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 [<name> [<comment>]]
|
| - - - - - - - - - - -
|
| 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 <option-name>/<text>
and
;No-option <option-name>/<text>
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 <date> 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?
<date>=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 <date> 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 <date> were not asked but the ;Option command caused the option
sort to default automatically to a "no" answer and the variable <date> 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 <option-name>s following each ;Option and ;No-option
command until one of the <option-name>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 <form> What kind of forms?
The variable <form> 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 <form> 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 <option-name> following the ;Select will be treated in all
succeeding occurrences as if it were not selected. That is a
;No-option <option-name>/ would be successful but an ;Option
<option-name>/ would be ignored.
;S v - The <variable-name> will not be defined and the string
"<variable-name>" will not be replaced if it is found in the
MCF.
;D c - The ;Define constant command will be effectively ignored, and
the string "<constant-name>" 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 "<variable-name>" 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 <option-name> 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 <date> 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 <date> \10-22-52\ Insert your birth date?
;No-option a/;Define variable <copies> 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 <job-id> 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-<JOB-ID>.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 <job-id> 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 <job-id> constant defined by SETUP is the
<job-name> constant. The value of <job-name> is defined to be the name
of the MCF; in the preceding example, <job-name> 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 <test> This variable will not be defined
Step2::
;Option restart /;Type Terminal i/o will now resume
;Type The value of variable "test" is <test>
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
<test>=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>
[TEST.CTL.2 complete]
SETUP %5(56) 20-May-80 Page 45
***** Features
In addition to the option Restart, SETUP defines the option
RESTART-<tagname> to be yes where <tagname> 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-<tagname> "yes" for the tagname specified in the /TAG:
switch; "no" for any other <tagname>.
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:
<Current-day> The current two-digit numeric day of the month.
| <Current-hour> The 2-character hour of the day on a
| 24-hour time clock.
|
| <Current-month-name> The 3-character abbreviation for the
| name of the current month. (The first three
| characters of the month.)
<Current-month> The current numeric month of the year
(January = 01).
| <Current-user-name> The logged-in username of the job
| currently running SETUP.
<Current-year> The two-digit year of the century.
<Job-id> The value of the /JOB-ID: switch.
<Job-name> The filename of the MCF specified in the SETUP
command line.
SETUP %5(56) 20-May-80 Page 47
***** Features
<Julian-date> 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 <posting-date> -
;+ 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 <report-header> -
;+ 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 <detail-report> Do you want the detail report?
| ;Option <detail-report/;Begin Detail-report-block
| ;Select variable <order> ("NAME","SSN","DEPT") -
| ;+ Enter the sort order desired:
| ;Define variable <copies> How many printed copies?
| ;Select variable <form> ("NORMAL","XEROX") -
| ;+ Enter the output form desired:
|
| @Vdirectory input.fil
| @Run DTLRPT
| *<order>
| @Vdirectory dtlrpt.prt
| @Print dtlrpt.prt/copies:<copies>/form:<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 <detail-report> 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-file>=trans-in.*
| @Vdirectory <trans-file>
| @Empty-check <trans-file>
| ;Error @Journal "<job-name>-<job-id>: <trans-file> is
| empty"
SETUP %5(56) 20-May-80 Page 50
***** Features
| @Append <trans-file> transin.fil
| @Delete <trans-file>
| ;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
| <trans-file> 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 <trans-file>,<dummy>,<sequence>=*.trn
| @Vdirectory <trans-file>
| @Empty-check <trans-file>
| ;Error block Empty-trans
| @Journal "<job-name>-<job-id>: <trans-file>
| empty"
| @Delete <trans-file>
| @Goto Nextrn
| ;End Empty-trans
| @Run edttrn
| @Vdirectory edttrn.prt
| @Print edttrn.rpt/delete
|
| ;Select option <post-<sequence>> -
| ;+ Is <trans-file> to be posted after editing?
| ;Option <post-<sequence>>/;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 <trans-file>,<dummy>,<sequence>=*.trn
| @Vdirectory <trans-file>
| @Empty-check <trans-file>
| ;Error block Empty-trans
| @Journal "<job-name>-<job-id>: <trans-file>
| empty"
| @Delete <trans-file>
| @Goto Nextrn
| ;End Empty-trans
| @Run edttrn
| @Vdirectory edttrn.prt
| @Print edttrn.rpt/delete
|
| ;Select option <post-<sequence>> -
| ;+ Is <trans-file> to be posted after editing?
| ;No-option <post-<sequence>>/;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 <name>
| Variable <variable-name> defined as <value>
| Option <option-name> defined as <value>
| Reading file <filespec>
| Return from <filespec>
|
| 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 <Testing> This is a variable
|
| might generate the trace
|
| SETUP version 5(56) input from PS:<DC00>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 <Testing> :: ;Define
| variable <Testing> This is a variable
| Line 3 [ + 3]: Variable <Testing> defined as "value"
| Line 3 [ + 3]: Return from PS:<DC00>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 <Testing> 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 <Testing> This is a variable
|
| might generate the log
|
| SETUP version 5(56) input from PS:<DC00>TESTING.MCF.1 on
| 19-May-80 12:10:14
|
| Defined Variables:
| <Current-Day> "19"
| <Current-Hour> "12"
| <Current-Month-Name> "May"
| <Current-Month> "05"
| <Current-User-Name> "RS3M"
| <Current-Year> "80"
| <Job-Id> ""
| <Job-Name> "FOO"
| <Julian-Date> "140"
| <Testing> "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 <option-name> YES | NO
Setup/variable <variable-name> <value>
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 "<name>=Yes"
or "<name>=No". If /LIST VARIABLES is specified, all variable defaults
will be displayed in the form "<name>=<value>". /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 <name>
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 <copies> How many copies of the report?
| ;Define/allow variable <forms> What kind of forms for the
| report?
| ;Define/verify variable <date> What date goes on the report
| (mo-da-yr)?
| ;End Rpt1
@Journal "<job-name> 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
<date>
;Option rpt/;Ask Insert amount report should balance to; format 999.99
<copies>
;Option rpt/;Ask Which report phase a or b?
;Error @Journal "<job-name>: Error while producing report"//@Goto Eojx
@Print output.rpt/copies:<copies>/forms:<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?
<copies>=5
What kind of forms for the report?
<forms> [NORMAL]=
What date goes on the report (mo-da-yr)?
<date>=6-30-74
<date>=6-30-74
OK? n
What date goes on the report (mo-da-yr)?
<date>=6-30-79
<date>=6-30-79
OK? y
Insert amount report should balance to; format 999.99
567.89
Which report phase a or b?
b
[PS:<DC00>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:<DC00>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 <copies> \5\ How many copies of the report?
| ;Define/allow variable <forms> \NORMAL\ What kind of forms for the
| report?
| ;Define/verify variable <date> \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:<DC00>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:<DC00>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
"<job-name>" 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
(% <error>) 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 (? <error>) 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
<option-name>. The slash indicates where the <option-name> ends and
the text to be left justified begins.
SETUP %5(56) 20-May-80 Page 73
***** SETUP error messages
;File <filespec> 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 <text> 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 <text> 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 "<name>"
| A ;Leave command with a specific block name given was encountered
| within a block of a different name. "<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 "<name>" 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.