OpenVMS DCL Dictionary

Document revision date: 30 March 2001

OpenVMS DCL Dictionary

Contents

Index

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.

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.

/TRAILER[=keyword]

/NOTRAILER

Positional qualifier.

Controls whether a file trailer page is printed at the end of a file. The trailer page displays the job entry number as well as information about the user submitting the job and the files being printed. If the /TRAILER qualifier is positioned between the PRINT command and the file specifications, it can take either of the following keywords:

ALL Prints a file trailer page after each file in the job.

ONE Prints a file trailer page after the last file in the job.

If you want the /TRAILER qualifier to apply to individual files in a multifile job, place the qualifier directly after each file that you want to have a trailer page.

Use the /[NO]TRAILER qualifier to override the /DEFAULT=[NO]TRAILER option that has been set for the output queue you are using. The /[NO]TRAILER qualifier does not override the /SEPARATE=[NO]TRAILER option set for the queue.

/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 print a job on behalf of another user. The print job runs exactly as if that user had submitted it. The print 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 user name qualifier value can be any user name that is valid on your system. The name must be 1 to 12 alphanumeric characters.

Examples

#1
$ PRINT/QUEUE=LPB0/COPIES=10/AFTER=20 RESUME Job RESUME (queue LPB0, entry 239) holding until 14-DEC-2001 20:00

The PRINT command in this example queues 10 copies of the file RESUME.LIS to printer LPB0, but requests that the copies not be printed until after 8:00 P.M.

#2
$ PRINT THETA.TXT + BETA/FLAG + GAMMA/FLAG + *.LIS/FLAG Job THETA (queue SYS$PRINT, entry 237) pending

The PRINT command in this example submits the files THETA.TXT, BETA.TXT, GAMMA.TXT, and the highest versions of all files with the file type .LIS as a single print job. Flag pages separate the individual files. Notice that the file type for BETA and GAMMA is .TXT, the file type of the first file in the list.

#3
$ PRINT/LOWERCASE THETA.TXT/COPIES=2, - _$BETA.DOC/COPIES=3 Job THETA (queue SYS$PRINT, entry 240) pending

The print job queued by the PRINT command in this example consists of two copies of THETA.TXT followed by three copies of BETA.DOC. This job must be printed on a printer that can print lowercase letters. If no such printer is available, the job waits in the queue.

#4
$ PRINT/JOB_COUNT=3 THETA.TXT,BETA/NOIDENTIFY

The PRINT command in this example concatenates the files THETA.TXT and BETA.TXT into a single print job and prints three copies of the job. The /NOIDENTIFY qualifier requests that the job entry number and queue name not be displayed.

#5
$ COPY REPORT.MEM NODE3:: $ PRINT/REMOTE NODE3::REPORT.MEM

In this example, the two commands are entered at a node other than NODE3. The COPY command copies the file REPORT.MEM from the current node to the NODE3 node. The PRINT command queues the file REPORT.MEM located on the NODE3 node for printing at the NODE3 node. The job entry number and queue name are not displayed when the /REMOTE qualifier is used.

#6
$ PRINT/HOLD MASTER.DOC Job MASTER (queue SYS$PRINT, entry 540) holding . . . $ SET ENTRY 540/RELEASE

The PRINT command in this example queues a copy of the file MASTER.DOC to the default printer in a hold status. Later, the SET ENTRY command releases the hold status on the file and makes it available for printing.

#7
$ PRINT TEST.TXT Job TEST.TXT (queue SYS$PRINT, entry 867) started on LPA0 $ SHOW ENTRY '$ENTRY' Entry Jobname Username Blocks Status ----- ------- -------- ------ ------ 867 TEST.TXT Nisslert 135 Printing Submitted 10-DEC-2001 11:07 /FORM=DEFAULT /PRIORITY=100 File: $5$DUA174:[NISSLERT]TEST.TXT;3

$ PRINT TEST.TXT
Job TEST.TXT (queue SYS$PRINT, entry 867) started on LPA0
$ SHOW ENTRY '$ENTRY'
Entry     Jobname     Username     Blocks    Status
-----     -------     --------     ------    ------
  867     TEST.TXT    Nisslert        135    Printing
          Submitted  10-DEC-2001 11:07 /FORM=DEFAULT /PRIORITY=100
          File: $5$DUA174:[NISSLERT]TEST.TXT;3

