The APPEND/APPLICATION_PROTOCOL=FTAM command accesses the FTAM
appending utility, which appends files between FTAM systems within
an OSI network. The appending utility operates on a combination of
local and remote FTAM or on remote files only. Using this command,
you can:
o Append an input file to a single output file
o Concatenate two or more input files into a single output file
If only local files are specified, the APPEND/APPLICATION_
PROTOCOL=FTAM utility passes the command to the RMS appending
utility. In that case, all command qualifiers operate in the
standard manner documented in OpenVMS help.
1 – Format
APPEND/APPLICATION_PROTOCOL=FTAM [/qualifier(s)] input-file-spec
[,...] output-file-spec
The following table describes the variables in this format state-
ment:
__________________________________________________________________
Variable Explanation
__________________________________________________________________
/qualifier An RMS qualifier of the APPEND command. For a
full description of supported qualifiers, see
individual qualifier subtopics; for a summary,
see the "Qualifier" subtopic.
input-file-spec A file specification of an input (source) file,
which can be either local or remote.
[,...] A file list containing file specifications for
one or more additional input files. Within a file
list, you must precede each additional file spec-
ification with either a comma (,) or a plus sign
(+) with or without a space. To end an input file
list, either omit the comma or plus sign between
the last input file specification and the output
file specification or press <RET>.
Input files can be from the same or different
FTAM systems.
output-file- The name of an output file. Because FTAM
spec always creates only one output file, the
APPEND/APPLICATION_PROTOCOL=FTAM command ac-
cepts only one output-file specification.
For local output files, appending a file to a
local directory is controlled by the same rules
that control the RMS appending utility. If you
specify no directory, the utility places the
output file in your default directory. If you
specify another local directory for which you
have write privileges, the utility places the
output file in that directory.
For remote output files, always specify the file
designation. For information on where a remote
FTAM system places an output file that is created
remotely using FTAM, see the documentation of the
remote system.
__________________________________________________________________
2 – Wildcards
Wildcards provide a method for generalizing a file designation to
encompass a set of local files. Standard DCL wildcard techniques
work for both local (RMS) files and remote files for those remote
FTAM systems that support the NBS-9 document type. If using
wildcard techniques with remote FTAM systems does not work, you
should complete the file designation.
The supported wildcard characters include an asterisk (*) to
represent a text string, a percent sign (%) to represent a single
character, or empty brackets ([ ]) to represent all files in the
local default RMS directory.
3 – Qualifiers
The availability of APPEND command qualifiers for the
APPEND/APPLICATION_PROTOCOL=FTAM command varies for local and
remote files. For local FTAM (RMS) files, the FTAM append utility
supports most of the DCL APPEND command qualifiers. For remote
files, only a few of those qualifiers are supported.
For APPEND command qualifiers used with local files, the FTAM ap-
pending utility generally implements standard RMS default values
and actions. The exceptions are indicated by the term "nonstan-
dard" in the qualifier descriptions.
Any APPEND command qualifier that is unlisted here is accepted as
a null qualifier, which produces no effect on the outcome of the
APPEND command.
3.1 /ALLOCATION
/ALLOCATION
/ALLOCATION=n
Qualifier type: Output file qualifier
Supported file Local and remote
types:
This qualifier sets the initial allocation for the output file to
the number of 512-byte blocks specified by n.
Default value: Size of input file
3.2 /BACKUP
/BACKUP
Qualifier type: Input file qualifier
Supported file types: Local
This qualifier selects files according to the dates of their most
recent backup. It is relevant only with /BEFORE or /SINCE and is
incompatible with /CREATED, /EXPIRED, and /MODIFIED.
Default value: Creation date
3.3 /BEFORE
/BEFORE
/BEFORE=time
Qualifier type: Input file qualifier
Supported file types: Local
This qualifier selects only those files that are dated before
the time specified using absolute time (a specific date and/or
time or a keyword - TODAY, TOMORROW, or YESTERDAY) or combination
time (absolute plus delta time). Associated qualifiers: /BACKUP,
/CREATED, /EXPIRED, or /MODIFIED. For information on specifying
absolute and delta time, see the "OpenVMS User's Manual".
Default value: Today
3.4 /BY_OWNER
/BY_OWNER
/BY_OWNER=uic
Qualifier type: Input file qualifier
Supported file types: Local
This qualifier selects only files whose user identification code
(UIC) matches the specified UIC.
Default value: UIC of current process
3.5 /CHARACTER_SET
/CHARACTER_SET=
This qualifier specifies which character set the file data belongs
to, and instructs FTAM to encode the data accordingly. For example,
to copy file data of the Japanese character sets Kanji and Katakana,
the user must supply the CHARACTER_SET= qualifier with the value
JP_INTAP2.
Default value: No character set specified
3.6 /CONFIRM
/CONFIRM
/NOCONFIRM
Qualifier type: Input file qualifier
Supported file types: Local and remote
This qualifier controls whether a request is issued before each
append operation asking you to indicate whether to append that
file. The local sytem prompts you by asking: "Append filename?
[N]." Issue one of the following responses:
o To affirm appending a specific file: Yes, True, or 1
o To prevent appending a specific file: No, FALSE, 0, or <RET>
o To continue appending without further confirmations: ALL
o To stop all appending: Quit or <CTRL/Z>
Abbreviations and any combination of upper- and lowercase letters
are acceptable.
Default value: Unconfirmed
3.7 /CONTIGUOUS
/CONTIGUOUS
/NOCONTIGUOUS
Qualifier type: Output file qualifier
Supported file types: Local
This qualifier indicates whether the output file must occupy
consecutive physical disk blocks.
Default value: Noncontiguous storage (nonstandard default)
3.8 /CREATED
/CREATED
Qualifier type: Input file qualifier
Supported file types: Local
This qualifier selects files based on their dates of creation. It
is relevant only with /BEFORE or /SINCE and is incompatible with
/BACKUP, /EXPIRED, and /MODIFIED.
Default value: Creation date
3.9 /EXCLUDE
/EXCLUDE=(file[,...])
Qualifier type: Input file qualifier
Supported file types: Local
This qualifier excludes from appending a file whose file specifi-
cation matches any excluded file specification. When excluding a
single file, you can omit the parentheses. Device names and ver-
sion numbers are unsupported. Using wildcards for file name and
type is permitted.
Default value: All input files are copied
3.10 /EXPIRED
/EXPIRED
Qualifier type: Input file qualifier
Supported file types: Local
This qualifier selects files according to their scheduled expi-
ration dates. It is relevant only with /BEFORE or /SINCE and is
incompatible with /BACKUP, /CREATED, and /MODIFIED.
Default value: Creation date
3.11 /EXTENSION
/EXTENSION=n
Qualifier type: Output file qualifier
Supported file types: Local
This qualifier specifies the number of blocks to be added to the
output file each time the file is extended. If you do not specify
/EXTENSION, the default extension attribute of the output file is
determined by the extension attribute of the corresponding input
file.
Default value: The default extension for the local system
- usually 3 (nonstandard default)
3.12 /JOURNAL
/JOURNAL=(filename )
Qualifier type: Global qualifier
Supported file Local (RMS) files
types:
This qualifier controls whether you want the FTAM service provider
to negotiate recovery and restart with the peer FTAM entity (if it
supports recovery). When the /JOURNAL qualifier is present, then
the FTAM protocol machine will insert checkpoints within the data
and will maintain a docket that contains recovery-related
information.
If an error occurs during data transfer, and the image has not
exited, the FTAM protocol machine will attempt to recover from the
error, using the checkpoints.
Default action: No journaling
3.13 /LOG
/LOG
/NOLOG
Qualifier type: Global qualifier
Supported file types: Local and remote
This qualifier controls whether the FTAM appending utility dis-
plays the input and output file specifications of each local file
it appends. The /LOG qualifier displays following information:
o The file specifications of the input and output files
o The number of blocks or records appended
o The total number of new files created
Default value: No logging
3.14 /MODIFIED
/MODIFIED
Qualifier type: Input file qualifier
Supported file types: Local
This qualifier selects files according to the dates on which they
were last modified. It is relevant only with /BEFORE or /SINCE and
is incompatible with /BACKUP, /CREATED, and /EXPIRED.
Default value: Creation date
3.15 /NEW_VERSION
/NEW_VERSION
Qualifier type: Output file qualifier
Supported file Local (RMS) and remote files
types:
This qualifier controls whether the FTAM appending facility cre-
ates a new output file if the specified output file does not ex-
ist. If the specified output file does exist, the /NEW_VERSION
qualifier is ignored and the input file is appended to the output
file.
Default date: /NONEW_VERSION
3.16 /PARAMETER=CONCURRENCY_CONTROL
/PARAMETER=CONCURRENCY_CONTROL=(parameter: value)
Qualifier type: Global qualifier
Supported file Remote files
types:
This qualifier gives users the ability to specify the file-locking
parameters and values that are defined in ISO standard 8571. The
possible file-locking parameters are:
o READ
o INSERT
o REPLACE
o EXTEND
o ERASE
o READ_ATTRIBUTE
o CHANGE_ATTRIBUTE
o DELETE_FILE
The allowed values for these file-locking parameters are:
o not-required
o shared
o exclusive OR
o no-access
Default action: No concurrency_control is used
3.17 /PARAMETER=CREATE_PASSWORD
/PARAMETER=CREATE_PASSWORD=(password)
Qualifier type: Global qualifier
Supported file Local (RMS) and remote files
types:
This qualifier gives users the ability to pass a password value,
if the responding FTAM entity (an FTAM listener) requires a pass-
word in order for anyone to create a file on its file system. This
file system password is not the same as a password for logging
into an account.
Default action: No create_password used
3.18 /PARAMETER=SECURITY
/PARAMETER=SECURITY=(ACTION=(ACCESS-REQUEST[,ACCESS-REQUEST...]),
[CONCURRENCY=(CA-NAME:CA-KEY[,CA-NAME:CA-KEY...])],
[PASSWORD=(APWD-NAME:APWD-STRING[,APWD-NAME:APWD-STRING...])],
[IDENTITY=USER-IDENTITY-STRING],
[LEGAL=LEGAL-QUAL-STRING])
This qualifier allows the user to implement FTAM security group
functions. These functions only apply for local to remote, or
remote to remote file copying.
The string list specified on the command line must be enclosed within
single or double quotes. All white space appearing within these
quotes is ignored.
The entire security string must be enclosed within parentheses, and
multiple entries within the parenthesis must be separated by commas.
You can abbreviate parameter values as long as there are
enough characters for a unique value.
You can use a dash (-) to continue any portion of the security group
specification onto a new line.
You can specify more than one security group, however you must
flag each new group list element with its own /PARAMETER=SECURITY
qualifier. Note that the legal qualification parameter can only be
specified once.
The ACTION=(ACCESS-REQUEST) is mandatory. CONCURRENCY, PASSWORD,
IDENTITY, and LEGAL are optional.
The allowed values for ACCESS-REQUEST, CA-NAME, and APWD-NAME
are READ, INSERT, REPLACE, EXTEND, ERASE CHANGE-ATTRIBUTE,
READ-ATTRIBUTE, and DELETE-FILE.
The allowed values for CA-KEY are NOT-REQUIRED, SHARED, EXCLUSIVE,
and NO-ACCESS.
The expected input for APWD-STRING, USER-IDENTITY, and
LEGAL-QUAL-STRING is GraphicString.
Default action: No security is used
3.19 /PROTECTION
/PROTECTION=(code)
Qualifier type: Output file qualifier
Supported file types: Local
This qualifier defines the protection to be applied to the output
file.
Default value: The default protection of the OpenVMS user
process (nonstandard default)
3.20 /SINCE
/SINCE=time
Qualifier type: Input file qualifier
Supported file types: Local
This qualifier selects only those files that are dated after
the time specified using absolute time (a specific date and/or
time or a keyword - TODAY, TOMORROW, or YESTERDAY) or combination
time (absolute plus delta time). Associated qualifiers: /BACKUP,
/CREATED, /EXPIRED, or /MODIFIED. For information on specifying
absolute and delta time, see the "OpenVMS User's Manual".
Default value: Today
4 – Examples
1. $ APPEND/APPLICATION=FTAM TEST.DAT AMIGUITA::"\DIR\FILE" <RET>
This command appends the single local file TEST.DAT to
\DIR\FILE on AMIGUITA.
Note that without the double quotation marks (" ") surrounding
\DIR\FILE, RMS would generate the following error:
%APPEND-F-OPENIN, error opening AMIGUITA::\DIR\FILE as input
-RMS-F-SYN, file specification syntax error
2. $ APPEND/APPLICATION_PROTOCOL=FTAM TEST.DAT AMIGUITA::* <RET>
This command appends the single local file TEST.DAT to TEST.DAT
on AMIGUITA.
3. $ APPEND/APPLICATION_PRO=FTAM TEST.DAT LESAMIES::"test.dat" <RET>
This command appends the single local file TEST.DAT to test.dat
on LESAMIES. Since the output-file designation is enclosed in
double quotation-marks ("-"), the lower case characters entered
in the command are retained in the output-file designation sent
to the remote FTAM system.
4. $ APPEND/APPLICATION_PROTOCOL=FTAM *.DAT FREUNDE::NEWFILE <RET>
This command concatenates alphabetically the .DAT files in the
local default directory. Concatenation ceases if any file dif-
fers in file organization, record format, or record attributes
from those of the first .DAT file listed in the directory.
Note that the specified output-file designation, NEWFILE, lacks
locational information. Therefore, the responding FTAM applica-
tion places the file NEWFILE in whatever location serves as its
default location for files created by an FTAM process.
5. $ APPEND/APPLICATION_PROTOCOL=FTAM AMIGUITA::"/DIR/FILE" <RET>
_To: AMIGUITA::"/NEWMAIN/FILE" <RET>
This command appends the file /DIR/FILE on AMIGUITA to
/NEWMAIN/FILE on the same system. Two remote systems could
just as easily be involved. Note that the file passes through
the local FTAM system but is not opened or stored locally.
6. $ APPEND/APPLICATION_PROTOCOL=FTAM -
_$ FREUNDE::"^VOL>MAIN>FILE.EXT", TEST.DAT <RET>
_To: LARGETEST.DAT <RET>
This command concatenates the remote input file,
^VOL>MAIN>FILE.EXT and the local input file, TEST.DAT,
(assuming that they have a common file organization and data
type) into the local output file, LARGETEST.DAT.
Note that without the double quotation marks (" ") surround-
ing ^VOL>DIR>FILE.EXT, DCL would interpret ^ as a parameter
delimiter and generate the following error:
%DCL-W-PARMDEL, invalid parameter delimiter ...
\^VOL\
7. $ APPEND/APPLICATION_PROTOCOL=FTAM TEST.DAT -
_$ AMIGUITA::"/MAIN/SUB/TEST/DAT" /ALLOCATION=90 <RET>
This command sets the future file size of /MAIN/SUB/TEST/DAT to
90 blocks.
Note that without the double quotation marks (" ") surrounding
/MAIN/SUB/FILE, DCL would interpret /MAIN as a qualifier and
generate the following error:
%DCL-W-IVQUAL, unrecognized qualifier ...
\MAIN\