OpenVMS DCL Dictionary

Document revision date: 15 July 2002

OpenVMS DCL Dictionary

Contents

Index

In this example, the /REPLACE qualifier requests that the COPY command replace an existing version of the output file with the new file. The first message from the COPY command indicates that it is replacing an existing file. The version number in the output file must be explicit; otherwise, the COPY command creates a new version of the file NEW.DAT.

#4

$ COPY *.COM [MALCOLM.TESTFILES]

#4
$ COPY *.COM [MALCOLM.TESTFILES]

In this example, the COPY command copies the highest versions of files in the current default directory with the file type .COM to the subdirectory MALCOLM.TESTFILES.

#5
$ COPY/LOG .TXT .OLD %COPY-S-COPIED, DKA0:[MAL]A.TXT;2 copied to DKA0:[MAL]A.OLD;2 (1 block) %COPY-S-COPIED, DKA0:[MAL]B.TXT;2 copied to DKA0:[MAL]B.OLD;2 (1 block) %COPY-S-COPIED, DKA0:[MAL]G.TXT;2 copied to DKA0:[MAL]G.OLD;2 (4 blocks) %COPY-S-NEWFILES, 3 files created

$ COPY/LOG *.TXT *.OLD
%COPY-S-COPIED, DKA0:[MAL]A.TXT;2 copied to DKA0:[MAL]A.OLD;2 (1 block)
%COPY-S-COPIED, DKA0:[MAL]B.TXT;2 copied to DKA0:[MAL]B.OLD;2 (1 block)
%COPY-S-COPIED, DKA0:[MAL]G.TXT;2 copied to DKA0:[MAL]G.OLD;2 (4 blocks)
%COPY-S-NEWFILES, 3 files created

In this example, the COPY command copies the highest versions of files with file types .TXT into new files. Each new file has the same file name as an existing file, but a file type .OLD. The last message from the COPY command indicates the number of new files that have been created.

#6
$ COPY/LOG A.DAT,B.MEM C.* %COPY-S-COPIED, DKA0:[MAL]A.DAT;5 copied to DKA0:[MAL]C.DAT;11 (1 block) %COPY-S-COPIED, DKA0:[MAL]B.MEM;2 copied to DKA0:[MAL]C.MEM;24 (58 records) %COPY-S-NEWFILES, 2 files created

$ COPY/LOG  A.DAT,B.MEM C.*
%COPY-S-COPIED, DKA0:[MAL]A.DAT;5 copied to DKA0:[MAL]C.DAT;11 (1 block)
%COPY-S-COPIED, DKA0:[MAL]B.MEM;2 copied to DKA0:[MAL]C.MEM;24 (58 records)
%COPY-S-NEWFILES, 2 files created

In this example, the two input file specifications are separated with a comma. The asterisk (*) wildcard character in the output file specification indicates that two output files are to be created. For each copy operation, the COPY command uses the file type of the input file to name the output file.

#7
$ COPY/LOG *.TXT TXT.SAV %COPY-S-COPIED, DKA0:[MAL]A.TXT;2 copied to DKA0:[MAL]TXT.SAV;1 (1 block) %COPY-S-APPENDED, DKA0:[MAL]B.TXT;2 appended to DKA0:[MAL]TXT.SAV;1 (3 records) %COPY-S-APPENDED, DKA0:[MAL]G.TXT;2 appended to DKA0:[MAL]TXT.SAV;1 (51 records) %COPY-S-NEWFILES, 1 file created

$ COPY/LOG *.TXT TXT.SAV
%COPY-S-COPIED, DKA0:[MAL]A.TXT;2 copied to DKA0:[MAL]TXT.SAV;1 (1 block)
%COPY-S-APPENDED, DKA0:[MAL]B.TXT;2 appended to DKA0:[MAL]TXT.SAV;1 (3 records)
%COPY-S-APPENDED, DKA0:[MAL]G.TXT;2 appended to DKA0:[MAL]TXT.SAV;1 (51 records)
%COPY-S-NEWFILES, 1 file created

In this example, the COPY command copies the highest versions of all files with the file type TXT to a single output file named TXT.SAV. After the first input file is copied, the messages from the COPY command indicate that subsequent files are being appended to the output file.
Note that, if you use the /NOCONCATENATE qualifier in this example, the COPY command creates one TXT.SAV file for each input file. Each TXT.SAV file has a different version number.

#8
$ COPY MASTER.DOC DKA1:[BACKUP]

