OpenVMS DCL: Single Command Batch Jobs
This sample code was the subject of “Single Command Batch Jobs”, the March 11, 2010 installment of The OpenVMS Consultant, a column on OpenVMS computing hosted by OpenVMS.org.
This example demonstrates how to expand the OpenVMS batch facility with an immediate mode akin to that provided by the DCL SPAWN command.
The three DCL command files comprising this example may be downloaded from this page. This files make use of a number of techniques, some of which have been featured in previous installments of The OpenVMS Consultant. For your convenience, the files have been packaged in a ZIP archive.
| LOGIN_SINGLELINEJOB.COM | This file, executed as part of the user login file (by default LOGIN.COM), system-wide login file (by default, SYS$MANAGER:SYLOGIN.COM), or manually by an individual user. It defines a global DCL symbol SINGLELINEJOB that may be used at a later point so submit a single command line for batch execution. |
| SUBMIT_SINGLELINEJOB.COM | When executed, this command file translates the supplied parameters and qualifiers into a request for batch execution of file RUN_SINGLELINEJOB.COM. A subset of the qualifiers accepted by the SUBMIT command is supported. |
| RUN_SINGLELINEJOB.COM | This file executes as the actual batch file. It receives the parameters provided to SUBMIT_SINGLELINEJOB.COM and uses them to execute the single command specified. |
The SUBMIT qualfiers supported by this procedure are:
- /AFTER
- /LOG_FILE
- /NAME
- /QUEUE
- /USER
The parameters are intended to be implemented to the same specification as documented for the conventional DCL SUBMIT command. The supported qualifiers are supplied to SUBMIT, which performs most of the validation.
If there are qualifiers that apply to the batch job, they must appear as the first parameter. For this reason, the qualifiers for SINGLELINEJOB.COM must be in a quoted string. This is required by DCL. The actual parsing of the qualifiers is done using a the F$ELEMENT and F$LOCATE lexical functions. Since the qualifiers all have unique leading strings, two checks are performed:
- the qualifier matches one of the supported qualifiers
- and any characters beyond the leading two characters are not inconsistent
This is precisely the usage described in “Pitfalls of F$LOCATE and other Functions”.
|
$! Initialize the list of qualifiers, and the name of the $! log file. $ VALID_QUALIFIERS = "/AF/LO/NA/PR/QU/US/" $ VALID_FULL_QUALIFIERS = - "/AFTER/LOG_FILE/NAME/PRINT/QUEUE/USER/" . . . $! $! If the first parameter contains a list of qualifiers, $! parse the list. Since the validity of the options will $! also be checked when the SUBMIT is executed, this $! parsing is limited to separating the various elements $! qualifiers(e.g., and values) so that the SUBMIT command $! can be constructed. All decisions are deferred to the $! actual normal validation processing done as part of $! SUBMIT. $ NEXT_QUALIFIER: $ NEGATED_QUALIFIER = 0 $ QUALIFIER_TERM = - F$ELEMENT(QUALIFIER_COUNT, "/", COMMAND_QUALIFIERS) $ IF QUALIFIER_TERM .EQS. "/" THEN GOTO EXECUTE_SUBMIT $ QUALIFIER_VERB = - F$EDIT(F$ELEMENT(0, "=", QUALIFIER_TERM), "UPCASE") $ QUALIFIER_PARAMETER = F$ELEMENT(1, "=", QUALIFIER_TERM) $ IF QUALIFIER_PARAMETER .EQS. "=" THEN - QUALIFIER_PARAMETER = "" $ IF F$EXTRACT(0, 2, QUALIFIER_VERB) .EQS. "NO" $ THEN $ NEGATED_QUALIFIER = 1 $ QUALIFIER_VERB = - F$EXTRACT(2, F$LENGTH(QUALIFIER_VERB)-2, QUALIFIER_VERB) $ ENDIF $! $ IF (F$LOCATE("/"+F$EXTRACT(0, 2, QUALIFIER_VERB), VALID_QUALIFIERS) - .EQ. F$LENGTH(VALID_QUALIFIERS)) $ THEN $ EXIT 229952 ! Exit with CLI$_IVQUAL $ ENDIF $! $! Since the first two characters of the supported qualifiers $! are unambiguous, the remainder of the each qualifier can $! also be validated as a string containing no characters $! inconsistent with the fully spelled qualifier (e.g., "LO", $! "LOG", "LOG_FILE", and "LOG_F" are all permissible; "LOGFILE" $! will not be accepted). $ IF (F$LOCATE("/"+QUALIFIER_VERB, VALID_FULL_QUALIFIERS) - .EQ. F$LENGTH(VALID_FULL_QUALIFIERS)) $ THEN $ EXIT 229952 ! Exit with CLI$_IVQUAL $ ENDIF |
Accumulating the information from the qualifiers requires different processing for each qualifier. This is accomplished using a GOSUB with the two character unique leading string of already validated qualifiers as a GOTO-index. With the substitution of the GOSUB in the place of the GOTO, this is technique is as described in “DCL Computed GOTO”. Since the qualifier has already been validated, there is no need for a separate validity check.
|
$! $! Use the first two characters in each qualifier as the $! index term in a DCL Computed GOTO (see $! http://www.rlgsc.com/demonstrations/dcl_goto.html). $! Range checking is not needed, as the qualifier has $! already been validated. $ GOSUB PROCESS_'F$EXTRACT(0, 2, QUALIFIER_VERB)' $ QUALIFIER_COUNT = QUALIFIER_COUNT + 1 $ GOTO NEXT_QUALIFIER . . . $! $! GOSUB Subroutines to process command qualifiers $! $ PROCESS_AF: $ STRING = "AFTER" $ IF NEGATED_QUALIFER THEN STRING = "NOAFTER" $ DCL_QUALIFIERS = DCL_QUALIFIERS + "/''STRING':" + - QUALIFIER_PARAMETER $ RETURN $! . . . |
The use of GOSUB/RETURN keeps the procedure within one symbol scope and eliminates the need for a reverse GOTO after processing each qualifier.
Lastly, the actual SUBMIT processing uses F$PARSE to ensure hierarchical defaulting of the name for the logfile. This allows the procedure to easily generate the logfile name equal to the jobname, unless the user has overridden this default with the /LOG_FILE qualifier.
|
$! $! Compute the name for the logfile and actually invoke SUBMIT. $! Report the results of the SUBMIT to our caller (success, $! failure). $ EXECUTE_SUBMIT: $ COMMANDFILE_DIRECTORY = F$PARSE(F$ENVIRONMENT("PROCEDURE"),,,- "DEVICE") + - F$PARSE(F$ENVIRONMENT("PROCEDURE"),,,"DIRECTORY") $ LOGFILE_FULLNAME = F$PARSE(LOGFILE_NAME, LOGFILE_DEFAULTNAME, - "[]SINGLELINEJOB.LOG") $ SUBMIT /LOG_FILE='LOGFILE_FULLNAME'- 'DCL_QUALIFIERS'- /PARAMETER=("''F$ENVIRONMENT(""DEFAULT"")", - "''COMMAND'",- "''COMMAND_PARAMETER_P1'",- "''COMMAND_PARAMETER_P2'",- "''COMMAND_PARAMETER_P3'",- "''COMMAND_PARAMETER_P4'",- "''COMMAND_PARAMETER_P5'",- "''COMMAND_PARAMETER_P6'"- )/NOPRINT 'COMMANDFILE_DIRECTORY'RUN_SINGLELINEJOB.COM $ EXIT $STATUS |
References
- Robert Gezelter “Single Command Batch Jobs: An Alternative to SPAWN or Command Files” The OpenVMS Consultant, OpenVMS.org, March 11, 2010, Retrieved from http://www.openvms.org/stories.php?story=10/03/11/9934878 on March 11,#2010.
- Robert Gezelter “DCL Computed GOTO” The OpenVMS Consultant, OpenVMS.org, June 9, 2009, Retrieved from http://www.openvms.org/stories.php?story=09/06/09/3479252 on March 11,#2010.
- Robert Gezelter “DCL Symbols: Starting at the beginning” The OpenVMS Consultant, OpenVMS.org, March 2, 2009, Retrieved from http://www.openvms.org/stories.php?story=09/03/02/8398294 on March 11,#2010.
- Robert Gezelter “Pitfalls of F$LOCATE and other Functions” The OpenVMS Consultant, OpenVMS.org, March 31, 2003, Retrieved from http://www.openvms.org/stories.php?story=03/03/31/6547431 on March 11,#2010.
- Robert Gezelter “Logical Names: Part 5” The OpenVMS Consultant, OpenVMS.org, March 3, 2003, Retrieved from http://www.openvms.org/stories.php?story=03/03/03/4358185 on March 11,#2010.
- Robert Gezelter “Logical Names: Part 4” The OpenVMS Consultant, OpenVMS.org, February 6, 2003, Retrieved from http://www.openvms.org/stories.php?story=03/02/06/8131783 on March 11,#2010.
- Robert Gezelter “Logical Names: Part 3” The OpenVMS Consultant, OpenVMS.org, November 4, 2002, Retrieved from http://www.openvms.org/stories.php?story=02/11/04/2738906 on March 11,#2010.
- Robert Gezelter “Logical Names: Part 2” The OpenVMS Consultant, OpenVMS.org, October 17, 2002, Retrieved from http://www.openvms.org/stories.php?story=02/10/17/9372652 on March 11,#2010.
- Robert Gezelter “Logical Names: Part 1” The OpenVMS Consultant, OpenVMS.org, September 24, 2002, Retrieved from http://www.openvms.org/stories.php?story=02/09/24/5441505 on March 11,#2010.
- Robert Gezelter “OpenVMS DCL Computed GOTO/Case Statement” Technology Demonstration, Robert Gezelter Software Consultant Retrieved from http://www.rlgsc.com/demonstrations/dcl_goto.html on March 11, 2010.
