HP OpenVMS Systems Documentation

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 describes 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-2001: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:

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 User's Manual 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 the 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 the 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 the 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-2001 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:[SCHREURS]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.

$ SUBMIT/HOLD/QUEUE=ANYRADQ /RAD=1  TEST.COM
Job TEST (queue ANYRADQ, entry 23) holding

$ SHOW ENTRY/FULL 23
 Entry  Jobname      Username     Blocks  Status
 -----  -------      --------     ------  ------
    23  TEST         SYSTEM               Holding
  On idle batch queue ANYRADQ
  Submitted 24-JUL-2001 14:19:37.44 /KEEP /NOPRINT /PRIORITY=100 /RAD=0
  File: _$1$DKB200:[SWEENEY.CLIUTL]TEST.COM;1
      

In this example, TEST.COM is submitted to the queue ANYRADQ. There is no RAD setting on the ANYRADQ queue.

$ SUBMIT/HOLD/QUEUE=BATCHQ1 /RAD=1  TEST.COM
Job TEST (queue BATCHQ1, entry 24) holding

$ SHOW ENTRY 24/FULL
 Entry  Jobname      Username     Blocks  Status
 -----  -------      --------     ------  ------
    24  TEST         SYSTEM               Holding
  On idle batch queue BATCHQ1
  Submitted 24-JUL-2001 14:23:10.37 /KEEP /NOPRINT /PRIORITY=100 /RAD=0
  File: _$1$DKB200:[SWEENEY.CLIUTL]TEST.COM;2
      

In this example, the queue, BATCHQ1, is defined with /RAD=0. Therefore, use of the SUBMIT command creates a job that runs on RAD 0, even though RAD 1 was specified.

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.

Displays the contents of a file or group of files on the current output device.

Format

TYPE filespec[,...]

Parameter

filespec[,...]

Specifies one or more files to be displayed. If you specify a file name and not a file type, the file type defaults to .LIS; however, you can specify a different default file type with the TYPE$DEFAULT_FILESPEC logical name. The TYPE command displays all files that satisfy the file description.

The asterisk (*) and the percent sign (%) wildcard characters are allowed in place of the directory name, file name, file type, or file version number field. If you specify more than one file, separate the file specifications with commas (,) or plus signs (+). The files are displayed in the order listed.

Description

When the TYPE command displays output, you can control the display in the following ways:

• Press Ctrl/C to stop the TYPE command for the current file that is being displayed. If you specified only one file with your TYPE command, or if the TYPE command is displaying the last file in the list, pressing Ctrl/C cancels the TYPE command. If you have specified more than one file with the TYPE command, pressing Ctrl/C causes the TYPE command to display the next file in the list.
• Press Ctrl/S to temporarily suspend the output. Press Ctrl/Q to resume the output display at the point of interruption.
• Press Ctrl/O to suppress the display but not to suspend the command processing. If you press Ctrl/O again before the TYPE command terminates, output resumes at the current point in command processing. However, if you press Ctrl/O when the TYPE command is displaying files in a list, the TYPE command suppresses typing the current file and begins typing the next file in the list. This behavior is an exception to normal Ctrl/O processing.
• Press Ctrl/Y to interrupt the command execution. You can enter the CONTINUE command after pressing Ctrl/Y to resume displaying the files where the interruption took place, provided you have not entered an intervening command that calls up a new image. If you press Ctrl/Y to stop command execution entirely, you can enter the EXIT command (or any other DCL command that activates an image) to run down the image.

In addition, the /PAGE qualifier may be used to display text one screen at a time.

The TYPE command opens the specified file with shared read (R) and write (W) access. Therefore, any file that has its attributes set to shared write is displayed, even if it is currently opened by another user.

You also can use the TYPE command to execute a command procedure on a remote node. This is useful on OpenVMS Cluster systems, for example, when you want to display the status of clusterwide services, such as queues, or when you want to display the users logged in to other nodes on the cluster. A sample command procedure follows:

$ @ SHOWUSERS.COM $ if f$mode() .eqs. "NETWORK" then define/user sys$output sys$net $ show users

This command procedure can be used with the TYPE command to display at the user's local node the users logged on to the remote node where the command procedure resides.

Specify the command procedure as a parameter to the TYPE command as follows:

$ TYPE node_name::"TASK=command_procedure"

where:

node_name	Specifies the name of the remote node on which the command procedure resides.
command_procedure	Specifies the file name of the command procedure to be run.