In this example, the COPY command copies the highest version of the file MASTER.DOC to the device DKA1. If no file named MASTER.DOC exists in the directory [BACKUP], the COPY command assigns the version number of the input file to the output file. You must have write (W) access to the directory [BACKUP] on device DKA1 for the command to work.

#9
$ COPY SAMPLE.EXE DALLAS::DISK2:[000,000]SAMPLE.EXE/CONTIGUOUS

In this example, the COPY command copies the file SAMPLE.EXE on the local node to a file with the same name at remote node DALLAS. The /CONTIGUOUS qualifier indicates that the output file is to occupy consecutive physical disk blocks. You must have write (W) access to the device DISK2 on remote node DALLAS for the command to work.

#10
$ COPY . PRTLND::.

In this example, the COPY command copies all files within the user directory at the local node to the remote node PRTLND. The new files have the same names as the input file. You must have write (W) access to the default directory on remote node PRTLND for the command to work.

#11
$ COPY BOSTON::DISK2:TEST.DAT;5 _To: DALLAS"SAM SECReturn"::DISK0:[MODEL.TEST]TEST.DAT/ALLOCATION=50

In this example, the COPY command copies the file TEST.DAT;5 on the device DISK2 at node BOSTON to a new file named TEST.DAT at remote node DALLAS. The /ALLOCATION qualifier initially allocates 50 blocks for the new file TEST.DAT at node DALLAS. The access control string SAM SECReturn is used to access the remote directory.

#12
$ MOUNT TAPED1: VOL025 TAPE: $ COPY TAPE:. *

In this example, the MOUNT command requests that the volume labeled VOL025 be mounted on the magnetic tape device TAPED1 and assigns the logical name TAPE to the device.
The COPY command uses the logical name TAPE as the input file specification, requesting that all files on the magnetic tape be copied to the current default disk and directory. All the files copied retain their file names and file types.

#13
$ ALLOCATE CR: _CR1: ALLOCATED $ COPY CR1: CARDS.DAT $ DEALLOCATE CR1:

In this example, the ALLOCATE command allocates a card reader for exclusive use by the process. The response from the ALLOCATE command indicates the device name of the card reader, CR1.
After the card reader is allocated, you can place a deck of cards in the reader and enter the COPY command, specifying the card reader as the input file. The COPY command reads the cards into the file CARDS.DAT. The end-of-file (EOF) in the card deck must be indicated with an EOF card (12-11-0-1-6-7-8-9 overpunch).
The DEALLOCATE command relinquishes use of the card reader.

#14
$ COPY [SMITH]MONKEY.DIR [PAINTER] $ COPY [SMITH.MONKEY]. [PAINTER.MONKEY].

In this example, the COPY command creates the new empty directory [PAINTER.MONKEY] that is registered in the [PAINTER]MONKEY.DIR directory file. After the COPY command creates the new [PAINTER]MONKEY.DIR directory file, you can copy or create files in the [PAINTER.MONKEY] directory.
The second COPY command in this example copies files from the [SMITH.MONKEY] directory to the [PAINTER.MONKEY] directory.

#15
$ COPY [SMITH]CATS.DIR [SMITH]DOGS.DIR

In this example, the COPY command creates the new empty directory file, called [SMITH]DOGS.DIR. Use this copy command to create a directory file that has the same attributes as the [SMITH]CATS.DIR file. This command example has the same effect as entering the command:
$ CREATE/DIRECTORY [SMITH.DOGS]

#16
$ COPY [SMITH]TIGER.DIR [SMITH.ANIMALS] $ COPY [SMITH.TIGER]. [SMITH.ANIMALS.TIGER]. $ DELETE [SMITH.TIGER].;* $ SET PROTECTION=W=D TIGER.DIR $ DELETE TIGER.DIR;

In this example, the COPY command creates the new empty directory file called [SMITH.ANIMALS]TIGER.DIR. The subsequent commands in this example then copy the files from the [SMITH.TIGER] directory to the [SMITH.ANIMALS.TIGER] directory, then delete the original TIGER.DIR directory file. Because the TIGER.DIR is a directory file, you must specify a protection code of delete (D) before you can delete the directory file.

COPY/FTP

Transfers files between hosts with possibly dissimilar file systems over a TCP/IP connection by invoking the FTP utility.

Format

COPY/FTP fromFile toFile

Parameters

fromFile
Specifies the name of an existing file (the source file) to be copied.
toFile
Specifies the name of the output file (the destination file) into which the input file is copied.

Description

The COPY/FTP command copies files to and from remote nodes using the File Transfer Protocol (FTP). The services provided by this command are a subset of the architected features of FTP (see vendor documentation for usage of their supplied FTP program).

