 |
HP OpenVMS DCL Dictionary
APPEND
Adds the contents of one or more specified input files to the end of
the specified output file.
Format
APPEND input-filespec[,...] output-filespec
Parameters
input-filespec[,...]
Specifies the names of one or more input files to be appended. Multiple
input files are appended to the output file in the order specified. If
you specify more than one input file, separate each file specification
with either a comma (,) or a plus sign (+).
The asterisk (*) and the percent sign (%) wildcard characters are
allowed in the input file specifications.
output-filespec
Specifies the name of the file to which the input files will be
appended.
You must specify at least one field in the output file specification.
If you do not specify a device or directory, the APPEND command uses
the current default device and directory. Other unspecified fields
default to the corresponding fields of the first input file
specification.
If you use the asterisk (*) wildcard character in any fields of the
output file specification, the APPEND command uses the corresponding
field of the input file specification. If you are appending more than
one input file, the APPEND command uses the corresponding fields from
the first input file.
Description
The APPEND command is similar in syntax and function to the COPY
command. Normally, the APPEND command adds the contents of one or more
files to the end of an existing file without incrementing the version
number. The /NEW_VERSION qualifier causes the APPEND command to create
a new output file if no file with that name exists.
Note that there are special considerations for using the APPEND command
with DECwindows compound documents. For more information, see the
Guide to OpenVMS File Applications.
Qualifiers
/ALLOCATION=number-of-blocks
Forces the initial allocation of the output file to the specified
number of 512-byte blocks. If you do not specify the /ALLOCATION
qualifier, or if you specify it without the number-of-blocks
parameter, the initial allocation of the output file is determined by
the size of the input file.
The allocation size is applied only if a new file is actually created
by using the /NEW_VERSION qualifier.
/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 specify none 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 on specifying time values, see the
OpenVMS User's Manual or the online help topic Date.
/BLOCK_SIZE=n
Overrides the default block size (124) used by COPY. You can specify a
value in the range of 1 through 127.
/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
OpenVMS User's Manual.
/CONFIRM
/NOCONFIRM (default)
Controls whether a request is issued before each append 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.
/CONTIGUOUS
/NOCONTIGUOUS
Specifies that the output file must occupy physically contiguous disk
blocks. By default, the APPEND command creates an output file in the
same format as the corresponding input file and does not report an
error if not enough space exists for a contiguous allocation. This
qualifier is relevant only with the /NEW_VERSION qualifier.
If an input file is contiguous, the APPEND command attempts to create a
contiguous output file, but does not report an error if there is not
enough space. If you append multiple input files of different formats,
the output file may or may not be contiguous. Use the /CONTIGUOUS
qualifier to ensure that the output file is contiguous.
/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 specify none of these four time
qualifiers, the default is the /CREATED qualifier.
/EXCLUDE=(filespec[,...])
Excludes the specified files from the append operation. You can include
a directory but not a device in the file specification. Wildcard
characters (* and %) 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 specify none
of these four time qualifiers, the default is the /CREATED qualifier.
/EXTENSION=number-of-blocks
Specifies the number of blocks to be added to the output file each time
the file is extended. When you specify the /EXTENSION qualifier, the
/NEW_VERSION qualifier is assumed and need not be typed on the command
line. This qualifier is relevant only with the /NEW_VERSION qualifier.
The extension value is applied only if a new file is actually created.
/LOG
/NOLOG (default)
Controls whether the APPEND command displays the file specifications of
each file appended. If the /LOG qualifier is specified, the command
displays the file specifications of the input and output files as well
as the number of blocks or records appended after each append operation.
/MODIFIED
Modifies the time value specified with the /BEFORE or the /SINCE
qualifier. The /MODIFIED qualifier selects files according to the dates
on which they were last modified. This qualifier is incompatible with
the /BACKUP, /CREATED, and /EXPIRED qualifiers, which also allow you to
select files according to time attributes. If you specify none of these
four time modifiers, the default is the /CREATED qualifier.
/NEW_VERSION
/NONEW_VERSION (default)
Controls whether the APPEND command creates a new output file if the
specified output file does not exist. (By default, the specified output
file already exists.) If the specified output file does not already
exist, use the /NEW_VERSION qualifier to create a new output file. If
the output file does exist, the /NEW_VERSION qualifier is ignored and
the input file is appended to the output file.
/PROTECTION=(ownership[:access][,...])
Specifies protection for the output 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).
The default protection, including any protection attributes not
specified, is that of the existing output file. If no output file
exists, the current default protection applies. This qualifier is
relevant only with the /NEW_VERSION qualifier.
For more information on specifying protection codes, see the
HP OpenVMS Guide to System Security.
/READ_CHECK
/NOREAD_CHECK (default)
Reads each record in the input files twice to verify that it has been
read correctly.
/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
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 on specifying time values, see the
OpenVMS User's Manual or the online help topic Date.
/WRITE_CHECK
/NOWRITE_CHECK (default)
Reads each record in the output file after the record is written to
verify
that it was appended successfully and that the output file can
subsequently be read without error.
Examples
| #1 |
$ APPEND TEST3.DAT TESTALL.DAT
|
The APPEND command appends the contents of the file TEST3.DAT from the
default disk and directory to the file TESTALL.DAT, also located on the
default disk and directory.
| #2 |
$ APPEND/NEW_VERSION/LOG *.TXT MEM.SUM
%APPEND-I-CREATED, USE$:[MAL]MEM.SUM;1 created
%APPEND-S-COPIED, USE$:[MAL]A.TXT;2 copied to USE$:[MAL]MEM.SUM;1 (1 block)
%APPEND-S-APPENDED, USE$:[MAL]B.TXT;3 appended to USE$:[MAL]MEM.SUM;1 (3 records)
%APPEND-S-APPENDED, USE$:[MAL]G.TXT;7 appended to USE$:[MAL]MEM.SUM;1 (51 records)
|
The APPEND command appends all files with file types of .TXT to a file
named MEM.SUM. The /LOG qualifier requests a display of the
specifications of each input file appended. If the file MEM.SUM does
not exist, the APPEND command creates it, as the output shows. The
number of blocks or records shown in the output refers to the source
file and not to the target file total.
| #3 |
$ APPEND/LOG A.DAT, B.MEM C.*
%APPEND-S-APPENDED, USE$:[MAL]A.DAT;4 appended to USE$:[MAL]C.DAT;4 (2 records)
%APPEND-S-APPENDED, USE$:[MAL]B.MEM;5 appended to USE$:[MAL]C.DAT;4 (29 records)
|
The APPEND command appends the files A.DAT and B.MEM to the file C.DAT,
which must already exist.
| #4 |
$ APPEND/LOG A.* B.*
%APPEND-S-APPENDED, USE$:[MAL]A.DAT;5 appended to USE$:[MAL]B.DAT;1 (5 records)
%APPEND-S-APPENDED, USE$:[MAL]A.DOC;2 appended to USE$:[MAL]B.DAT;1 (1 record)
|
Both the input and output file specifications contain wildcard
characters in the file type field. The APPEND command appends each file
with a file name of A to an existing file with B as its file name. The
file type of the first input file located determines the output file
type.
| #5 |
$ APPEND BOSTON"BILL_BESTON YANKEE"::DEMO1.DAT, DEMO2.DAT
$ _To: DALLAS::DISK1:[MODEL.TEST]TEST.DAT
|
This APPEND command adds the contents of the files DEMO1.DAT and
DEMO2.DAT at remote node BOSTON to the end of the file TEST.DAT at
remote node DALLAS.
|
