Library /sys$common/syshlp/helplib.hlb  —  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

1  –  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.

2  –  Qualifiers

2.1    /ALLOCATION

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

2.2    /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.

2.3    /BEFORE

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

2.4    /BLOCK_SIZE

       /BLOCK_SIZE=n

    Overrides the default block size (124) used by COPY. You can
    specify a value in the range of 1 through 127.

2.5    /BY_OWNER

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

2.6    /CONFIRM

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

2.7    /CONTIGUOUS

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

2.8    /CREATED

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

2.9    /EXCLUDE

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

2.10    /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.

2.11    /EXTENSION

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

2.12    /LOG

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

2.13    /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.

2.14    /NEW_VERSION

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

2.15    /PROTECTION

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

    Specifies protection for the output file.

    o  Specify the ownership parameter as system (S),  owner (O),
       group (G),  or world (W).

    o  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 VSI
    OpenVMS Guide to System Security.

2.16    /READ_CHECK

       /READ_CHECK
       /NOREAD_CHECK (default)

    Reads each record in the input files twice to verify that it has
    been read correctly.

2.17    /SINCE

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

2.18    /WRITE_CHECK

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

3  –  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 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.
Close Help