Document revision date: 30 March 2001

## OpenVMS DCL Dictionary

Previous | Contents | Index

The equivalence string definition can contain different types of information. Definitions often consist of DCL commands. For example, you can assign SHOW TIME to the zero key. When you press 0, the system displays the current date and time. Other definitions can consist of text strings to be appended to command lines. When you define a key to insert a text string, use the /NOTERMINATE qualifier so that you can continue typing more data after the string has been inserted.

In most instances you will want to use the echo feature. The default setting is /ECHO. With /ECHO set, the key definition is displayed on the screen each time you press the key.

You can use the /STATE qualifier to increase the number of key definitions available on your terminal. The same key can be assigned any number of definitions, as long as each definition is associated with a different state. State names can contain any alphanumeric characters, dollar signs, and underscores. Be sure to create a state name that is easy to remember and type and, if possible, one that might remind you of the types of definitions you created for that state. For example, you can create a state called SETSHOW. The key definitions for this state might all refer to various DCL SET and SHOW commands. If you are used to the EDT Editor, you might define a state as GOLD. Then, using the /IF_STATE qualifier, you can assign different definitions to keys used in combination with a key defined as GOLD.

The SET KEY command changes the keypad state. Use the SHOW KEY command to display key definitions and states.

### Qualifiers

> #### /ECHO (default)

> #### /NOECHO

> Displays the equivalence string on your screen after the key has been pressed. You cannot use the /NOECHO qualifier with the /NOTERMINATE qualifier.

> #### /ERASE

> #### /NOERASE (default)

> Determines whether the current line is erased before the key translation is inserted.

> #### /IF_STATE=(state-name,...)

> #### /NOIF_STATE

> Specifies a list of one or more states, one of which must be in effect for the key definition to work. The /NOIF_STATE qualifier has the same meaning as /IF_STATE=current_state. The state name is an alphanumeric string. States are established with the /SET_STATE qualifier or the SET KEY command. If you specify only one state name, you can omit the parentheses. By including several state names, you can define a key to have the same function in all the specified states.

> #### /LOCK_STATE

> #### /NOLOCK_STATE (default)

> Specifies that the state set by the /SET_STATE qualifier remain in effect until explicitly changed. (By default, the /SET_STATE qualifier is in effect only for the next definable key you press or the next read-terminating character that you type.) This qualifier can be specified only with the /SET_STATE qualifier.

> #### /LOG (default)

> #### /NOLOG

> Displays a message indicating that the key definition has been successfully created.

> #### /SET_STATE=state-name

> #### /NOSET_STATE (default)

> Causes the specified state-name to be set when the key is pressed. (By default, the current locked state is reset when the key is pressed.) If you have not included this qualifier with a key definition, you can use the SET KEY command to change the current state. The state name can be any alphanumeric string; specify the state as a character string enclosed in quotation marks.

> #### /TERMINATE

> #### /NOTERMINATE (default)

> Specifies whether the current equivalence string is to be processed immediately when the key is pressed (equivalent to entering the string and pressing Return). By default, you can press other keys before the definition is processed. This allows you to create key definitions that insert text into command lines, after prompts, or into other text that you are entering.

###

#### Examples

#1
    $ DEFINE/KEY PF3 "SHOW TIME" /TERMINATE
    %DCL-I-DEFKEY, DEFAULT key PF3 has been defined
    $ [PF3]
    $ SHOW TIME
      14-DEC-2001 14:43:59

> In this example, the DEFINE/KEY command defines the PF3 key on the keypad to perform the SHOW TIME command. DEFAULT refers to the default state.

#2
    $ DEFINE/KEY PF1 "SHOW " /SET_STATE=GOLD/NOTERMINATE/ECHO
    %DCL-I-DEFKEY, DEFAULT key PF1 has been defined
    $ DEFINE/KEY PF1 " DEFAULT" /TERMINATE/IF_STATE=GOLD/ECHO
    %DCL-I-DEFKEY, GOLD key PF1 has been defined
    $ [PF1]
    $ [PF1]
    $ SHOW DEFAULT
    DISK1:[JOHN.TEST]