For OpenVMS to OpenVMS Transfers
If both machines support OpenVMS structured transfers, the /BINARY, /ASCII, and /FDL qualifiers will be ignored. The cooperating OpenVMS FTP client and server will automatically transfer the file with proper OpenVMS attributes.

COPY/FTP commonly supports the asterisk wildcard character (*) in remote file specifications.

Qualifiers

/ANONYMOUS
Causes an anonymous access to the remote node or nodes. /ANONYMOUS is the default remote access. The password passed to the remote node should be in the form of "user@fullyqualifiednodename".
/ASCII
Used to identify an ASCII file (text file). /ASCII is the default.
/BINARY
Required to identify binary files.
/FDL
This qualifier is optional. Causes interaction with an FDL (file definition language) file. If the file is being copied to the local OpenVMS system, a remote FDL file is sought and interpreted for the operation. If the file is being copied outside the local OpenVMS system, an FDL file is generated and copied in addition to the requested file. If the /FDL qualifier is specified and the vendor application does not support it, a warning message may be issued.
/LOG
Displays a message at SYS$OUTPUT when a file is transferred.
/NOSTRUVMS
Used to explicitly disable the negotiation of STRU OpenVMS transfers. Otherwise, some servers will immediately abort when negotiating the feature.
/PASSIVE=option
Controls whether the FTP client or server initiates the data connection. If you do not specify this qualifier, the Internet Protocol appropriate value is used. The values are: OFF for IPv4, ON for IPv6.
The following table describes the /PASSIVE options:

Option Description

OFF The FTP server initiates the data connection.

ON (default) The FTP client initiates the data connection.
This is often used where a firewall between the FTP client and server prevents the server from making an outbound connection.
ON is the default value only if /PASSIVE is specified.

The underlying TCP/IP Networking product must recognize this qualifier and must support FTP passive in order for this qualifier to have an effect.
Note that the /PASSIVE qualifier is equivalent to the FTP PASV command.
/VERBOSE

/NOVERBOSE
Specifies whether all messages (including banner messages) are to be displayed on the terminal. By default, disables the display of the messages.

Option	Description
OFF	The FTP server initiates the data connection.
ON (default)	The FTP client initiates the data connection. This is often used where a firewall between the FTP client and server prevents the server from making an outbound connection. ON is the default value only if /PASSIVE is specified.

Examples

#1
$ COPY/FTP/FDL/ANON rms_indexed_file.idx - remotehst5::"/public/rms.idx.file"

This example transfers the OpenVMS RMS file rms_indexed_file.idx to the remote file public/rms.idx.file on remotehst5 over a TCP/IP connection. Access to the remote host is anonymous and an FDL file is generated and copied along with rms_indexed_file.idx.

#2
$ COPY/FTP/VERBOSE sys$login:login.com - xdelta.zko.dec.com"username password"::sys$login:login.tmp

This example transfers the OpenVMS RMS file sys$login:login.com to the remote file sys$login:login.tmp over a TCP/IP connection while specifying the user name and password on the remote system.

#3
$ COPY/FTP/LOG RESULTS.LOG - _To: grad.uq.edu.au"JONES BYRONBAY"::DKA200$:[JONES.DATA]

In this example, the COPY/FTP command copies the file RESULTS.LOG to the file DKA200$:[JONES.DATA]RESULTS.LOG using the user account JONES, with password BYRONBAY on node grad, that is located in the uq.edu.au internet domain.

COPY/RCP

Copies files from host to host over a TCP/IP connection by invoking the RCP utility.

Format

COPY/RCP fromFile toFile

Parameters

fromFile
Specifies the name of an existing file (the source file) to be copied.
toFile
Specifies the name of the output file (the destination file) into which the input file is copied.

Description

The COPY/RCP command copies one or more files (or directory trees) to or from a remote host using the RCP utility.
The OpenVMS DCL commands for TCP/IP support the same remote file specification format as the DCL commands for DECnet network connections. Some implementations of the file transaction applications support file transfers in which both the source file and the destination file are remote file specifications.
The full format for a remote file specification is as follows:

node"username password account"::filename.ext

If a file resides on a system other than OpenVMS, enclose the name of the file in quotation marks. For example, to access a file named /usr/users/user/Orders on a Tru64 UNIX node named U32, you would use the following format for the file specification:
U32"user password"::"/usr/users/user/Orders"
Note that UNIX systems support case sensitive file specifications.

Qualifiers

