===== DCL Command File Parameters ===== DCL command file processing provides for as many as eight (8) com-line parameters in all versions of OpenVMS (V8.4 and above actually have 16 now), 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 [[symbol_substitution#string_substitution_examples|DCL Symbol Substitution - String Substitution Examples]] and [[symbol_substitution#command_file_parameters_p1_thru_p8|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. ==== Invoking DCL Scripts ==== * 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. ==== Com-Line Parameters ==== * 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|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"''. ==== Parameters Are Always Character Strings, Never Integers ==== * 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... ==== Parameters for Batch Jobs ==== 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") ==== But My Script Needs More Than 8 Parameters ==== 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. Specifically: - DCL_CTLFLAGS -- This is a VMS system parameter (controlled with SYSGEN, SYSMAN and/or AUTOGEN), thus requires the system administrator to decide whether or not to use/alter it, and if yes, then to implement the necessary change. If bit-3 of this bit-mask system parameter is set (asserted, meaning that its integer value will be greater than or equal to eight (>=8)), then DCL will permit the use of up to sixteen (16) command line parameters ''P1''...''P16'' rather than the traditional eight parameters. - Create explicit DCL code (programming) to turn one or more "ordinary" command line parameter(s) into a "compound parameter value," which the DCL code can "pick apart" and use. (**Note to system administrators**: If you consider using the DCL_CTLFLAGS approach, be sure to read the help text ''$ MCR SYSGEN HELP SYS_PARAMETERS DCL_CTLFLAGS'' in its entirety; and see the text for ''Bit 3'' specifically. If you elect to make this change for your system, be certain to include this parameter and its new value in your system's ''SYS$SYSTEM:MODPARAMS.DAT'' file so that it will be included in future AUTOGEN operations. In practice, this change is //rarely// justified and/or actually done; the value ''0'' is quite normal for this parameter on most VMS systems.) Here's an example of the second method, "compound parameter values": $ ! COMPOUND_PARAMETERS.COM $ ! $ ! Assume that com-line parameters P1..P7 are allocated and used $ ! for specific purposes in this script, but you need "a few more"... $ ! $ ! Make P8 function as a compound parameter: "val8;val9;val10;val11;..." $ ! $ ! ...Process parameters P1..P7 here... $ ! $ SEP = ";" ! the "separator character", here, a semicolon... (can be any single character you want) $ j = 0 ! initialize ("j" is a short-&-sweet name for an "index" variable) $CPLOOP1: $ arg'j' = F$ELEMENT( j, SEP, P8 ) $ IF ( arg'j' .EQS. SEP ) THEN GOTO CPCONTINUE1 ! =SEP character means no more elements in P8 $ ! ...else, got a good element/value from P8... $ ! ...so edit that element: Upcase it, remove leading/trailing space, compress multiple spaces $ arg'j' = F$EDIT( arg'j', "TRIM,COMPRESS,UPCASE" ) $ j = j + 1 ! since it's a good one, count it $ GOTO CPLOOP1 ! and try again... $ ! $CPCONTINUE1: $ ! At this point, we've got from zero (0) to j+1 elements extracted from P8 $ ! (j is our upper-limit)... $ ! Process these compound values (here, demo'd by just echoing them out to display): $ i = 0 ! another short&sweet index variable $ WRITE sys$output "Echo P8 compound parameter values:" $CPLOOP2: $ ! When i > j, we're done... $ IF ( i .GT. j ) THEN GOTO CPCONTINUE2 ! done with all compound parameters? $ ! ...nope, process the compound parameter (here, just display it): $ tmp = arg'i' ! makes single-tick substitution easy in the quoted-output: $ WRITE sys$output " ''tmp'" $ ! ...or, this works too: $ WRITE sys$output " ", arg'i' $ i = i + 1 ! next counted-element... $ GOTO CPLOOP2 $ ! $CPCONTINUE2: $ ! ...script continues here $ WRITE sys$output "" $ WRITE sys$output "...processing continues" $ WRITE sys$output "" $Done: $ EXIT 1 Then you could invoke (call) this script, //with more than 8 parameter values//, as follows: $ @COMPOUND_PARAMETERS value1 value2 value3 value4 value5 value6 value7 - "value8; value9; value10 is multiword; value11; value12" Echo P8 compound parameter values: VALUE8 VALUE9 VALUE10 IS MULTIWORD VALUE11 VALUE12 ...processing continues $ This approach has the benefit of being generally //portable// to other VMS systems //without// needing to involve other system admins in messing with the DCL_CTLFLAGS system parameter.