Updated: 11 December 1998

OpenVMS DCL Dictionary

When you use the /LOG_FILE qualifier, the system writes the batch job's output to the file you specify. If you use the /NOLOG_FILE qualifier, no log file is created. By default, a log file is created, is written to the directory defined by the logical name SYS$LOGIN in the UAF, and is given the batch job's name as its file name with a file type of LOG. By default, a log file also is given the batch job's name as its file name with a file type of LOG.

You can use the /LOG_FILE qualifier to write the log file to a different device. Logical names in the file specification are translated in the context of the process that submits the job. The process executing the batch job must have access to the device on which the log file will reside.

If you omit the /LOG_FILE qualifier and specify the /NAME qualifier, the log file is written to a file having the same file name as that specified by the /NAME qualifier with the file type LOG. When you omit the /LOG_FILE qualifier, the job-name value used with the /NAME qualifier must be a valid file name.

/MODIFIED

/NOMODIFIED

/NAME=job-name

If you omit the /LOG_FILE qualifier, the job-name value must be a valid file name. The SHOW ENTRY and SHOW QUEUE/FULL commands display the job name.

/NOTE=text

/NOTIFY

/NONOTIFY (default)

/PARAMETERS=(parameter[,...])

Commas (,) separate individual parameters. If you specify only one parameter, you can omit the parentheses.

If the parameter contains spaces, special characters, or lowercase characters, enclose it in quotation marks. The size of the parameter can be from 1 to 255 characters.

/PRINTER[=queue-name](default)

/NOPRINTER

When batch and output queues are managed by the same queue manager, the queue manager checks to ensure that the queue specified on the SUBMIT/PRINTER command is an output queue and that the user has access to the output queue. These checks are not made if the batch queue specified by the SUBMIT command and the output queue specified by the /PRINTER qualifier are managed by different queue managers.

If you explicitly specify an output queue for the log file when submitting a batch job, be sure the queue you specify with the /PRINTER qualifier is an output queue and not a batch queue. Also, be sure that you have access to the output queue.

/PRIORITY=n

Specifies the job-scheduling priority for the batch job with respect to other jobs in the same queue. The value of n is an integer in the range of 0 to 255, where 0 is the lowest priority and 255 is the highest.

The default value is the value of the system parameter DEFQUEPRI. No privilege is needed to set the priority lower than the queue's maximum scheduling priority, which is the value of the system parameter MAXQUEPRI.

The /PRIORITY qualifier has no effect on the job's process execution priority. The job's process execution priority is determined by the base priority attribute of the INITIALIZE/QUEUE/BASE_PRIORITY command.

/QUEUE=queue-name[:]

/REMOTE

Note that, unlike submitting a job on a local node, multiple command procedures queued by a single SUBMIT/REMOTE command are considered separate jobs.

You can specify only the following qualifiers with the /REMOTE qualifier:

/BACKUP	/BEFORE	/BY_OWNER	/CONFIRM
/CREATED	/EXCLUDE	/EXPIRED	/MODIFIED
/SINCE

/RESTART

/NORESTART (default)

/RETAIN=option

Use the following options to specify job retention:

• ALWAYS----Holds the job in the queue regardless of the job's completion status.
• DEFAULT----Holds the job in the queue as specified by the queue's retention policy.
• ERROR----Holds the job in the queue only if the job completes unsuccessfully.
• UNTIL=time-value----Holds the job in the queue for the specified length of time, regardless of the job's completion status.

How Job Retention Is Determined

Although you can specify job retention options for your own jobs, the job retention option you specify may be overridden by the job retention option of the queue on which your job executed. If you submit or print a job to a generic queue, the generic queue's job retention setting may also override the job retention option you specify. This section describes how job retention is determined.

An execution queue's job retention setting takes precedence over a generic queue's job retention setting. However, if the job's completion status does not match the job retention setting (if any) on the execution queue, then the generic queue's job retention setting attempts to control job retention. If the job's completion status does not match the job retention setting (if any) on the generic queue, then the user-specified job retention setting is used. Jobs submitted directly to execution queues are not affected by job retention settings on generic queues.