The PRINT command in this system example queues a copy of the file TEST.TXT to the default printer. It also creates the local symbol $ENTRY to store the job entry number. The SHOW ENTRY command requests a display of the entry using the symbol $ENTRY to identify it.

#8
$ PRINT/RETAIN=UNTIL=1 MYFILE.DAT . . . $ SHOW QUEUE DOC$LN03 Server queue DOC$LN03, stopped, on NEWTON::, mounted form DEFAULT Entry Jobname Username Blocks Status ----- ------- -------- ------ ------ 436 MYFILE MIGDAL 8 Retained until 11-DEC-2001 16:56 %JBC-F-JOBABORT, job aborted during execution Completed 11-DEC-2001 15:56 on queue DOC$LN03

$ PRINT/RETAIN=UNTIL=1 MYFILE.DAT
   .
   .
   .
$ SHOW QUEUE DOC$LN03
Server queue DOC$LN03, stopped, on NEWTON::, mounted form DEFAULT
Entry    Jobname    Username  Blocks  Status
-----    -------    --------  ------  ------
  436    MYFILE     MIGDAL         8  Retained until 11-DEC-2001 16:56
      %JBC-F-JOBABORT, job aborted during execution
        Completed  11-DEC-2001 15:56 on queue DOC$LN03

The SHOW QUEUE display in this system example includes the date and time at which a retained job completed and the queue on which it executed. The user set job retention to be one hour after job completion. Depending on the queue's job retention policy, the job might be deleted from the queue at 16:56.

#9
PRINT /PARAMETERS=AAA=123

This command passes the parameter AAA=123 to the print symbiont. The interpretation of the parameter is dependent on the symbiont.

#10
$ PRINT /PARAMETERS=(ddd,"e,(F=(3,4),g),h)",iii)

This command passes three parameters to the print symbiont: DDD, "e,(F=(3,4),g),h)", and III. The use of the quotes around the second parameter allows the use of nested parentheses, commas, and the preservation of alphabetic case. This parameter value is perfectly acceptable to the PRINT command, even though it is apt to subsequently be rejected by the print symbiont.

#11
PRINT /PARAMETERS=("N,O,P,Q,R,S,T",U,V)

This command passes three parameters to the print symbiont: "N,O,P,Q,R,S,T", U, and V. Depending on the parsing capabilities of the symbiont and the length of the parameters (each parameter is limited to 255 characters), this may be a workaround to the limitation of eight parameters.

PRODUCT

Invokes the POLYCENTER Software Installation utility to do one of the following:

Install one or more software products.
Remove one or more software products.
Perform other related operations.

For a complete description of the POLYCENTER Software Installation utility and the use of the PRODUCT command, refer to the OpenVMS System Manager's Manual and the OpenVMS System Management Utilities Reference Manual or online help.

Format

PRODUCT [subcommand product-name [/qualifiers]]

PURGE

Deletes all but the highest numbered versions of the specified files.

Format

PURGE [filespec[,...]]

Parameter

filespec[,...]
Specifies one or more files to be purged. If you specify more than one file, separate the file specifications with either commas (,) or plus signs (+). The asterisk (*) and the percent sign (%) wildcard characters are allowed in the directory, file name, and file type fields; however, no version number can be specified. As a default, the PURGE command purges all files in the current directory. There are no file name or file type defaults with the PURGE command.

Description

The PURGE command deletes earlier versions of files. The PURGE command never deletes all versions of any file. By default, the PURGE command keeps only the highest version of a file. If you do not include a file specification with the PURGE command, all files in the current directory are affected by the purge.

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 OpenVMS Guide to System Security.
/CONFIRM

/NOCONFIRM (default)
Controls whether a request is issued before each purge 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.
/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.
/ERASE

/NOERASE (default)
Erases the specified files from the disk so that the purged data no longer exists physically on the deallocated disk blocks.
When you delete a file, the area in which the file was stored is returned to the system for future use. The data that was stored in that location still exists in the system until new data is written over it. When the /ERASE qualifier is specified, the storage location is overwritten with a system-specified pattern so that the data no longer exists.
/EXCLUDE=(filespec[,...])
Excludes the specified files from the purge 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.
/KEEP=number-of-versions
Specifies the maximum number of versions of the specified files to be retained in the directory. If you do not include the /KEEP qualifier, all but the highest numbered version of the specified files are deleted from the directory.
/LOG

