FILECOPY Modifiers

The following text describes the FILECOPY modifiers and options that you can specify with the FILECOPY task requests.

Unless you specify overriding FILECOPY modifiers, the program uses the following defaults for each task request:

  • The date used in checking is the TODAY value extracted from the system. In the task requests CREATED, ACCESSED, and UPDATED, FILECOPY does its testing with the AFTER option.

  • The WFL deck that results from a successful run is processed by a ZIP command.

  • The result is a simple COPY operation, without COMPARE, BACKUP, or SKIPEXCLUSIVE.

  • FILECOPY does not create an index file.

  • FILECOPY prints an output summary.

  • The usercode under which FILECOPY is running is prefixed to all file names except files that explicitly specify a usercode, to system files, or to a file name that includes a wild-card character.

  • If you do not specify a family name, FILECOPY assumes that the files reside on the family DISK.

  • FILECOPY copies files to a tape whose default name is that of the task request (CREATED, EXPIRED, and so forth) with no attribute values specified for DENSITY, UNITNO, or SERIALNO.

  • If the task request is EXPIRED, all files are considered to be expired if they were last accessed more than SAVECONSTANT days before the current system date. The default value for SAVECONSTANT attribute is 60.

Syntax

<filecopy modifier> 

──┬──────────┬─<file specification>─┬──────────┬───────────────────────┤
  └─<option>─┘                      └─<option>─┘

<file specification> 

──┬─ FILES ───┬─ ( ──<source>── ) ─┬───────────────┬───────────────────┤
  ├─ INCLUDE ─┤                    └─<destination>─┘
  └─ EXCLUDE ─┘

<source> 

  ┌◄───────── , ────────┐ 
──┴─<source from group>─┴──────────────────────────────────────────────┤

<source from group> 

  ┌◄───────────── , ────────────┐
──┴─┬─<file name>─────────────┬─┴─┬───────────────┬────────────────────┤
    └─<source directory name>─┘   └─<from clause>─┘

<source directory name> 

──┬─ = ────────────────┬───────────────────────────────────────────────┤
  ├─<file name>─┬──────┤
  │             └─ /= ─┤
  └─ *USERCODE/= ──────┘

<from clause> 

── FROM ─┬─<family name>─┬────────────────────────────────────┬────────┤
         │               └─ ( ─┬─────────────┬─┬─ PACK ─┬─ ) ─┤
         │                     └─ KIND ── = ─┘ └─ DISK ─┘     │
         ├─ PACK ─────────────────────────────────────────────┤
         └─ DISK ─────────────────────────────────────────────┘

<destination> 

── TO ──<identifier>───────────────────────────────────────────────────────►
►─┬──────────────────────────────────────────────────────────────────────┬─┤
  │     ┌◄─────────────────────────── , ───────────────────────────┐     │
  └─ ( ─┴─┬─ /1\ ─┬─────────────┬─<output medium>────────────────┬─┴─ ) ─┘
          │       └─ KIND ── = ─┘                                │
          ├─ /1\ ── BLOCKSIZE ── = ──<blocksize value>───────────┤
          ├─ /1\ ── CDCOPIES ── = ──<CDCOPIES value>─────────────┤
          ├─┬─ /1\ ── COPYAS ──────┬─ = ──<unquoted name>────────┤
          │ ├─ /1\ ── HOSTNAME ────┤                             │
          │ └─ /1\ ── SCRATCHPOOL ─┘                             │
          ├─ /1\ ── DENSITY ── = ──<density value>───────────────┤
          ├─ /1\ ── SERIALNO ── = ──<serial number list>─────────┤
          ├─ /1\ ── LIBMAINTAPPEND ── = ──<libmaintappend value>─┤
          ├─ /1\ ── LIBMAINTDIR ── = ──<boolean value>───────────┤
          ├─ /1\ ── MULTIVOLUME ── = ──<boolean value>───────────┤
          ├─ /1\ ── SAVEFACTOR ── = ──<savefactor value>─────────┤
          ├─ /1\ ── AUTOUNLOAD ── = ──<autounload value>─────────┤
          └─ /1\ ── ENCRYPT ── = ──<encrypt value>───────────────┘

<output medium> 

──┬─ PACK ─┬───────────────────────────────────────────────────────────┤
  ├─ DISK ─┤
  ├─ CD ───┤
  └─ TAPE ─┘

<blocksize value> 

  ┌◄────────────┐
──┴─/6\─<digit>─┴──────────────────────────────────────────────────────┤

<CDCOPIES value>

A single digit whose value is between 1 and 9.

<unquoted name>> 

