HP OpenVMS Systems Documentation

Enables the operating system to transfer files to or from operating systems that do not support OpenVMS file organizations. The transfer occurs over a DECnet network communications link that connects OpenVMS systems and non OpenVMS operating system nodes.

Using DECnet services, the EXCHANGE/NETWORK command can perform any of the following tasks:

• Transfer files between an OpenVMS node and a non OpenVMS system node.
• Transfer a group of input files to a group of output files.
• Transfer files between two non OpenVMS nodes, provided those nodes share DECnet connections with the OpenVMS node that issues the EXCHANGE/NETWORK command.

Format

EXCHANGE/NETWORK input-filespec[,...] output-filespec

Parameters

input-filespec[,...]

Specifies the name of an existing file to be transferred. The asterisk (*) and the percent sign (%) wildcard characters are allowed. If you specify more than one file, separate the file specifications with commas (,).

output-filespec

Specifies the name of the output file into which the input is transferred.

You must specify at least one field in the output file specification. If you omit the device or directory, your current default device and directory are used. The EXCHANGE/NETWORK command replaces any other missing fields (file name, file type, and version number) with the corresponding field of the input file specification.

The EXCHANGE/NETWORK command creates a new output file for every input file that you specify.

You can use the asterisk (*) wildcard character in place of the file name, the file type, or the version number. The EXCHANGE/NETWORK command uses the corresponding field in the related input file to name the output file. You can also use the asterisk (*) wildcard character in the output file specification to direct EXCHANGE/NETWORK to create more than one output file. For example:

$ EXCHANGE/NETWORK A.A,B.B MYPC::*.C

This EXCHANGE/NETWORK command creates the files A.C and B.C at the non OpenVMS target node MYPC.

A more complete explanation of the asterisk (*) and the percent sign (%) wildcard characters and version numbers follows in the Description section.

Description

The EXCHANGE/NETWORK command imposes the following restrictions:

• Transfers of files can occur only between disk devices. (If a disk device is not the desired permanent residence for the file, you must either move the file to a disk before issuing the command or retrieve the file from a disk after the command completes.)
• The remote system must have a block size of 512 bytes, where a byte is 8 bits long.
• The nodes transferring files must support the DECnet Data Access Protocol (DAP).

The OpenVMS Record Management Services (RMS) facility provides the operating system access to records in OpenVMS RMS files. To transfer OpenVMS RMS files between two nodes where both nodes are OpenVMS nodes, use one of the other DCL commands (such as COPY, APPEND, or CONVERT), as appropriate. These commands recognize RMS file organizations and are designed to ensure that RMS record structures are preserved as your files are moved.

Use the EXCHANGE/NETWORK command to transfer files between OpenVMS nodes and non OpenVMS nodes when the differences in the file organizations would otherwise prevent the transfer or could lead to undesirable results. While using the COPY command ensures that both the contents and the attributes of a replicated file are preserved, the EXCHANGE/NETWORK command has more advantages. The EXCHANGE/NETWORK command offers you explicit control of your record attributes during file transfers, with the opportunity to make a file usable on several different operating systems.

The EXCHANGE/NETWORK command transfers files between OpenVMS nodes and non OpenVMS nodes connected to the same DECnet network. If the non OpenVMS system does not support OpenVMS file organizations, the EXCHANGE/NETWORK command can modify or discard file and record attributes during the transfer. However, if the target system is an OpenVMS node, you have the option of applying new file and record attributes to the output file by supplying a File Definition Language (FDL) file, as described later in this section. The EXCHANGE/NETWORK command provides a number of defaults to handle the majority of transfers properly; however, in some situations you need to know your file or record format requirements at both nodes.

OpenVMS File and Record Attributes

All RMS files in the OpenVMS environment include stored information, known as the file and record attributes, to describe the file and record characteristics. File attributes consist of items such as file organization, file protection, and file allocation information. Record attributes consist of items such as the record format, record size, key definitions for indexed files, and carriage control information. These attributes define the data format and access methods for the OpenVMS RMS facility.