If the execution queue's retention setting applies, the job is retained on the execution queue. Likewise, if the generic queue's retention setting applies, the job is retained on the generic queue. If the user-specified setting applies, the job is retained in the queue to which it was submitted.

The following example illustrates how the queue manager determines job retention:

Suppose you submit a job to a generic queue and specify /RETAIN=ALWAYS, and the job completes successfully.

First, the queue manager compares the job's completion status to the execution queue's retention setting. Suppose the queue is set with /RETAIN=ERROR (retains only jobs that complete unsuccessfully). The job is not retained in the execution queue because the error condition was not met.

The queue manager then compares the job's completion status to the generic queue's retention setting. Suppose the generic queue has no retention setting. The queue manager's comparison again fails to retain the job.

Finally, the queue manager compares the job's completion status to the retention setting you specified for the job. This comparison reveals that the job should be retained. Because the user-specified setting leads the queue manager to retain the job, the job is held in the queue to which the job was submitted---in this case, the generic queue.

For more information on types of queues, see the INITIALIZE/QUEUE command. For more information on setting retention options for queues, see the INITIALIZE/QUEUE, START/QUEUE, or SET QUEUE command.

Timed Retention

Timed retention, which you specify using the UNTIL=time-value option, allows you to retain a job in the queue only as long as you need it. This eliminates the need to delete the job from the queue later.

For example, the following command retains the job MYFILE in the queue until 7:31 on December 14, when the job will automatically be deleted from the queue.

$ SUBMIT/RETAIN=UNTIL=14-DEC-1998:07:31:0.0 MYFILE.COM

However, depending on the queue's job retention policy, the job might be retained indefinitely. The job retention policy set on the queue takes precedence over the user-specified job retention setting. Because system managers cannot specify timed job retention for a queue, any jobs retained as a result of a queue's setting are retained indefinitely.

If you specify the /RETAIN=UNTIL=time-value option, you must supply a time value. The time value is first interpreted as a delta time, then as a combination time, and finally as an absolute time. If you specify a delta time, the delta begins when the job completes. For example, if you specify SUBMIT/RETAIN=UNTIL="3:00", the job will be retained for three hours after the job completes. For information on specifying time values, refer to the OpenVMS User's Manual.

/SINCE[=time]

/NOSINCE

For complete information about specifying time values, refer to the OpenVMS User's Manual or the online help topic DCL_Tips (subtopic Date_Time).

/STYLE=keyword

The valid keywords for this qualifier are CONDENSED and EXPANDED. Descriptions are as follows:

Keyword	Explanation
CONDENSED (default)	Displays the file name representation of what is generated to fit into a 255-length character string. This file name may contain a DID or FID abbreviation in the file specification.
EXPANDED	Displays the file name representation of what is stored on disk. This file name does not contain any DID or FID abbreviations.

The keywords CONDENSED and EXPANDED are mutually exclusive. This qualifier specifies which file name format is displayed in the output message, along with the confirmation if requested.

File errors are displayed with the CONDENSED file specification unless the EXPANDED keyword is specified.

Refer to the OpenVMS Guide to Extended File Specifications for more information.

/USER=username

Allows you to submit a job on behalf of another user. The job runs exactly as if that user had submitted it. The job runs under that user's user name and user identification code (UIC), and accounting information is logged to that user's account. By default, the user identification comes from the requesting process. The username qualifier value can be any user name that is validated on your system. The name must be 1 to 12 alphanumeric characters.

/WSDEFAULT=n

Specify the value of n as a number of 512-byte pagelets on Alpha or 512-byte pages on VAX. Note that OpenVMS systems round up this value to the nearest CPU-specific page so that actual amount of physical memory allowed may be larger than the specified amount on Alpha. If you specify the value 0 or NONE, the specified queue or UAF value is used. Working set default values must range between the numbers specified by the system parameters PQL_MWSDEFAULT and WSMAX.