──<alphanumeric character>─┬───────────────────────────────────────┬───┤
                           │ ┌◄──────────────────────────────────┐ │
                           └─┴─/16\─┬─<alphanumeric character>─┬─┴─┘
                                    ├─<hyphen>─────────────────┤
                                    └─<underscore>─────────────┘

<serial number list> 

      ┌◄──────────── , ────────────┐
      │   ┌◄────────────┐          │
── ( ─┴─┬─┴─/6\─<digit>─┴────────┬─┴─ ) ───────────────────────────────┤
        └─<serial number string>─┘

<serial number string> 

      ┌◄──────────────────────────────┐
── " ─┴─/6\─<EBCDIC string character>─┴─ " ────────────────────────────┤

<savefactor value>

An integer between 0 and 999.

<digit>

Any one of the decimal digits 0 through 9, inclusive.

<hyphen>

The single hyphen (-) character.

<underscore>

The single underscore (_) character.

<autounload value> 

──┬─ DONTCARE ─┬───────────────────────────────────────────────────────┤
  ├─ ON ───────┤
  └─ OFF ──────┘

<encrypt value> 

──┬─ NO ─────┬─────────────────────────────────────────────────────────┤
  ├─ TDES ───┤
  └─ AES256 ─┘

<locatecapable value> 

──┬─ DONTCARE ─┬───────────────────────────────────────────────────────┤
  ├─ ON ───────┤
  └─ OFF ──────┘

Explanation

Components Used in FILECOPY Modifiers explains the various components that can be used to construct FILECOPY modifiers.

Table 27. Components Used in FILECOPY Modifiers

Component

Description or Explanation

<file specification>

Specifies a list of files to be considered, included, or excluded. You must specify either a FILES list or an INCLUDE or an EXCLUDE list.

FILES (<source>)

Causes the files listed in the source variable to be checked against the criteria from the FILECOPY task request. FILECOPY selects files for copying that meet the criteria and that are not excluded in some way. FILECOPY uses GETSTATUS calls to obtain the files specified in this list. FILECOPY checks the files against the specified testing criteria.

INCLUDE (<source>)

Causes the files listed in the source variable to be specified for copying, whether or not they meet the specified criteria.

INCLUDE overrides EXCLUDE; that is, if a file is on an EXCLUDE list, specified either by name or by FILEKIND value, and is explicitly included by name, the file is included.

EXCLUDE (<source>)

Causes the files listed in the source variable not to be selected for copying, even if they meet the specified criteria. You can also exclude files based on their FILEKIND attribute values (CODE, DATA, and so forth) as specified under “FILECOPY Options” later in this section.

Both the file name and the FILEKIND option cannot be used in the same EXCLUDE clause, although each type can appear alone several times as shown in the following example:

EXCLUDE <file name> EXCLUDE FILEKIND(<filekind>)

<source from group>

In a <source from group> phrase, a FROM clause applies to all source file names in that source from group. If you do not specify a FROM clause, FILECOPY assumes that the files reside on the family DISK.

<file name>

If the file name is not followed by a slash and an equal sign (/=), it refers to only one file.

<source directory name>

Specifies the name of the input files as follows:

  • The equal sign (=) specifies all files.

  • The <file name>/= format specifies a directory. The program processes all files under that directory.

  • The *USERCODE/= format specifies all usercoded files.

<from clause>

Specifies the location of the input files. Input files cannot reside on CD-ROM or TAPE. Input files must reside on DISK.

Use the <family name> to name a particular family.

You can specify a FROM clause for each input file in the task. If you do not specify a FROM clause for an input file, FILECOPY assumes that the file resides in the location specified by the next-mentioned FROM clause. For example, the statement FILES A, B FROM PACK specifies that files A and B both reside on PACK.

If you do not specify a FROM clause, or if no next-mentioned FROM clause exists, FILECOPY assumes that the files reside on the family DISK. For example, the statement FILES A, B specifies that files A and B both reside on DISK. The statement FILES A, B FROM PACK, C specifies that files A and B reside on PACK and that file C resides on DISK.

<destination>

Specifies the name and type of the output medium. If you do not specify a destination, FILECOPY copies files to a tape whose default name is that of the task request (CREATED, ACCESSED, and so forth) with no UNITNO or SERIALNO attribute value supplied.

TO <identifier>

Labels the output medium.

<output medium>

Specifies the output medium (TAPE, PACK, DISK, or CD) to which the files are to be copied.

KIND = <output medium>

Specifies the output medium (TAPE, PACK, DISK, or CD) to which the files are to be copied.

CDCOPIES = <digit>

Specifies the number of copies of a CD-ROM that are to be burned. The default value of CDCOPIES is 1.

When data is copied to a CD-ROM, the data is first copied from the source media to a temporary disk file. The data in the temporary disk file is formatted exactly as it is to appear on the CD-ROM.