Non OpenVMS operating systems that do not support OpenVMS file organizations have no means of storing file and record attributes with their files. Transferring an OpenVMS file to a non OpenVMS system that is unable to store and handle file and record attributes can result in most of this information being discarded. Removing these attributes from a file can render it useless if it must be returned to the OpenVMS system.

Transferring Files to OpenVMS Nodes

When you transfer files to an OpenVMS system from a non OpenVMS system, the files typically assume default file and record attributes; however, you can specify the attributes that you want the file to acquire in a File Definition Language (FDL) file. Alternatively, if transferring a CDA document, enter the following command after the EXCHANGE/NETWORK command:

$ SET FILE/SEMANTICS=[ddif,dtif] document-name.doc

If you specify an FDL file with the /FDL qualifier, the FDL file determines the characteristics of the output file. This feature is useful in establishing compatible file and record attributes when you transfer a file from a non OpenVMS system to an OpenVMS system; however, when you use an FDL file, you also assume responsibility for determining the required characteristics.

For more information on FDL files, see the OpenVMS Record Management Utilities Reference Manual.

Transferring Files to Non OpenVMS Nodes

The EXCHANGE/NETWORK command discards file and record attributes associated with an OpenVMS file during a transfer to a non OpenVMS system that does not support OpenVMS file organizations. Be aware that the loss of file and record attributes in the transfer can render the output file useless for many applications.

Selecting Transfer Modes

The EXCHANGE/NETWORK command has four transfer mode options: AUTOMATIC, BLOCK, RECORD, and CONVERT. For most file transfers, AUTOMATIC is sufficient. The AUTOMATIC transfer mode option allows the EXCHANGE/NETWORK command to transfer files using either block or record I/O. The selection is based on the input file organization and the operating systems involved.

Selecting the BLOCK transfer mode option forces the EXCHANGE/NETWORK command to open both the input and output files for block I/O access. The input file is then transferred to the output file block by block. Use this transfer mode when you transfer executable images. It is also useful when you must preserve a file's content exactly, which is a common requirement when you store files temporarily on another system or when cooperating applications exist on the systems.

Selecting the RECORD transfer mode option forces the EXCHANGE/NETWORK command to open both the input file and output file for record I/O access. The input file is then transferred to the output file record by record. This transfer mode is primarily used for transferring text files.

Selecting the CONVERT transfer mode option forces the EXCHANGE/NETWORK command to open the input file for RECORD access and the output file for BLOCK access. Records are then read in from the input file, packed into blocks, and are written to the output file. This transfer mode is primarily used for transferring files with no implied carriage control. For example, to transfer a file created with DIGITAL Standard Runoff (DSR) to a DECnet DOS system, you must use the CONVERT transfer mode option. To transfer the resultant output file back to an OpenVMS node, use the AUTOMATIC transfer mode option.

Wildcard Characters

The asterisk (*) and the percent sign (%) wildcard characters are permitted in the file specifications and follow the behavior typical of other OpenVMS system commands with respect to the OpenVMS node.

When more than one input file is specified, but the asterisk (*) or the percent sign (%) wildcard characters are not specified in the output file specification, the first input file is copied to the output file, and each subsequent input file is transferred and given a higher version number of the same output file name. Note that the files are not concatenated into a single output file. Also note that when you transfer files to foreign systems that do not support version numbers, only one output file results, and it is the last input file.

To create multiple output files, specify multiple input files and use at least one of the following:

• An asterisk (*) wildcard character in the output file name, file type, or version number field
• Only a node name, a device name, or a directory specification as the output file specification

When you create multiple output files, the EXCHANGE/NETWORK command uses the corresponding field from each input file in the output file name.

Use the /LOG qualifier when you specify multiple input and output files to verify that the files were copied as you intended.

Version Numbers

The following guidelines apply when the target node file formats accept version numbers.

If no version numbers are specified for input and output files, the EXCHANGE/NETWORK command (by default) assigns a version number to the output files that is either of the following:

• The version number of the input file
• A version number one greater than the highest version number of an existing file with the same file name and file type

When the output file version number is specified by an asterisk (*) wildcard character, the EXCHANGE/NETWORK command uses the version numbers of the associated input files as the version numbers of the output files.