/WSEXTENT=n

Specify the value of n as a number of 512-byte pagelets on Alpha or 512-byte pages on VAX. Note that OpenVMS systems round up this value to the nearest CPU-specific page so that actual amount of physical memory allowed may be larger than the specified amount on Alpha. If you specify the value 0 or NONE, the specified queue or UAF value is used. Working set extent values must range between the numbers specified by the system parameters PQL_MWSEXTENT and WSMAX.

/WSQUOTA=n

Specify the value of n as a number of 512-byte pagelets on Alpha or 512-byte pages on VAX. Note that OpenVMS systems round up this value to the nearest CPU-specific page so that actual amount of physical memory allowed may be larger than the specified amount on Alpha. If you specify the value 0 or NONE, the specified queue or UAF value is used. Working set quota values must range between the numbers specified by the system parameters PQL_MWSQUOTA and WSMAX.

Examples

$ SUBMIT/AFTER=16:30 TRANSLATE
Job TRANSLATE (queue SYS$BATCH, entry 1401) holding until 14-DEC-1998 16:30
 
      

In this example, the command procedure TRANSLATE.COM is submitted to SYS$BATCH. The procedure is executed at 4:30 P.M. or later. When the batch job completes, the log file TRANSLATE.LOG is queued to SYS$PRINT for printing and is deleted.

$ SUBMIT /PARAMETERS=(TXT,DOC,MEM) BACKUP, AVERAGE, RUNMASTER
  Job BACKUP (queue SYS$BATCH, entry 416) pending
 
      

In this example, the SUBMIT command enters three command procedures in a single job. The job is given three parameters: P1 is equated to the string TXT, P2 to the string DOC, and P3 to the string MEM. After the procedure BACKUP.COM is executed, the procedures AVERAGE.COM and RUNMASTER.COM are executed.

$ SUBMIT/NAME=BATCH24/HOLD TESTALL
  Job BATCH24 (queue SYS$BATCH, entry 467) holding
      

In this example, the SUBMIT command enters the procedure TESTALL.COM as a batch job and specifies that the job be held for later processing. The job is not released until the SET ENTRY/RELEASE command is entered. The /NAME qualifier requests that the batch job be identified as BATCH24.

$ SUBMIT TEST.COM
  Job TEST (queue SYS$BATCH, entry 493) pending
$ BATCH_JOB = $ENTRY
   .
   .
   .
$ DELETE/ENTRY='BATCH_JOB'
      

In this command sequence, the $ENTRY symbol is used to refer to a particular job in the queue file. The SUBMIT command creates a batch job to run the command procedure TEST.COM. In addition, the SUBMIT command defines $ENTRY as a local symbol whose value is the entry number of the job (493 in this example). The second statement assigns the value $ENTRY to the local symbol BATCH_JOB. The last line of the example deletes the job by using the symbol BATCH_JOB to identify it.

$ DEFINE JUNE WORKZ:[JONES]ANNUAL_REPORT.COM
$ SUBMIT JUNE
Job ANNUAL_REPORT (queue SYS$BATCH, entry 229) started on ZOO_BATCH
 
      

In this example, the logical name JUNE is created and equated to ANNUAL_REPORT.COM with the DEFINE command. Using the logical name JUNE, the user submits ANNUAL_REPORT.COM to the batch queue. Note that the system translates the logical name JUNE to ANNUAL_REPORT.COM before ANNUAL_REPORT.COM is submitted to the batch queue. Also, the log file produced is named ANNUAL_REPORT.COM rather than JUNE.COM.

Note also that the job is submitted to the generic queue SYS$BATCH, but runs on the execution queue ZOO_BATCH.

Defines the beginning of a subroutine in a command procedure. The SUBROUTINE command must be the first executable statement in a subroutine. For more information about the SUBROUTINE command, refer to the description of the CALL command.

Format

SUBROUTINE

