PARSEC Technical Information

DCL command file processing provides for as many as eight (8) com-line parameters, which are used/known as local variables named P1, P2, P3, P4, P5, P6, P7 and P8 within the command file itself. Each of these local “parameter-variables” behaves exactly like any other programmer-created DCL local variables within the script, except for the fact that their initial values are picked up from what the user types on the command line when invoking (running) that script.

In the DCL examples on wiki-page DCL Symbol Substitution - String Substitution Examples and Command File Parameters P1 thru P8, you can see how P1 is used in the first FANCYSHOW.COM script; all 8 parameter-variables are demonstrated in the last COM_FILE_PARAMETERS.COM script.

What follows are the important things to know about DCL scripts and parameters.

• A command file is invoked (executed or run) by preceding its filename (or more complete filespec) with an at-sign “@”; for example, a script named EXAMPLE.COM:

$ @EXAMPLE

If that script is not located in your current working directory (see SHOW DEFAULT), then use as much device and/or directory/subdirectory file specification as needed to locate it:

$ @[-.CALEB.COMMANDS]EXAMPLE

…or:

$ @DISK$USER:[USERS.CALEB.COMMANDS]EXAMPLE

…and logical names work well too:

$ SHOW LOGICAL USER_COMMANDS
    USER_COMMANDS = "DISK$USER:[USERS.ALL.COMMANDS]" (LNM$SYSTEM_TABLE)
$ @USER_COMMANDS:EXAMPLE

With all these variations, we'll stick with the first, short form for what follows, just for brevity.

• Whenever a script is invoked ($ @EXAMPLE), the com-file's name can be followed with from one to eight parameters, separated by spaces (blanks).

• Each parameter (word) on that command line becomes the variable value (or contents) for the correspondingly numbered com-file parameter-variable within the script, from P1 up to P8.

$ @EXAMPLE value1 value2 value3 value4 value5 value6 value7 value8
$ ! becomes:  |      |      |      |      |      |      |      |
$ !           v      v      v      v      v      v      v      v
$ !          P1     P2     P3     P4     P5     P6     P7     P8
$ ! within the script...

• If more than one space (blank) character separates any two parameter values on the invoking command line, those multiple spaces are compressed (reduced) to a single space character, which does not alter or affect the positional mapping of values to their respective parameter-variables.

• In the absence of double-quotes surrounding any parameter value, each value is converted to UPPERCASE letters.

• These two steps are known as “command line normalization,” and are a normal part of DCL com-line parsing. See Symbol Substitution - Command File Parameters P1 thru P8 for practical examples.

• If lower/MiXeD/UPPERcase is to be preserved exactly, then those com-line parameter values must each be surrounded by double-quote marks “:

$ @EXAMPLE "lowercase" "MixedCase" upperCASE "UPPERCASE"

In the above example, the values of P1 and P2 will be “lowercase” and “MixedCase” respectively, but each value for P3 and P4 will be “UPPERCASE”.

• If a multi-word parameter value is needed/desired, surround the whole phrase in double-quotes – That double-quoted string becomes one parameter value:

$ @EXAMPLE "This is a test" "Another test"

Here, P1's value becomes “This is a test”, and P2's value becomes “Another test”.

• All parameters are treated as character strings – you cannot (directly) pass an integer as a parameter value:

$ @EXAMPLE 123 "45678"

With or without quotes, both of the above parameter values are character strings that just happen to contain digit-characters: P1's value is “123”, and P2's value is “45678”. However, if arithmetic is indeed the goal for either/both of these parameter variables, you can convert these character-strings (containing digit characters) to true DCL integer values using the F$INTEGER lexical function:

$ ! ...in the command file itself:
$ ival1 = F$INTEGER( P1 )
$ ival2 = F$INTEGER( P2 )
$ sum   = ival1 + ival2
$ ! or also:  $ sum = F$INTEGER( P1 ) + F$INTEGER( P2 )
$ WRITE sys$output "The arithmetic sum of the values is: ''sum'" 

yields this output:

The arithmetic sum of the values is: 45801

Note that if you attempt to just “add” P1 and P2 directly, you'll end up with string concatenation:

$ ! ...again, in the command file:
$ not_a_sum = P1 + P2
$ WRITE sys$output "Wrong! The arithmetic sum of the values is not: ""''not_a_sum'"""
$ WRITE sys$output "That is just a concatenated string of digit-characters..."

yields:

Wrong! The arithmetic sum of the values is not: "12345678"
That is just a concatenated string of digit-characters...

You know to execute a command file “interactively,” from the command line as seen above:

$ @UTILS:DISK_BACKUP dka0: now mkb300: verify

which will execute the command file DISK_BACKUP.COM from the UTILS: directory (likely a logical name), and passes four parameter values, “DKA0:”, “NOW”, “MKB300:” and “VERIFY” (all are UPCASED, because no quotes were used on any of the parameter values/words), which become P1, P2, P3 and P4, respectively, within the script.

You likely know how to run that same command file in a batch job, perhaps delaying it until sometime this evening when everyone's gone home for the day:

$ SUBMIT /AFTER=21:00 UTILS:DISK_BACKUP

But what if you need to provide parameters to that batch job when it runs? Certainly not like this:

$ SUBMIT /AFTER=21:00 UTILS:DISK_BACKUP dka0: now mkb300: verify
$ !                            wrong!---^^^^^ ^^^ ^^^^^^^ ^^^^^^

That's wrong syntax for the SUBMIT command… those “parameter words” will not be seen as actual parameter values in the SUBMIT command's syntax. Instead, you pass parameter values to the batch job like this:

$ SUBMIT /AFTER=21:00 UTILS:DISK_BACKUP /PARAMETER=(dka0:,now,mkb300:,verify)
$ !... or like this -- double-quoting continues to work for lowercase and/or multi-word values:
$ SUBMIT /AFTER=21:00 UTILS:DISK_BACKUP /PARAMETER=("dka0:","now","mkb300:","verify")

Normally, eight parameters P1…P8 is sufficient for almost any script/application, but sometimes you might need more. There are two ways to handle this – The first one requires the assistance (and approval) of your VMS system administrator; the second one you can just implement yourself.

TODO –

JOB_CTLFLAGS

compound parameter string