/AUTHENTICATE
Specifies that Kerberos authentication should be used for acquiring access to the remote node.
/LOG
Displays a message in SYS$OUTPUT when a file is transferred.
/PRESERVE
Preserves the file protection codes.
/RECURSIVE
Requests a subdirectory copy operation.
/TRUNCATE=USERNAME
Truncates the user name to 8 characters.
/USERNAME=username
Optional qualifier that specifies the remote user name. The standard operation is to log in to a remote system using the same user name as at the local terminal. The command supports quoted parameters in the /USERNAME value.

Example


$ COPY/RCP local_file.c remotehst4"Smith smpw"::rem_file.c

This example copies local_file.c to rem_file.c on the remote host remotehst4 over a TCP/IP connection.

CREATE

Creates a sequential disk file or files.

Format

CREATE filespec[,...]

Parameter

filespec[,...]
Specifies the name of one or more input files to be created. Wildcard characters are not allowed. If you omit either the file name or the file type, the CREATE command does not supply any defaults. The file name or file type is null. If the specified file already exists, a new version is created.

Description

The CREATE command creates a new sequential disk file. In interactive mode, each separate line that you enter after you enter the command line becomes a record in the newly created file. To terminate the file input, press Ctrl/Z.
When you enter the CREATE command from a command procedure file, the system reads all subsequent records in the command procedure file into the new file until it encounters a dollar sign ($) in the first position in a record. Terminate the file input with a line with a dollar sign in column 1 (or with the end of the command procedure).
If you use an existing file specification with the CREATE command, the newly created file has a higher version number than any existing files with the same specification.
If you use the CREATE command to create a file in a logical name search list, the file will only be created in the first directory produced by the logical name translation.
Normally, the owner of the output file will be the same as the creator of the output file. However, if a user with extended privileges creates the output file, the owner will be the owner of the parent directory or any previous versions of the output file.
Extended privileges include any of the following:

SYSPRV (system privilege) or BYPASS
System user identification codes (UICs)
GRPPRV (group privilege) if the owner of the parent directory (or previous version of the output file) is in the same group as the creator of the new output file
An identifier (with the resource attribute) representing the owner of the parent directory (or previous version of the output file)

Qualifiers

/LOG

/NOLOG (default)
Displays the file specification of each new file created as the command executes.
/OWNER_UIC=uic
Requires SYSPRV (system privilege) privilege to specify a user identification code (UIC) other than your own.
Specifies the UIC to be associated with the file being created. Specify the UIC by using standard UIC format as described in the OpenVMS User's Manual.
/PROTECTION=(ownership[:access][,...])
Specifies protection for the file.

Specify the ownership parameter as system (S), owner (O), group (G), or world (W).
Specify the access parameter as read (R), write (W), execute (E), or delete (D).

If you do not specify a value for each access category, or if you omit the /PROTECTION qualifier, the CREATE command applies the following protection for each unspecified category:

File Already Exists? Protection Applied

Yes Protection of the existing file

No Current default protection

Note
If you attempt to create a file with no access, the file is created with the system default RMS protection values. To create a file with no access, use the SET SECURITY/PROTECTION command.

For more information on specifying protection codes, refer to the OpenVMS Guide to System Security.
/VOLUME=n
Places the file on the specified relative volume of a multivolume set. By default, the file is placed arbitrarily in a multivolume set.

File Already Exists?	Protection Applied
Yes	Protection of the existing file
No	Current default protection

Examples

#1
$ CREATE MEET.TXT John, Residents in the apartment complex will hold their annual meeting this evening. We hope to see you there, Regards, Elwood `[Ctrl/Z]`

The CREATE command in this example creates a text file named MEET.TXT in your default directory. The text file MEET.TXT contains the lines that follow until the Ctrl/Z.

#2
$ CREATE A.DAT, B.DAT Input line one for A.DAT... Input line two for A.DAT... . . . `[Ctrl/Z]` Input line one for B.DAT... Input line two for B.DAT... . . . `[Ctrl/Z]` $

After you enter the CREATE command from the terminal, the system reads input lines into the sequential file A.DAT until Ctrl/Z terminates the first input. The next set of input data is placed in the second file, B.DAT. Again, Ctrl/Z terminates the input.

#3
$ FILE = F$SEARCH("MEET.TXT") $ IF FILE .EQS. "" $ THEN CREATE MEET.TXT John, Residents in the apartment complex will hold their annual meeting this evening. We hope to see you there, Regards, Elwood $ ELSE TYPE MEET.TXT $ ENDIF $ EXIT