Holds the process issuing the command until the specified job completes execution.

Requires delete (D) access to the specified job.

Format

SYNCHRONIZE [job-name]

Parameter

job-name

Specifies the name of the job as defined when the job was submitted. You can specify only job names that are associated with your user name. (A job is associated with the user name of the process that submits it.)

To specify a job that does not have a unique name, use the /ENTRY qualifier to specify the entry number. If you specify both the job-name parameter and the /ENTRY qualifier, the job-name parameter is ignored.

If you specify the job-name parameter, the command searches for a job with the specified name in the queue SYS$BATCH. To specify a job in a different queue, you must specify the name of the queue using the /QUEUE qualifier.

Description

The SYNCHRONIZE command provides job synchronization by placing a process in a wait state until the specified job completes. If the specified job is not a current job in the system, the SYNCHRONIZE command displays an error message.

When a job specified in a SYNCHRONIZE command completes, the process is released from the wait state. The completion status for the SYNCHRONIZE command is the same as the completion status of the last command executed in the job. To make sure that you can determine the completion status when the SYNCHRONIZE command is part of a command procedure, include SET NOON before the SYNCHRONIZE command and SHOW SYMBOL $STATUS immediately after the SYNCHRONIZE command.

You must specify either the job-name parameter or the /ENTRY qualifier.

Qualifiers

/ENTRY=entry-number

Identifies the job by the system-assigned entry number.

The system assigns a unique entry number to each queued print or batch job in the system. By default, the PRINT and SUBMIT commands display the entry number when they successfully queue a job for processing. These commands also create or update the local symbol $ENTRY to reflect the entry number of the most recently queued job. To find a job's entry number, enter the SHOW ENTRY or SHOW QUEUE command. If you specify both the job-name parameter and the /ENTRY qualifier, the job name is ignored.

/QUEUE=queue-name[:]

Names the queue containing the job. If you use the /QUEUE qualifier, you must specify either the job-name parameter or the /ENTRY qualifier. If you specify the job-name parameter, the default queue is SYS$BATCH. If you specify the /ENTRY qualifier, there is no default queue. If you specify a generic queue, the command looks for the job in the generic queue and in the qeneric queue's target execution queues.

Examples

$ SUBMIT/NAME=PREP FORMAT/PARAMETERS=(SORT,PURGE)
  Job PREP (queue SYS$BATCH, entry 219) started on queue SYS$BATCH
$ SUBMIT PHASER
  Job PHASER (queue SYS$BATCH, entry 223) started on queue SYS$BATCH
      

In this example, the first SUBMIT command submits the command procedure FORMAT.COM for execution and names the job PREP. The second SUBMIT command queues the procedure PHASER.COM. The procedure PHASER.COM contains the following line:

$ SYNCHRONIZE PREP

When this line is processed, the system verifies whether the job named PREP exists in the default queue SYS$BATCH. The procedure PHASER is forced to wait until the job PREP completes execution.

$ SUBMIT/NAME=TIMER       COMP.COM
  Job TIMER (queue SYS$BATCH, entry 214) started on queue SYS$BATCH
$ SYNCHRONIZE /ENTRY=214
      

In this example, a batch job named TIMER is submitted. Then the SYNCHRONIZE command is entered interactively. This command places the interactive process in a wait state until entry number 214 (TIMER) completes. You cannot enter subsequent commands from your terminal session until the SYNCHRONIZE command completes and your process is released from the wait state.

$ SUBMIT/NAME=TIMER COMP.COM/QUEUE=BUILD_QUEUE
$ SYNCHRONIZE/QUEUE=BUILD_QUEUE TIMER
      

The batch job name TIMER is submitted to the queue BUILD_QUEUE in this example. Then the SYNCHRONIZE command is entered interactively. Because the job named TIMER is not in the default queue SYS$BATCH, the SYNCHRONIZE command includes the /QUEUE qualifier to specify the queue in which the job is located.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

9996PRO_077.HTML