Using the DCL Definition Type

The DCL shell is the default shell for OpenVMS. It is used for almost all scripting on OpenVMS systems, because it is guaranteed to be installed and there is a low likelihood of any other shell being installed.

Variables and Parameters

You can manipulate parameters in a Process Definition as global symbolsin the DCL code, using the standard SYMBOL or 'SYMBOL' syntax. For example, if a Process Definition with parameters named P_IN and P_OUT, you can read and set their values as follows.

Copy 
$ write sys$output "The parameter P_IN has value ''P_IN'"
$ P_OUT=="New Output value for P_OUT"

If you use parameters named P1 through P8, your DCL script will run as a nested DCL script. It will have local symbols P1 through P8, but they will not be set to any value, because the script is called without positional parameters. This means that if you use Process Definitions that use the parameters P1 through P8, you must delete the local symbol before you can access the global symbol value.

For example, to print the value of the parameter P1 you can use code like the following.

Copy 
$ delete/symbol/local P1
$ write sys$output "The parameter P1 = ''P1'"

The following notes apply to DCL code.

  • All parameters are passed as string values.

  • Numbers are translated automatically.

  • Dates are sent and retrieved using the Script Date Format.

  • Out parameters are supported.

Returning an Error

The DCL $status is correctly reflected in the return code of the process. Process status is also derived using the normal OpenVMS method. Because the OpenVMS exit status indicates the success or failure of the process in the lower three bits of the return code, a large numerical value in the return code may still indicate success.

Standard files

Your DCL code runs with it's default directory set to [...<job>.JobFiles]. Any files it creates there will be attached to the process. This directory normally contains three standard files:

  • STDOUT.LOG;1 contains any output sent to SYS$OUTPUT, including any DCL verify output written by your script.
  • STDERR.LOG;1 contains any output sent to SYS$ERROR, including any DCL verify output written by the DCL Process Definition runner and the SYLOGIN.COM and LOGIN.COM procedures, as well as the trailing process information written by the command processor when the process finishes.
  • STDLOG.LOG;1 which contains any debugging and informational output created by the job-processor. If you are not running the Process Server with logging at debug level, this file will usually be empty and will be deleted automatically.

In most OpenVMS installations, SYLOGIN.COM contains the following in its first two lines.

Copy 
$ Set NoOn
$ VERIFY = F$VERIFY(F$TRNLNM("SYLOGIN_VERIFY"))

Because a RunMyJobs Platform Agent starts logging at an early stage, the STDERR.LOG file may contain the above output. To remove this output, change the SYLOGIN.COM file to begin as follows.

Copy 
$! VERIFY = 'F$VERIFY(F$TRNLNM("SYLOGIN_VERIFY"))
$ Set NoOn

Note the added comment and quote characters, and the reversed order. The $! line is not logged, but it is executed by DCL as because it contains 'F$VERIFY.