/NOLOG (default)
Controls whether file specifications are displayed as the files are deleted.
/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.
/SINCE[=time]
Selects only those files dated on or 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, refer to the OpenVMS User's Manual or the online help topic DCL_Tips (subtopic Date_Time).
/STYLE=keyword
Specifies the file name format for display purposes while purging files.
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.

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.

Examples

#1
$ PURGE

The PURGE command in this example deletes all but the highest numbered version of all files in the default directory.

#2
$ PURGE *.COM

The PURGE command in this example deletes all but the highest numbered version of each file with a file type of .COM.

#3
$ PURGE/KEEP=3 [WILDER.JOB308]ACCOUNT.COB

The PURGE command in this example deletes all but the three highest numbered versions of the file ACCOUNT.COB in the subdirectory [WILDER.JOB308].

#4
$ PURGE/ERASE/SINCE=YESTERDAY [.MEMOS]

The PURGE command in this example purges all files in the MEMOS subdirectory that have been created or modified since yesterday and erases the storage locations so that the purged data no longer exists.

#5
$ PURGE [BRODRIBB.TESTFILES]/LOG %PURGE-I-FILPURG, DISK1:[BRODRIBB.TESTFILES]AVE.OBJ;1 deleted (3 blocks) %PURGE-I-FILPURG, DISK1:[BRODRIBB.TESTFILES]BACK.OBJ;2 deleted (5 blocks) %PURGE-I-TOTAL, 2 files deleted (8 blocks)

$ PURGE [BRODRIBB.TESTFILES]/LOG
%PURGE-I-FILPURG, DISK1:[BRODRIBB.TESTFILES]AVE.OBJ;1 deleted (3 blocks)
%PURGE-I-FILPURG, DISK1:[BRODRIBB.TESTFILES]BACK.OBJ;2 deleted (5 blocks)
%PURGE-I-TOTAL, 2 files deleted (8 blocks)

The PURGE command in this example purges all files cataloged in the subdirectory named [BRODRIBB.TESTFILES]. The /LOG qualifier requests the PURGE command to display the specification of each file it has deleted as well as the total number of files that have been deleted.

#6
$ PURGE/KEEP=2 TAMPA::DISK1:[EXAMPLE]*.LIS

The PURGE command in this example deletes all but the two highest numbered versions of each file with the file type .LIS in the directory EXAMPLE on remote node TAMPA.

READ

Reads a single record from a specified input file and assigns the record's contents to a specified symbol name.

Format

READ logical-name[:] symbol-name

Parameters

logical-name[:]
Specifies the logical name of the input file from which a record is to be read. Use the logical name assigned by the OPEN command when the file was opened. (The OPEN command assigns a logical name to a file and places the name in the process logical name table.)
In addition, you can specify the process-permanent files identified by the logical names SYS$INPUT, SYS$OUTPUT, SYS$ERROR, and SYS$COMMAND.
symbol-name
Specifies the name of a symbol to be equated to the contents of the record. The name must be 1 to 255 alphanumeric characters and must start with an alphabetic letter, an underscore (_), or a dollar sign ($).
When you specify a symbol name for the READ command, the command interpreter places the symbol name in the local symbol table for the current command level. If the symbol has already been defined, the READ command redefines it to the new value being read.

Description

The READ command can read data from sequential, relative, or indexed files. After each record is read from the specified file, the READ command positions the record pointer at the next record in the file; however, if you are reading an indexed file, you can use the /INDEX and /KEY qualifiers to read records randomly.
The maximum size of any record that can be read in a single READ command is 2048 bytes.
To read a file, the file must be opened by using the /READ qualifier with the OPEN command. The process-permanent files identified by the logical names SYS$INPUT, SYS$OUTPUT, SYS$ERROR, and SYS$COMMAND do not have to be opened explicitly to be read.
If the READ command is executed interactively and the logical name is specified as one of the process-permanent files, SYS$INPUT, SYS$OUTPUT, SYS$COMMAND, or SYS$ERROR, the command interpreter prompts for input data. The READ command accepts data exactly as you enter it. The READ command does not convert characters to uppercase, remove extra spaces and tabs, or remove quotation marks (" "). Also, the READ command does not perform symbol substitution. See the /PROMPT qualifier for more information on issuing prompts with the READ command.

