OpenVMS DCL Dictionary

For complete information on specifying time values, see the OpenVMS User's Manual or the topic SPECIFY Date_Time in online help.

/USER=username

Requires CMKRNL (change mode to kernel) privilege and read (R) and write (W) access to the user authorization file (UAF).

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

Defines for a batch job a working set default, the default number of physical pages that the job can use. If the queue on which the job executes has a nonzero default working set, the smaller of the specified job and queue values is used. If the queue on which the job executes has a working set default of 0, the smaller of the specified job and UAF values (value established in the user authorization file) is used.

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

Defines for the batch job a working set extent, the maximum amount of physical memory that the job can use. The job uses the maximum amount of physical memory only when the system has excess free pages. If the queue on which the job executes has a nonzero working set extent, the smaller of the specified job and queue values is used. If the queue on which the job executes has a working set extent of 0, the smaller of the specified job and the value established in the user authorization file (UAF) is used.

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

Defines for the batch job a working set quota, the amount of physical memory that the job is guaranteed. If the queue on which the job executes has a nonzero working set quota, the smaller of the specified job and queue values is used. If the queue on which the job executes has a working set quota of 0, the smaller of the specified job or the value established in the user authorization file (UAF) is used.

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-1994 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.

SUBROUTINE

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

SYNCHRONIZE

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.

TYPE

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, see the OpenVMS User's Manual or the topic SPECIFY Date_Time in online help.
/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 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 the Return key. 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]

/NOHIGHLIGHT (default)
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.
If you enter the /OUTPUT qualifier with a partial file specification (for example, /OUTPUT=[JONES]), TYPE is the default file name and .LIS the default file type. The file specification cannot include the asterisk (*) and the percent sign (%) wildcard characters.
If you enter the /NOOUTPUT qualifier, output is suppressed.
The /OUTPUT qualifier is incompatible with the /PAGE qualifier.

/PAGE[=keyword]

/NOPAGE (default)
Controls the display of information on the screen.
You can use the following keywords with the /PAGE qualifier:

CLEAR_SCREEN Clears the screen before each page is displayed.

SCROLL Displays information one line at a time.

SAVE[= n] Enables screen navigation of information, where n is the number of pages to store.

The /PAGE=SAVE qualifier allows you to navigate through screens of information. The /PAGE=SAVE qualifier stores up to 5 screens of up to 255 columns of information. When you use the /PAGE=SAVE qualifier, you can use the following keys to navigate through the information:

Key Sequence Description

Up arrow (<uparrow symbol>), Ctrl/B Scroll up one line.

Down arrow (<downarrow symbol>) Scroll down one line.

Left arrow ( <-) Scroll left one column.

Right arrow (->) Scroll right one column.

Find (E1) Specify a string to find when the information is displayed.

Insert Here (E2) Scroll right one half screen.

Remove (E3) Scroll left one half screen.

Select (E4) Toggle 80/132 column mode.

Prev Screen (E5) Get the previous page of information.

Next Screen (E6), Return, Enter, Space Get the next page of information.

F10, Ctrl/Z Exit. (Some utilities define these differently.)

Help (F15) Display utility help text.

Do (F16) Toggle the display to oldest/newest page.

Ctrl/W Refresh the display.

N Display the next file (when more than one file is specified with the TYPE command)

Q Quit displaying output from the TYPE command.

The /PAGE qualifier is not compatible with the /OUTPUT qualifier.
/SEARCH="string"
Use with the /PAGE=SAVE qualifier to specify a string that you want to find in the information being displayed. Quotation marks are required for the /SEARCH qualifier, if you include spaces in the text string.
You can also dynamically change the search string by pressing the Find key (E1) while the information is being displayed. Quotation marks are not required for a dynamic search.
/SINCE[=time]
Selects only those files dated after 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 /SINCE 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, see the OpenVMS User's Manual or the topic SPECIFY Date_Time in online help.
/TAIL[=n]
Displays the last several lines of a log file. The value, n, defaults to p-2 where p is the current terminal page length. You can use TYPE/TAIL only if all of the following criteria are true:

File organization is sequential.
The longest record is less than 512 bytes.
The record format is either VAR, VFC, STM, STRCM or STMLF (for more information, see the description of FAB$B_RFM in the OpenVMS Record Management Services Reference Manual).
The file being typed is on a device that supports random access. The TYPE/TAIL command does not work on magnetic tape drives.

Even with this criteria, some file conditions cannot be anticipated and may not allow display of the last several lines of a log file, resulting in the following error message:
%TYPE-W-READERR, error reading DEVICE:[DIRECTORY]FILE.EXT;1 
-SYSTEM-E-UNSUPPORTED, unsupported operation or function 
/WRAP

/NOWRAP (default)
Use with the /PAGE=SAVE qualifier to limit the number of columns to the width of the screen and to wrap lines that extend beyond the width of the screen to the next line.
The /NOWRAP qualifier extends lines beyond the width of the screen and can be seen when you use the scrolling (left and right) features provided by the /PAGE=SAVE qualifier.

Key Sequence	Description
Up arrow (<uparrow symbol>), Ctrl/B	Scroll up one line.
Down arrow (<downarrow symbol>)	Scroll down one line.
Left arrow ( <-)	Scroll left one column.
Right arrow (->)	Scroll right one column.
Find (E1)	Specify a string to find when the information is displayed.
Insert Here (E2)	Scroll right one half screen.
Remove (E3)	Scroll left one half screen.
Select (E4)	Toggle 80/132 column mode.
Prev Screen (E5)	Get the previous page of information.
Next Screen (E6), Return, Enter, Space	Get the next page of information.
F10, Ctrl/Z	Exit. (Some utilities define these differently.)
Help (F15)	Display utility help text.
Do (F16)	Toggle the display to oldest/newest page.
Ctrl/W	Refresh the display.
N	Display the next file (when more than one file is specified with the TYPE command)
Q	Quit displaying output from the TYPE command.

Examples

$ TYPE  COMMON.DAT

In this example, the TYPE command requests that the file COMMON.DAT be displayed at the terminal.

$ TYPE *.DAT
This is the first line in the file AA.DAT.
   .
   .
   .
[Ctrl/O]
This is the first line in the file BB.DAT.
   .
   .
   .
 
[Ctrl/Y]
Interrupt
$ STOP

In this example, the TYPE command contains an asterisk (*) wildcard character in place of the file name. All files with file types of DAT are scheduled for display. When Ctrl/O is pressed, output of the current file stops and the TYPE command begins displaying the next file. The Ctrl/Y function interrupts the command; the STOP command terminates the TYPE command.

$ TYPE LETTER*.MEM
December 14, 1994
   .
   .
   .
 
[Ctrl/Y]
Interrupt
$ SHOW TIME
 14-DEC-1994 15:48:07  
$ CONTINUE
Sincerely yours,
   .
   .
   .

In this example, the TYPE command displays all files whose names begin with the word LETTER and have the file type MEM. While the files are being displayed, the user presses Ctrl/Y to interrupt the TYPE operation and to display the time. After entering the SHOW TIME command, the user enters the CONTINUE command to resume the TYPE operation.

$ TYPE/OUTPUT=SAVETEXT.TXT *.TXT

Previous | Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]
  9996P065.HTM
  OSSG Documentation
  26-NOV-1996 11:18:46.27
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal

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.

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

CLEAR_SCREEN	Clears the screen before each page is displayed.
SCROLL	Displays information one line at a time.
SAVE[= n]	Enables screen navigation of information, where n is the number of pages to store.