$ FILE = F$SEARCH("MEET.TXT") 
$ IF FILE .EQS. "" 
$ THEN CREATE MEET.TXT 
  John, Residents in the apartment complex will hold their annual 
  meeting this evening.  We hope to see you there, Regards, Elwood 
$ ELSE TYPE MEET.TXT 
$ ENDIF 
$ EXIT

In this example, the command procedure searches the default disk and directory for the file MEET.TXT. If the command procedure determines that the file does not exist, it creates a file named MEET.TXT using the CREATE command.

CREATE/DIRECTORY

Creates one or more new directories or subdirectories. The /DIRECTORY qualifier is required.
Requires write (W) access to the master file directory (MFD) to create a first-level directory. On a system volume, generally only users with a system user identification code (UIC) or the SYSPRV (system privilege) or BYPASS user privileges have write (W) access to the MFD to create a first-level directory.
Requires write (W) access to the lowest level directory that currently exists to create a subdirectory.

Format

CREATE/DIRECTORY directory-spec[,...]

Parameter

directory-spec[,...]
Specifies the name of one or more directories or subdirectories to be created. The directory specification optionally can be preceded by a device name (and colon [:]). The default is the current default directory. Wildcard characters are not allowed. When you create a subdirectory, separate the names of the directory levels with periods (.).
Note that it is possible to create a series of nested subdirectories with a single CREATE/DIRECTORY command. For example, [a.b.c] can be created, even though neither [a.b] nor [a] exists at the time the command is entered. Each subdirectory will be created, starting with the highest level and proceeding downward.

Description

The CREATE/DIRECTORY command creates new directories as well as subdirectories. Special privileges are needed to create new first-level directories. (See the restrictions noted above.) Generally, users have sufficient privileges to create subdirectories in their own directories. Use the SET DEFAULT command to move from one directory to another.

Qualifiers

/ALLOCATION=n
Specifies the initial number of blocks to be allocated to each of the specified directories. The default allocation is 1 block.
This qualifier is useful for creating large directories, for example MAIL.DIR;1. It can improve performance by avoiding the need for later dynamic expansion of the directory.
This qualifier does not apply to Files-11 ODS-1, ODS-3, or ODS-4 volumes.
/LOG

/NOLOG (default)
Controls whether the CREATE/DIRECTORY command displays the directory specification of each directory after creating it.
/OWNER_UIC=option
Requires SYSPRV (system privilege) privilege for a user identification code (UIC) other than your own.
Specifies the owner UIC for the directory. The default is your UIC. You can specify the keyword PARENT in place of a UIC to mean the UIC of the parent (next-higher-level) directory. If a user with privileges creates a subdirectory, by default, the owner of the subdirectory will be the owner of the parent directory (or the owner of the MFD, if creating a main level directory). If you do not specifiy the /OWNER_UIC qualifier when creating a directory, the command assigns ownership as follows: (1) if you specify the directory name in either alphanumeric or subdirectory format, the default is your UIC (unless you are privileged, in which case the UIC defaults to the parent directory); (2) if you specify the directory in UIC format, the default is the specified UIC.
Specify the UIC by using standard UIC format as described in the OpenVMS User's Manual.
/PROTECTION=(ownership[:access][,...])
Specifies protection for the directory.

Specify the ownership parameter as system (S), owner (O), group (G), or world (W).
Specify the access parameter as read (R), write (W), execute (E), or delete (D).

The default protection is the protection of the parent directory (the next-higher level directory, or the master directory for top-level directories) minus any delete (D) access.
If you are creating a first-level directory, then the next-higher-level directory is the MFD. (The protection of the MFD is established by the INITIALIZE command.)
For more information on specifying protection code, refer to the OpenVMS Guide to System Security.
/VERSION_LIMIT=n
Specifies the number of versions of any one file that can exist in the directory. If you exceed the limit, the system deletes the lowest numbered version. A specification of 0 means no limit. The maximum number of versions allowed is 32,767. The default is the limit for the parent (next-higher-level) directory.
When you change the version limit setting, the new limit applies only to files created after the setting was changed. New versions of files created before the change are subject to the previous version limit.
/VOLUME=n
Requests that the directory file be placed on the specified relative volume of a multivolume set. By default, the file is placed arbitrarily within the multivolume set.

Examples

#1
$ CREATE/DIRECTORY/VERSION_LIMIT=2 $DISK1:[ACCOUNTS.MEMOS]

Previous Next Contents Index

privacy and legal statement

9996PRO_008.HTML