Updated: 11 December 1998

OpenVMS DCL Dictionary

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

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.

Examples

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

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

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

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

This qualifier applies only to Files-11 ODS--2 volumes. It 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.

/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

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

In this example, the CREATE/DIRECTORY command creates a subdirectory named MEMOS in the ACCOUNTS directory on $DISK1. No more than two versions of each file can exist in the directory.

$ CREATE/DIRECTORY/PROTECTION=(SYSTEM:RWED,OWNER:RWED,GROUP,WORLD) - 
_$[KONSTANZ.SUB.HLP]
 
      

In this example, the CREATE/DIRECTORY command creates a subdirectory named [KONSTANZ.SUB.HLP]. The protection on the subdirectory allows read (R), write (W), execute (E), and delete (D) access for the system and owner categories, but prohibits all access for the group or world categories.

$ CREATE/DIRECTORY DISK2:[GOLDSTEIN]
      

In this example, the CREATE/DIRECTORY command creates a directory named [GOLDSTEIN] on the device DISK2. Special privileges are required to create a first-level directory.

$ CREATE/DIRECTORY [HOFFMAN.SUB]
$ SET DEFAULT [HOFFMAN.SUB]
      

In this example, the CREATE/DIRECTORY command creates a subdirectory named [HOFFMAN.SUB]. This directory file is placed in the directory named [HOFFMAN]. The command SET DEFAULT [HOFFMAN.SUB] changes the current default directory to this subdirectory. All files subsequently created are cataloged in [HOFFMAN.SUB].

$ CREATE/DIRECTORY [BOAEN.SUB1.SUB2.SUB3] 
      

In this example, the CREATE/DIRECTORY command creates a top-level directory ([BOAEN]) and three subdirectories ([BOAEN.SUB1], [BOAEN.SUB1.SUB2], and [BOAEN.SUB1.SUB2.SUB3]).

Invokes the Create/FDL utility, which uses the specifications in a File Definition Language (FDL) file to create a new, empty data file. The /FDL qualifier is required.

For more information about the Create/FDL utility, refer to the OpenVMS Record Management Utilities Reference Manual or online help.

Format

CREATE/FDL =fdl-filespec [filespec]

Creates a new logical name table. The /NAME_TABLE qualifier is required.

Format

CREATE/NAME_TABLE table-name

Parameter

table-name

Specifies a string of 1 to 31 characters that identifies the logical name table you are creating. The string can include alphanumeric characters, the dollar sign ($), and the underscore (_). This name is entered as a logical name in either the process directory logical name table (LNM$PROCESS_DIRECTORY) or the system directory logical name table (LNM$SYSTEM_DIRECTORY).

Description

The CREATE/NAME_TABLE command creates a new logical name table. The name of the table is contained within the LNM$PROCESS_DIRECTORY directory table if the table is process-private, and within the LNM$SYSTEM_DIRECTORY directory table if the table is shareable.

Every new table has a parent table, which determines whether the new table is process-private or shareable. To create a process-private table, use the /PARENT_TABLE qualifier to specify the name of a process-private table (the process directory table). To create a shareable table, specify the parent as a shareable table.

If you do not explicitly provide a parent table, the CREATE/NAME_TABLE command creates a process-private table whose parent is LNM$PROCESS_DIRECTORY; that is, the name of the table is entered in the process directory.

Every table has a size quota. The quota may either constrain the potential growth of the table or indicate that the table's size can be virtually unlimited. The description of the /QUOTA qualifier explains how to specify a quota.

To specify an access mode for the table you are creating, use the /USER_MODE, the /SUPERVISOR_MODE, or the /EXECUTIVE_MODE qualifier. If you specify more than one of these qualifiers, only the last one entered is accepted. If you do not specify an access mode, then a supervisor-mode table is created.

To delete a logical name table, use the DEASSIGN command, specify the name of the table you want to delete, and use the /TABLE qualifier to specify the directory table where the name of the table was entered.

For more information about logical name tables, refer to the OpenVMS System Manager's Manual.

Qualifiers

/ATTRIBUTES[=(keyword[,...])]

Specifies attributes for the logical name table. If you specify only one keyword, you can omit the parentheses. If you do not specify the /ATTRIBUTES qualifier, no attributes are set.

You can specify the following keywords for attributes:

CONFINE	Does not copy the table name or the logical names contained in the table into a spawned subprocess; used only when creating a private logical name table. If a table is created with the CONFINE attribute, all names subsequently entered into the table are also confined.
NO_ALIAS	No identical names (either logical names or names of logical name tables) may be created in an outer (less privileged) mode in the current directory. If you do not specify the NO_ALIAS attribute, then the table may be "aliased" by an identical name created in an outer access mode. Deletes any previously created identical table names in an outer access mode in the same logical name table directory.
SUPERSEDE	Creates a new table that supersedes any previous (existing) table that contains the name, access mode, and directory table that you specify. The new table is created regardless of whether the previous table exists. (If you do not specify the SUPERSEDE attribute, the new table is not created if the previous table exists.) If you specify or accept the default for the qualifier /LOG, you receive a message indicating the result.

/EXECUTIVE_MODE

Requires SYSNAM (system logical name) privilege.

Creates an executive-mode logical name table. If you specify executive mode, but do not have SYSNAM privilege, a supervisor-mode logical name table is created.

/LOG (default)

/NOLOG

Controls whether an informational message is generated when the SUPERSEDE attribute is specified, or when the table already exists but the SUPERSEDE attribute is not specified. The default is the /LOG qualifier; that is, the informational message is displayed.

/PARENT_TABLE=table

Requires either create (C) access to the parent table and write (W) access to the system directory or the SYSNAM privilege.

Specifies the name of the parent table. The parent table determines whether a table is private or shareable; it also determines the size quota of the table. If you do not specify a parent table, the default table is LNM$PROCESS_DIRECTORY. A shareable table has LNM$SYSTEM_DIRECTORY as its parent table. The parent table must have the same access mode or a higher level access mode than the one you are creating.

/PROTECTION=(ownership[:access][,...])

Applies the specified protection to shareable name tables.

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

For more information on specifying protection codes, refer to the OpenVMS Guide to System Security.

The /PROTECTION qualifier affects only shareable logical name tables; it does not affect process-private logical name tables.

/QUOTA=number-of-bytes

Specifies the size limit of the logical name table. The size of each logical name entered in the new table is deducted from this size limit. The new table's quota is statically subtracted from the parent table's quota holder. The parent table's quota holder is the first logical name table encountered when working upward in the table hierarchy that has an explicit quota and is therefore its own quota holder. If the /QUOTA qualifier is not specified or the size limit is 0, the parent table's quota holder becomes the new table's quota holder and space is dynamically withdrawn from it whenever a logical name is entered in this new table. If the table has no quota holder and you specify /QUOTA=0, the table has unlimited quota.

/SUPERVISOR_MODE (default)

Creates a supervisor-mode logical name table. If you do not specify a mode, a supervisor-mode logical name table is created.

/USER_MODE

Creates a user-mode logical name table. If you do not explicitly specify a mode, a supervisor-mode logical name table is created.

Note User-mode logical names are automatically deleted when invoking and exiting a command procedure.

Examples

$ CREATE/NAME_TABLE TEST_TAB
$ SHOW LOGICAL TEST_TAB
%SHOW-S-NOTRAN, no translation for logical name TEST_TAB
$ SHOW LOGICAL/TABLE=LNM$PROCESS_DIRECTORY TEST_TAB
      

In this example, the CREATE/NAME_TABLE command creates a new table called TEST_TAB. By default, the name of the table is entered in the process directory. The first SHOW LOGICAL command does not find the name TEST_TAB because it does not, by default, search the process directory table. You must use the /TABLE qualifier to request that the process directory be searched.

$ CREATE/NAME_TABLE/ATTRIBUTES=CONFINE EXTRA
$ DEFINE/TABLE=EXTRA MYDISK DISK4:
$ DEFINE/TABLE=LNM$PROCESS_DIRECTORY LNM$FILE_DEV -
_$ EXTRA, LNM$PROCESS, LNM$JOB, LNM$GROUP, LNM$SYSTEM
$ TYPE MYDISK:[COHEN]EXAMPLE1.LIS
      

This example creates a new logical name table called EXTRA that is created with the CONFINE attribute. Therefore, the EXTRA table and the names it contains will not be copied to subprocesses.

Next, the logical name MYDISK is placed into the table EXTRA. To use the name MYDISK in file specifications, you must make sure that the table EXTRA is searched when RMS parses file specifications. To do this, you can define a process-private version of the logical name LNM$FILE_DEV to include the name EXTRA as one of its equivalence strings. (The system uses LNM$FILE_DEV to determine the tables to search during logical name translation for device or file specifications, and will use the process-private version of the logical name before using the default system version.) After you define LNM$FILE_DEV, the system searches the following tables during logical name translation: EXTRA, your process table, your job table, your group table, and the system table. Now, you can use the name MYDISK in a file specification and the equivalence string DISK4 will be substituted.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

9996PRO_008.HTML