HP OpenVMS Systems Documentation

HP OpenVMS DCL Dictionary

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.

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.

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.

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.

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.

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.

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.

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:

Protection of previously existing versions of the output file

Default protection and ACL of the output directory

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.

/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

#1

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

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.

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.

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.