> In this example, the first DEFINE/KEY command defines the PF1 key to be the string SHOW. The state is set to GOLD for the subsequent key. The /NOTERMINATE qualifier instructs the system not to process the string when the key is pressed. The second DEFINE/KEY command defines the use of the PF1 key when the keypad is in the GOLD state. When the keypad is in the GOLD state, pressing PF1 causes the current read to be terminated.

> If you press the PF1 key twice, the system displays and processes the SHOW DEFAULT command.

> The word DEFAULT in the second line of the example indicates that the PF1 key has been defined in the default state. Note the space before the word DEFAULT in the second DEFINE/KEY command. If the space is omitted, the system fails to recognize DEFAULT as the keyword for the SHOW command.

#3
    $ SET KEY/STATE=ONE
    %DCL-I-SETKEY, keypad state has been set to ONE
    $ DEFINE/KEY PF1 "ONE"
    %DCL-I-DEFKEY, ONE key PF1 has been defined
    $ DEFINE/KEY/IF_STATE=ONE PF1 "ONE"
    %DCL-I-DEFKEY, ONE key PF1 has been defined

> This example shows two ways to define the PF1 key to be "ONE" for state ONE.

> The second DEFINE/KEY command shows the preferred method for defining keys. This method eliminates the possibility of error by specifying the state in the same command as the key definition.

## DELETE

> Deletes one or more files from a mass storage disk volume.

> Requires delete (D) access to the file and write (W) access to the parent directory. If the target file is itself a directory, the directory must be empty.

### Format

> DELETE filespec[,...]

### Parameter

> #### filespec[,...]

> Specifies the names of one or more files to be deleted from a mass storage disk volume. The first file specification must contain an explicit or default directory specification plus an explicit file name, file type, and version number. Subsequent file specifications need contain only a version number; the defaults will come from the preceding specification. The asterisk (*) and the percent sign (%) wildcard characters can be used in any of the file specification fields.

> If you omit the directory specification or device name, the current default device and directory are assumed.

> If the file specification contains a null version number (a semicolon (;) followed by no file version number), a version number of 0, or one or more spaces in the version number, the latest version of the file is deleted.

> To delete more than one file, separate the file specifications with either commas (,) or plus signs (+).

### Description

> The DELETE command deletes one or more files from a mass storage disk volume. This command requires delete (D) access to the file and write (W) access to the parent directory. If the target file is itself a directory, the directory must be empty.

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

> #### /BITMAP=n,x

> Enables the system manager to delete one or more active bitmaps to make memory resources available. If a bitmap is deleted, then former virtual unit members can only be added with a full copy.

> Requires ownership of the device or VOLPRO protection.

> For additional information on bitmaps, refer to Volume Shadowing for OpenVMS.

> #### /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 delete 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)

> 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 you specify the /ERASE qualifier, 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 delete 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.

> #### /LOG

> #### /NOLOG (default)

> Controls whether the DELETE command displays the file specification of each file after its deletion.

> #### /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 about 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 deleting 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 a FID 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
    $ DELETE COMMON.SUM;2

> The DELETE command deletes the file COMMON.SUM;2 from the current default disk and directory.

#2
    $ DELETE *.OLD;*

> The DELETE command deletes all versions of files with file type .OLD from the default disk directory.

#3
    $ DELETE  ALPHA.TXT;*, BETA;*, GAMMA;*

> The DELETE command deletes all versions of the files ALPHA.TXT, BETA.TXT, and GAMMA.TXT. The command uses the file type of the first input file as a temporary default. Note, however, that some form of version number (here specified as the asterisk (*) wildcards) must be included in each file specification.

#4
    $ DELETE /BEFORE=15-APR/LOG *.DAT;*
    %DELETE-I-FILDEL, DISK2:[MAIN]ASSIGN.DAT;1 deleted (5 block)
    %DELETE-I-FILDEL, DISK2:[MAIN]BATCHAVE.DAT;3 deleted (4 blocks)
    %DELETE-I-FILDEL, DISK2:[MAIN]BATCHAVE.DAT;2 deleted (4 blocks)
    %DELETE-I-FILDEL, DISK2:[MAIN]BATCHAVE.DAT;1 deleted (4 blocks)
    %DELETE-I-FILDEL, DISK2:[MAIN]CANCEL.DAT;1 deleted (2 blocks)
    %DELETE-I-FILDEL, DISK2:[MAIN]DEFINE.DAT;1 deleted (3 blocks)
    %DELETE-I-FILDEL, DISK2:[MAIN]EXIT.DAT;1 deleted (1 block)
    %DELETE-I-TOTAL, 7 files deleted (23 blocks)

