Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS DCL Dictionary


Previous Contents Index


PRODUCT

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

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]]


PSWRAP

Invokes the PSWRAP translator, which converts procedures written in the PostScript language into routines that can be called from applications. The PSWRAP translator is available with the DECwindows Display PostScript system, which is an extension to the DECwindows programming environment.

For more information about using the PSWRAP translator and the PSWRAP command and its qualifiers, refer to the Display PostScript documentation or online help.


Format

PSWRAP filespec


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

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


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 [MAL.TESTFILES]/LOG
%PURGE-I-FILPURG, DISK1:[MAL.TESTFILES]AVE.OBJ;1 deleted (3 blocks)
%PURGE-I-FILPURG, DISK1:[MAL.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 [MAL.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 
   .
   .
   .
      

The READ command requests data from the current SYS$COMMAND device. If the command procedure containing these lines is executed interactively, the command issues a prompt to the terminal, accepts a line of data, and equates the data entered to the symbol name DATA_LINE.

Then the WRITE command writes the value of the symbol DATA_LINE to the file identified by the logical name OUTPUT_FILE.

#4

$ OPEN/READ INPUT_FILE TRNTO::INVENTORY.DAT 
$ OPEN/APPEND OUTPUT_FILE RECEIVE.DAT 
$ READ INPUT_FILE DATA_LINE 
$ WRITE OUTPUT_FILE DATA_LINE 
      

The OPEN/READ command opens the file INVENTORY.DAT at the remote node TRNTO for reading and assigns it the logical name INPUT_FILE. The OPEN/APPEND command opens the file RECEIVE.DAT in the current default directory. The READ command requests data from the file INVENTORY.DAT at the remote node TRNTO. The WRITE command writes the value of the symbol DATA_LINE to the end of the local file RECEIVE.DAT.


RECALL

Displays up to 254 previously entered commands on the screen for subsequent execution.


Format

RECALL [command-specifier]


Parameter

command-specifier

Specifies the number or the first several characters of the command you want to recall. You cannot use any of the qualifiers in conjunction with a command-specifier.

The specified characters should be unique. If they are not unique, the RECALL command displays the most recently entered command line that matches those characters. For example, suppose you enter a SHOW STATUS command and later enter a SHOW TIME command. If you then type RECALL S, the SHOW TIME command is recalled. You must type RECALL SHOW S to recall the SHOW STATUS command. The number of the command can be from 1 to 254 (where 1 is the last command entered).

The RECALL command itself is never assigned a number. If no command specifier is entered, the RECALL command recalls the most recently entered command. You can use the /ALL qualifier to have the system display all the commands in the recall buffer, along with their command numbers, to verify the number of the command you want to recall.


Description

When you enter commands to the system, they are stored in a recall buffer for later use with the RECALL command. Input to the INQUIRE command in command procedures is also placed in the recall buffer. The RECALL command itself is never stored in the recall buffer. You can use continuation characters with the commands to be recalled, but only 255 characters can be read at a time.

The recall buffer can hold up to 254 commands. The size of the recall buffer is 4Kb, which will store approximately 80 commands at 48 characters each.

If the length of stored commands makes it necessary, one or more of the oldest commands will be removed from the recall buffer to make room for the most recent command.

When you use the RECALL command, the system displays the command but does not process it. If you want it processed as it appears, press the Return key. You can use the command line editing facility to make minor changes in the command line and then press the Return key to process the revised version of the command.


Qualifiers

/ALL

Displays all the commands (and their numbers) available for recall. Do not use the /ALL qualifier with the other RECALL qualifiers.

Note

The RECALL command is never stored in the recall buffer.

/ERASE

Erases the contents of the recall buffer.

/INPUT=filespec

Causes each line of the input file to be added to the recall buffer. If a file type is not specified with the file name, .LIS is the default. The file specification cannot include the asterisk (*) and the percent sign (%) wildcard characters.

If the /ERASE qualifier is also specified, the contents of the recall buffer are erased before the contents of the specified file are read into the recall buffer.

The /INPUT qualifier is incompatible with the /ALL and /PAGE qualifiers.

/OUTPUT=filespec

Specifies the name of the output file where the contents of the recall buffer are written. If you do not specify a file type, the default is .LIS. The file specification cannot include the asterisk (*) and the percent sign (%) wildcard characters.

If the /ERASE qualifier is also specified, the contents of the recall buffer are erased after the contents of the recall buffer are written to the specified file.

The /OUTPUT qualifier is incompatible with the /ALL and /PAGE qualifiers.

/PAGE

/NOPAGE (default)

Displays all the commands (and their numbers) available for recall one screen at a time. The /NOPAGE qualifier produces the same output as the /ALL qualifier. You can cancel the output display by pressing Ctrl/Z.

The /PAGE qualifier is incompatible with the /INPUT and /OUTPUT qualifiers.


Examples

#1

$ RECALL T
      

The RECALL command in this example recalls the last command entered that begins with the letter T.

#2

$ SHOW DEFAULT
  DISK3:[SMITH]
$ DIRECTORY SEPT*
  %DIRECT-W-NOFILES, no files found
$ SET DEFAULT [SMITH.LETTERS]
$ RECALL/ALL
  1 SET DEFAULT [SMITH.LETTERS]
  2 DIRECTORY SEPT*
  3 SHOW DEFAULT
$ RECALL 2
$ DIRECTORY SEPT* 
  %DIRECT-W-NOFILES, no files found
$ RECALL 2
$ SET DEFAULT [SMITH.LETTERS]
  <edit command line>
$ SET DEFAULT [SMITH.MEMOS] 
$ RECALL 2
$ DIRECTORY SEPT* 
 
      

This example starts with a SHOW DEFAULT and a DIRECTORY command. After not finding the file you want, enter the SET DEFAULT command to move to the LETTERS subdirectory. Next use the RECALL/ALL command to see the list of commands you have entered. Enter the RECALL 2 command to repeat the DIRECTORY command in the LETTERS subdirectory. Because you still have not found the file you want, enter the RECALL 2 command again to recall the SET DEFAULT command. (With the entry of the latest DIRECTORY command, SET DEFAULT becomes command 2 in the RECALL list.) Edit the command line so that the system sets the default to the MEMOS subdirectory. Finally, recall the DIRECTORY command to try once more to find the file.

#3

$ TYPE COMMANDS.LIS
DIRECTORY
RUN AUTHORIZE
SET PROCESS/PRIVILEGES=ALL
$ RECALL/INPUT=COMMANDS.LIS
$ RECALL/ALL
  1 SET PROCESS/PRIVILEGES=ALL
  2 RUN AUTHORIZE
  3 DIRECTORY
  4 TYPE COMMANDS.LIS
 
      

This example shows the contents of the COMMANDS.LIS file with the TYPE command, then uses the RECALL/INPUT=COMMANDS.LIS command to place the commands into the recall buffer. Issuing the RECALL/ALL command subsequently shows the numbered display of commands in the recall buffer.

#4

$ RECALL/OUTPUT=NEW_COMMANDS.LIS
$ TYPE NEW_COMMANDS.LIS
TYPE COMMANDS.LIS
DIRECTORY
RUN AUTHORIZE
SET PROCESS/PRIVILEGES=ALL
 
      

This example places the contents of the recall buffer (see the previous example) into the NEW_COMMANDS.LIS file. Note that they are not numbered and in the reverse sequence of the RECALL/ALL command output.


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
9996PRO_041.HTML