Qualifiers

/DELETE
Deletes a record from an indexed file after it has been read. An indexed file must be opened with the /READ and /WRITE qualifiers in order to use the READ/DELETE command.
/END_OF_FILE=label
Transfers control to the location specified by the label keyword (in the current command procedure) when the end of the file is reached. When the last record in the file is read, the OpenVMS Record Management Services (RMS) returns an error condition indicating the end-of-file (EOF). If the /END_OF_FILE qualifier is specified, the command interpreter transfers control to the command line at the specified label.
If the /END_OF_FILE qualifier is not specified, control is given to the error label specified with the /ERROR qualifier when the end of the file is reached. If neither the /ERROR nor the /END_OF_FILE qualifier is specified, then the current ON condition action is taken.
/ERROR=label
Transfers control to the location specified by the label keyword (in the current command procedure) when a read error occurs. If no error routine is specified and an error occurs during the reading of the file, the current ON condition action is taken.
Overrides any ON condition action specified.
If an error occurs and the target label is successfully given control, the reserved global symbol $STATUS retains the error code.
/INDEX=n
Specifies the index (n) to be used to look up keys when reading an indexed file.
If you do not specify the /INDEX qualifier, the most recent /INDEX qualifier value is used. If a previous value was not specified, the primary index is used (/INDEX=0).
/KEY=string
Reads a record with the key that matches the specified character string. Binary and integer keys are not allowed. This qualifier, when used together with the /INDEX qualifier, allows you random access to indexed files.
Key matches are made by comparing the characters in the /KEY string to characters in the record key.
To read records at random in an indexed file, you must specify the /KEY qualifier. Once a record is read randomly, all subsequent reads without the /KEY qualifier access records in the indexed file sequentially.

/MATCH=option
Specifies the key match algorithm to be used when searching for matching keys. Specify one of the following options:

EQ Selects keys equal to the match value (default).

GE Selects keys greater than or equal to the match value.

GT Selects keys greater than the specified key.

If you are reading indexed files and you do not use the /MATCH qualifier, the default is /MATCH=EQ.
/NOLOCK
Specifies that the record to be read not be locked and enables a record to be read that has been locked by other accessors.
By default, records are locked as they are read and unlocked on the next I/O operation on the file.
/PROMPT=string
Specifies an alternate prompt string to be displayed when reading from the terminal. The default prompt string is DATA:.
/TIME_OUT=n

/NOTIME_OUT (default)
Specifies the number of seconds after which the READ command is terminated if no input is received. If you enter the /TIME_OUT qualifier, you must specify a value from 0 to 255.
If you enter both the /ERROR=label and /TIME_OUT qualifiers, and the time limit expires, the error branch is taken.

Examples

#1
$ OPEN IN NAMES.DAT $ LOOP: $ READ/END_OF_FILE=ENDIT IN NAME . . . $ GOTO LOOP $ ENDIT: $ CLOSE IN

The OPEN command opens the file NAMES.DAT for input and assigns it the logical name of IN. The READ command reads records from the file IN and places the contents into the symbol NAME. The READ command specifies the label ENDIT to receive control when the last record in the file has been read. The procedure loops until all records in the file have been processed.

#2
$ READ/ERROR=READERR/END_OF_FILE=OKAY MSGFILE CODE . . . $ READERR: $ CLOSE MSGFILE . . . $ OKAY: $ CLOSE MSGFILE $ EXIT

The READ command reads records from the file MSGFILE and places the contents into the symbol CODE. The READ command also uses the /ERROR and /END_OF_FILE qualifiers to specify labels to receive control at the end-of-file (EOF) and on error conditions. At the EOF, control is transferred to the label OKAY. On other read errors, control is transferred to the READERR label.

#3
$ READ SYS$COMMAND DATA_LINE $ WRITE OUTPUT_FILE DATA_LINE . . .

Previous Next Contents Index

privacy and legal statement

9996PRO_043.HTML

ALL	Prints a file trailer page after each file in the job.
ONE	Prints a file trailer page after the last file in the job.

EQ	Selects keys equal to the match value (default).
GE	Selects keys greater than or equal to the match value.
GT	Selects keys greater than the specified key.