> The DELETE command deletes all versions of all files with file type .DAT that were either created or updated before April 15 of this year. The /LOG qualifier not only displays the name of each file deleted, but also the total number of files deleted.

#5
    $ DELETE A.B;

> The DELETE command deletes the file A.B with the highest version number.

#6
    $ DELETE/CONFIRM/SINCE=TODAY [MEIER.TESTFILES]*.OBJ;*
    DISK0:[MEIER.TESTFILES]AVERAG.OBJ;1, delete? [N]:Y
    DISK0:[MEIER.TESTFILES]SCANLINE.OBJ;4, delete? [N]:N
    DISK0:[MEIER.TESTFILES]SCANLINE.OBJ;3, delete? [N]:N
    DISK0:[MEIER.TESTFILES]SCANLINE.OBJ;2, delete? [N]:N
    DISK0:[MEIER.TESTFILES]WEATHER.OBJ;3, delete? [N]:Y

> The DELETE command examines all versions of files with file type .OBJ in the subdirectory [MEIER.TESTFILES], and locates those that were created or modified today. Before deleting each file, it requests confirmation that the file should be deleted. The default response---N---is given in brackets.

#7
    $ DIRECTORY [.SUBTEST]
    %DIRECT-W-NOFILES, no files found
    $ SET PROTECTION SUBTEST.DIR/PROTECTION=OWNER:D
    $ DELETE SUBTEST.DIR;1

> Before the directory file SUBTEST.DIR is deleted, the DIRECTORY command is used to verify that there are no files cataloged in the directory. The SET PROTECTION command redefines the protection for the directory file so that it can be deleted; then the DELETE command deletes it.

#8
    $ DELETE DALLAS"THOMAS SECRET"::DISK0:[000,000]DECODE.LIS;1

> This DELETE command deletes the file DECODE.LIS;1 from the directory [000,000] on device DISK0 at remote node DALLAS. The user name and password follow the remote node name.

#9
    $ DELETE NODE12::"DISK1:DEAL.BIG"
    $ DELETE NODE12::DISK1:DEAL.BIG;

> Either of these DELETE commands can be used to delete the file DEAL.BIG on device ZZZ1 at remote node NODE12. Note that the DELETE command requires an explicit version number in a file specification, but the file to be deleted is on a remote node whose file syntax does not recognize version numbers. (NODE12 is an RT-11 node.) Therefore, the file specification must either be enclosed in quotation marks (" ") or entered with a null version number (that is, a trailing semicolon [;]).

## DELETE/CHARACTERISTIC

> Deletes the definition of a queue characteristic previously established with the DEFINE/CHARACTERISTIC command. The /CHARACTERISTIC qualifier is required.

> Requires OPER (operator) privilege.

### Format

> DELETE/CHARACTERISTIC characteristic-name

### Parameter

> #### characteristic-name

> Specifies the name of the characteristic to be deleted.

### Description

> The DELETE/CHARACTERISTIC command deletes a characteristic from the system characteristic table.

> To modify a characteristic's name or number, you must delete and redefine the characteristic.

### Qualifier

> #### /LOG

> #### /NOLOG (default)

> Controls whether the DELETE/CHARACTERISTIC command displays the name of each characteristic after its deletion.

### Example

    $ DEFINE/CHARACTERISTIC BLUE 7
       .
       .
       .
    $ DELETE/CHARACTERISTIC BLUE
    $ DEFINE/CHARACTERISTIC BLUE_INK 7

> The DEFINE/CHARACTERISTIC command in this example establishes the characteristic BLUE, with number 7, to mean blue ink ribbons for printers. To change the name of the characteristic, enter the DELETE/CHARACTERISTIC command. Then enter another DEFINE/CHARACTERISTIC command to rename the characteristic to BLUE_INK, using the characteristic number 7.

## DELETE/ENTRY

> Deletes one or more print or batch jobs. The jobs can be in progress or waiting in the queue. The /ENTRY qualifier is required.