This form of the command finds the command procedure in the default DECnet account of the remote node.

To execute a command procedure in the SYS$LOGIN directory of a particular account, use an access control string in the command, as follows:

$ TYPE node_name"user_name password"::"TASK=command_procedure"

where:

user_name	Specifies the user name of the account on the remote node.
password	Specifies the password of the account on the remote node.

Qualifiers

/BACKUP

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /BACKUP qualifier selects files according to the dates of their most recent backups. This qualifier is incompatible with the /CREATED, /EXPIRED, and /MODIFIED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time qualifiers, the default is the /CREATED qualifier.

/BEFORE[=time]

Selects only those files dated prior to the specified time. You can specify time as absolute time, as a combination of absolute and delta times, or as one of the following keywords: BOOT, LOGIN, TODAY (default), TOMORROW, or YESTERDAY. Specify one of the following qualifiers with the /BEFORE qualifier to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED (default), /EXPIRED, or /MODIFIED.

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

/BY_OWNER[=uic]

Selects only those files whose owner user identification code (UIC) matches the specified owner UIC. The default UIC is that of the current process.

Specify the UIC by using standard UIC format as described in the HP OpenVMS Guide to System Security.

/CONFIRM

/NOCONFIRM (default)

Controls whether a request is issued before each typing operation to confirm that the operation should be performed on that file. The following responses are valid:

YES	NO	QUIT
TRUE	FALSE	Ctrl/Z
1	0	ALL
	[Return]

You can use any combination of uppercase and lowercase letters for word responses. Word responses can be abbreviated to one or more letters (for example, T, TR, or TRU for TRUE), but these abbreviations must be unique. Affirmative answers are YES, TRUE, and 1. Negative answers include: NO, FALSE, 0, and pressing Return. Entering QUIT or pressing Ctrl/Z indicates that you want to stop processing the command at that point. When you respond by entering ALL, the command continues to process, but no further prompts are given. If you type a response other than one of those in the list, DCL issues an error message and redisplays the prompt.

/CONTINUOUS/INTERVAL=n

Upon reaching the end of a file, TYPE waits a specified number of seconds (the default is 30) then displays any records which have been added to the file and returns to the wait state. TYPE continues until either Ctrl/C or Ctrl/Y is entered by the user.

/CREATED (default)

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /CREATED qualifier selects files based on their dates of creation. This qualifier is incompatible with the /BACKUP, /EXPIRED, and /MODIFIED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time qualifiers, the default is the /CREATED qualifier.

/EXACT

Use with the /PAGE=SAVE and /SEARCH qualifiers to specify a search string that must match the search string exactly and must be enclosed with quotation marks (" ").

If you specify the /EXACT qualifier without the /SEARCH qualifier, exact search mode is enabled when you set the search string with the Find (E1) key.

/EXCLUDE=(filespec[,...])

Excludes the specified files from the type operation. You can include a directory but not a device in the file specification. The asterisk (*) and the percent sign (%) wildcard characters are allowed in the file specification; however, you cannot use relative version numbers to exclude a specific version. If you specify only one file, you can omit the parentheses.

/EXPIRED

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /EXPIRED qualifier selects files according to their expiration dates. (The expiration date is set with the SET FILE/EXPIRATION_DATE command.) The /EXPIRED qualifier is incompatible with the /BACKUP, /CREATED, and /MODIFIED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time qualifiers, the default is the /CREATED qualifier.

/HEADER

/NOHEADER

Specifies whether a header line is placed at the top of each file that is displayed with the TYPE /PAGE=SAVE command.

/HIGHLIGHT[=keyword]

Use with the /PAGE=SAVE and /SEARCH qualifiers to specify the type of highlighting you want when a search string is found. When a string is found, the entire line is highlighted. You can use the following keywords: BOLD, BLINK, REVERSE, and UNDERLINE. BOLD is the default highlighting.

/MODIFIED

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /MODIFIED qualifier selects files according to the dates on which they were last modified. This qualifier is incompatible with the /BACKUP, /CREATED, and /EXPIRED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time modifiers, the default is the /CREATED qualifier.

/OUTPUT[=filespec]

/NOOUTPUT

Controls where the output of the command is sent. If you specify the /OUTPUT=filespec qualifier, the output is sent to the specified file, rather than to the current output device, SYS$OUTPUT. If you do not enter the qualifier, or if you enter the /OUTPUT qualifier without a file specification, the output is sent to SYS$OUTPUT.

---

Previous

Next

Contents

Index