If the output file specification has an explicit version number, the EXCHANGE/NETWORK command normally uses that number for the output file specification. However, if an equal or higher version of the output file already exists, no warning message is issued, the file is copied, and the version number is set to a value one greater than the highest version number already existing.

File Protection and Creation/Revision Dates

The EXCHANGE/NETWORK command treats an output file as a new file when any portion of the output file name is specified explicitly. When the output node is an OpenVMS system, the creation date for a new file is set to the current time and date. However, if the output file specification consists only of the asterisk (*) and the percent sign (%) wildcard characters, the output file no longer qualifies as a new file, and, therefore, the creation date of the input file is used. That is, if the output file specification is one of the following, the creation date becomes that of the input file: *, *.*, or *.*;*.

The revision date of the output file is always set to the current time and date; the backup date is set to zero. The output file is assigned a new expiration date. (Expiration dates are set by the file system if retention is enabled; otherwise, they are set to zero.)

When the target node is an OpenVMS node, the protection and access control list (ACL) of the output file is determined by the following parameters, in the following order:

1. Protection of previously existing versions of the output file
2. Default protection and ACL of the output directory
3. Process default file protection

For an introduction to ACLs, see the HP OpenVMS Guide to System Security.

On OpenVMS systems, the owner of the output file usually is the same as the creator of the output file. However, if a user with extended privileges creates the output file, the owner is either the owner of the parent directory or the owner of a previous version of the output file, if one exists.

Extended privileges include any of the following:

• SYSPRV (system privilege) or BYPASS
• System user identification code (UIC)
• 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

/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 do not specify any 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 about specifying time values, see the OpenVMS User's Manual or the online help topic Date.

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

/CONFIRM

/NOCONFIRM (default)

Controls whether a request is issued before each file transfer 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 do not specify any of these four time qualifiers, the default is the /CREATED qualifier.

/EXCLUDE=(filespec[,...])

Excludes the specified files from the file transfer 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 do not specify any of these four time qualifiers, the default is the /CREATED qualifier.

/FDL=fdl-filespec

Specifies that the output file characteristics are described in the File Definition Language (FDL) file. Use this qualifier when you require special output file characteristics. For more information about FDL files, see the OpenVMS Record Management Utilities Reference Manual.

Use of the /FDL qualifier implies that the transfer mode is block by block; however, the transfer mode you specify with the /TRANSFER_MODE qualifier prevails.

/LOG

/NOLOG (default)

Controls whether the EXCHANGE/NETWORK command displays the file specifications of each file copied.

When you use the /LOG qualifier, the EXCHANGE/NETWORK command displays the following for each copy operation:

• The file specifications of the input and output files
• The number of blocks or the number of records copied (depending on whether the file is copied on a block-by-block or record-by-record basis)

/MODIFIED

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /MODIFIED qualifier selects files according to the date on which they were last modified. This time qualifier is incompatible with the /BACKUP, /CREATED, and /EXPIRED qualifiers, which also allow you to select files according to time attributes. If you do not specify any of these four time qualifiers, 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, JOB_LOGIN, LOGIN, TODAY (default), TOMORROW, or YESTERDAY. Specify one of the following time 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, see the OpenVMS User's Manual or the online help topic Date.

/STYLE=keyword

Specifies the file name format for display purposes.

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.

See the HP OpenVMS System Manager's Manual, Volume 1: Essentials for more information.

/SYMLINK=keyword

The valid keywords for this qualifier are [NO]WILDCARD and [NO]ELLIPSIS. Descriptions are as follows:

Keyword	Explanation
WILDCARD	Indicates that symlinks are enabled during wildcard searches.
NOWILDCARD	Indicates that symlinks are disabled during directory wildcard searches.
ELLIPSIS	Equivalent to WILDCARD (included for command symmetry).
NOELLIPSIS	Indicates that symlinks are matched for all wildcard fields except for ellipsis.

If the file named in the EXCHANGE/NETWORK command is a symlink, the command operates on the symlink target.

/TRANSFER_MODE=option

Specifies the I/O method to be used in the transfer. This qualifier is useful for all file formats. You can specify any one of the following options:

Option	Function
AUTOMATIC	Allows the EXCHANGE/NETWORK command to determine the appropriate transfer mode. This is the default transfer mode.
BLOCK	Opens both the input and output files for block I/O and transfers the files block by block.
CONVERT[=option[,...]]	Reads records from the input file, packs them into blocks, and writes them to the output file in block mode. The options listed in the following table determine what additional information is inserted during the transfer.
RECORD	Opens both the input and output files for record I/O and transfers the files record by record. The target system must support record operations, and the input file must be record oriented.

The following four options are available with the CONVERT transfer mode to control the insertion of special characters in the records:

Option	Function
CARRIAGE_CONTROL	Any carriage control information in the input file is interpreted, expanded into actual characters, and included with each record.
COUNTED	The length of each record, in bytes, is included at the beginning of the record. The length includes all FIXED_CONTROL, CARRIAGE_CONTROL, and RECORD_SEPARATOR information in each record.
FIXED_CONTROL	All variable length with fixed control record (VFC) information is written to the output file as part of the data. This information follows the record length information, if the COUNTED option was specified.
RECORD_SEPARATOR= separator	A 1- or 2-byte record separator is inserted between each record. Record separator characters are the last characters in the record. The three choices for separator characters are as follows: CR: Specifies carriage return only. LF: Specifies line feed only. CRLF: Specifies carriage return and line feed.

Examples

$ EXCHANGE/NETWORK VMS_FILE.DAT KUDOS::FOREIGN_SYS.DAT
 
      

In this example, the EXCHANGE/NETWORK command transfers the file VMS_FILE.DAT located in the current default device and directory to the file FOREIGN_SYS.DAT on the non OpenVMS node KUDOS. Because the /TRANSFER_MODE qualifier was not explicitly specified, the EXCHANGE/NETWORK command automatically determines whether the transfer method should be block or record I/O.

$ EXCHANGE/NETWORK/TRANSFER_MODE=BLOCK -
_$ KUDOS::FOREIGN_SYS.DAT VMS_FILE.DAT
 
      

In this example, the EXCHANGE/NETWORK command transfers the file FOREIGN_SYS.DAT from the non OpenVMS node KUDOS to the file VMS_FILE.DAT in the current default device and directory. Block I/O is specified for the transfer mode.

$ EXCHANGE/NETWORK/FDL=VMS_FILE_DEFINITION.FDL -
_$ KUDOS::REMOTE_FILE.TXT  VMS_FILE.DAT
 
      

In this example, the EXCHANGE/NETWORK command transfers the file REMOTE_FILE.TXT on node KUDOS to the file VMS_FILE.DAT. The file attributes for the output file VMS_FILE.DAT are obtained from the File Definition Language (FDL) source file VMS_FILE_DEFINITION.FDL. Because the qualifier /FDL is specified and the /TRANSFER_MODE qualifier is omitted, the transfer mode uses block I/O, by default.

For more information about creating FDL files, see the OpenVMS Record Management Utilities Reference Manual.

$ EXCHANGE/NETWORK -
_$ /TRANSFER_MODE=CONVERT=(CARRIAGE_CONTROL,COUNTED, -
_$ RECORD_SEPARATOR=CRLF,FIXED_CONTROL) -
_$ PRINT_FILE.TXT  KUDOS::*
 
      

In this example, the EXCHANGE/NETWORK command transfers the file PRINT_FILE.TXT from the current default device and directory to the file PRINT_FILE.TXT on the non OpenVMS node KUDOS. The use of the CONVERT option with the /TRANSFER_MODE qualifier forces the input file to be read in record by record, modified as specified by the CONVERT options that follow, and written to the output file block by block. As many records as will fit are packed into the output blocks.

The CONVERT option CARRIAGE_CONTROL specifies that carriage control information is converted to ASCII characters and inserted before the data or appended to the record, depending on whether prefix control or postfix control, or both, are used.

The CONVERT option FIXED_CONTROL specifies that any fixed control information be translated to ASCII characters and inserted at the beginning of the record.

The CONVERT option RECORD_SEPARATOR=CRLF appends the two specified characters, carriage return and line feed, to the end of the record.

The CONVERT option COUNTED specifies that the total length of the record must be counted (once the impact of all the previous convert options have been added), and the result is to be inserted at the beginning of the record, in the first 2 bytes.