> Requires manage (M) access to the queue, or delete (D) access to the specified jobs.

### Format

> DELETE/ENTRY =(entry-number[,...]) [queue-name[:]]

### Parameters

> #### entry-number[,...]

> Specifies the entry number (or a list of entry numbers) of jobs to be deleted. If you specify only one entry number, you can omit the parentheses. If you do not specify a queue name, you can delete entries from multiple queues.

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

> #### queue-name[:]

> Specifies the name of the queue where the jobs are located. The queue name can refer either to the queue to which the job was submitted or to the queue where the job is executing. The queue-name parameter is optional syntax; however, when you specify a queue name, the operating system uses it to verify an entry in the specific queue before deleting the entry.

### Description

> The DELETE/ENTRY command deletes one or more jobs from a queue. If you specify a queue name and more than one entry number with a DELETE/ENTRY command, all the jobs must be located in the same queue.

> You can delete jobs that are currently executing, as well as jobs that are in other states. For example, DELETE/ENTRY can delete a job that is currently in a holding or a pending state.

### Qualifier

> #### /LOG

> #### /NOLOG (default)

> Controls whether the DELETE/ENTRY command displays the entry number of each batch or print job that it deletes.

### Examples

#1
    $ PRINT/HOLD   ALPHA.TXT
    Job ALPHA (queue SYS$PRINT, entry 110) holding
       .
       .
       .
    $ DELETE/ENTRY=110  SYS$PRINT

> The PRINT command in this example queues a copy of the file ALPHA.TXT in a HOLD status, to defer its printing until a SET ENTRY/RELEASE command is entered. The system displays the job name, the entry number, the name of the queue in which the job was entered, and the status. Later, the DELETE/ENTRY command requests that the entry be deleted from the queue SYS$PRINT.

#2
    $ SUBMIT/AFTER=18:00  WEATHER
    Job WEATHER (queue SYS$BATCH, entry 203) holding until 14-DEC-2001
    18:00
    $ SUBMIT/HOLD/PARAMETERS=SCANLINE  DOFOR
    Job DOFOR (queue SYS$BATCH, entry 210) holding
       .
       .
       .
    $ DELETE/ENTRY=(203,210)/LOG
    %DELETE-W-SEARCHFAIL, error searching for 203
    -JBC-E-NOSUCHENT, no such entry
    %DELETE-I-DELETED, entry 210 aborting or deleted

> The SUBMIT commands in this example queue the command procedures WEATHER.COM and DOFOR.COM for processing as batch jobs. WEATHER.COM is queued for execution after 6:00 P.M. DOFOR.COM is queued in a HOLD status and cannot execute until you enter a SET ENTRY/RELEASE command. Later, the DELETE/ENTRY/LOG command requests that the system delete both these entries from the queue and display a message indicating that the entries have been deleted.

> The job WEATHER (entry 203) has completed by the time the DELETE/ENTRY/LOG command is entered; therefore, entry 203 no longer exists. Note that a message indicates that there is no entry 203 in the queue. The job DOFOR (entry 210) is in a HOLD status when the DELETE/ENTRY/LOG command is entered. Thus, the system deletes entry 210 from the queue and displays a message to that effect.

#3
    $ PRINT CHAPTER8.MEM
    Job CHAPTER8 (queue SYS$PRINT, entry 25) pending on queue SYS$PRINT
       .
       .
       .
    $ SHOW QUEUE SYS$PRINT
    Printer queue SYS$PRINT, on PARROT::PARROT$LPA0, mounted form DEFAULT
    Entry  Jobname         Username             Status
    -----  -------         --------             ------
       24  CHAPTER7        SMITH                Pending
       25  CHAPTER8        SMITH                Pending
    $ DELETE/ENTRY=25 SYS$PRINT

> The PRINT command in this example submits the file CHAPTER8.MEM to the printer queue SYS$PRINT. Later, user SMITH needs to edit the file again before printing it. Using the SHOW QUEUE command, SMITH verifies that the job is still pending and that the entry number for the job is 25. SMITH then enters the DELETE/ENTRY command to delete the job from the queue.

Previous | Next | Contents | Index

| privacy and legal statement |
9996PRO_012.HTML