This temporary disk file is then copied to a CD-R or CD-RW drive. CDCOPIES causes the disk file to be copied to the CD-R or CD-RW drive up to nine times, without having to recopy the data from the source media.

COPYAS = <unquoted name>

Allows files being copied from disk to disk to be renamed.

Specifies a string to be inserted as the first node when files are being copied from disk to disk. For usercoded files, the string is inserted after the usercode node.

The length of the node must not exceed 17 characters and quotes are not permitted.

When COPYAS is specified, some of the other copy-related functions (for example, BACKUP) are not permitted.

If the COPYAS node cannot be added to a file name, a comment line is written in the WFL indicating that the file was copied without being renamed.

DENSITY = <density value>

Specifies the density of the medium to which the files are to be copied.

SERIALNO = <serial number list>

Specifies a serial number list of the destination volumes to be used. Serial numbers must be no more than 6 characters long and are not allowed in a task that uses the PARTITION option.

HOSTNAME = <unquoted name>

Specifies the destination hostname to which the files are to be copied. The HOSTNAME attribute must be no more than 17 characters.

LIBMAINTAPPEND = <libmaintappend value>

Indicates whether LIBMAINTAPPEND is used for tape destination files. Valid values are "NO" and "TOEND."

If you specify LIBMAINTAPPEND = NO, or if you omit the LIBMAINTAPPEND option, a new tape is used for copying files.

If you specify LIBMAINTAPPEND = TOEND, library maintenance searches for an existing library maintenance tape with the name and serial number you specify. The tape you specify must be a tape created with the LIBMAINTDIR = TRUE specification. Library maintenance checks the LIBMAINTDIR tape directory disk file for that tape to determine the serial number of the last tape in that set of tapes.

If necessary, library maintenance searches for that tape. Then library maintenance skips to the end of the last file copied to that tape and copies the files that you specified. The copy procedure expands the LIBMAINTDIR tape directory disk file for the tape with the names and status of all files copied to the LIBMAINTAPPEND TAPE.

The following conditions must be met to use LIBMAINTAPPEND = TOEND

  • The destination tape must have been created by a COPY or ARCHIVE statement that specified LIBMAINTDIR = TRUE for that tape.

  • You must specify & VERIFY for the append operation if the & VERIFY option was specified when the tape was originally created.

  • You must not specify & VERIFY for the append operation if the & VERIFY option was not specified when the tape was originally created.

LIBMAINTDIR = <boolean value>

LIBMAINTDIR = TRUE indicates that library maintenance should create a tape directory disk file on the DL LIBMAINTDIR disk family. The LIBMAINTDIR tape directory disk file describes the destination tape and the files copied to it.

The information stored includes

  • Serial numbers of the output tapes used

  • File names of the files copied to those tapes

  • Other attributes

Library maintenance writes tapes created with the LIBMAINTDIR option with ANSI87 labels.

If you overwrite a library maintenance tape for which there is a tape directory disk file resident on the DL LIBMAINTDIR disk family, the system automatically removes that LIBMAINTDIR file.

LOCATECAPABLE = <locatecapable value>

Applies to tape files. Valid values are ON, OFF, and DONTCARE.

Set LOCATECAPABLE attribute to ON to indicate that the file requires a tape drive that is capable of processing the READ POSITION and LOCATE BLOCK ID tape commands for fast tape access.

SAVEFACTOR = <savefactor value>

Specifies the output tape file savefactor. Savefactor values can be up to 3 digits long.

SCRATCHPOOL = <unquoted name>

Specifies the output tape scratch pool. This option applies only to those tapes for which you did not specify the SERIALNO file attribute.

AUTOUNLOAD = <autounload value>

Specifies whether or not the output tape volume should be rewound and unloaded. The value can be either ON, OFF, or DONTCARE.

BLOCKSIZE = <blocksize value>

Specifies in words the blocksize to be used when writing to the output media. The value can be up to 6 digits in length.

ENCRYPT = <encrypt value>

Specifies the encryption algorithm that library maintenance uses when copying to tapes or CDROMs. FILECOPY ignores the ENCRYPT value for DISK or PACK destinations.

Do not specify ENCRYPT if you want library maintenance to use the default SYSOPS LMENCRYPT setting. If you specify ENCRYPT, library maintenance overrides the default value.

Set the NO value to ensure that library maintenance does not encrypt the output. Set the TDES and AES256 values to ensure that library maintenance encrypts the output with the indicated algorithm.

MULTIVOLUME = <boolean value>

Applies to CD only. Specifies whether a multivolume set is to be written when data being copied overflows a single CD-ROM.


Prev  Up  Next
EXPIRED Request  Home  FILECOPY Options