CAT Command

The CAT command extends an existing disk file by copying records to the end of that file from one or more input files. You can also use the CAT command to create a new file with records copied from one or more input files.

Syntax

── CAT ────────────────────────────────────────────────────────────────►
  ┌◄────────────────────────────── THEN ─────────────────────────────┐
  │                              ┌◄────────────┬──────┬────────────┐ │ 
  │                              │             └◄─ , ─┘            │ │
►─┴─/10000\─┬─<file title>─────┬─┴─┬─────────────────────────────┬─┴─┴─► 
            ├─ UL <old specs> ─┤   ├─ ( ──<file attributes>── ) ─┤ 
            └─ FR <old specs> ─┘   ├─<record range list>─┬───────┤     
                                   │                     └─<key>─┤
                                   ├─<skip specification>────────┤ 
                                   ├─ SKIPTM ──<integer>─────────┤
                                   ├─ MULTIFILE ─────────────────┤
                                   └─/1\─<key>───────────────────┘
►─┬─ TO ──<file specification>─────┬─┬──────────────────┬──────────────┤
  └─ GIVING ──<file specification>─┘ └─ : ── DONTPRINT ─┘

<file specification> 

                        ┌◄────────────┬──────┬────────────┐
                        │             └◄─ , ─┘            │
──┬─<file title>──────┬─┴─┬─────────────────────────────┬─┴────────────┤
  ├─<long file title>─┤   ├─ ( ──<file attributes>── ) ─┤
  ├─ UL ──────────────┤   ├─ MULTIFILE ─────────────────┤
  └─ FR ──────────────┘   └─ CRUNCH ────────────────────┘

Explanation

CAT <file title>

CAT <long file title>

THEN <file title>

THEN <long file title>

Specify the name of an input file. If the file title does not include an ON <family name> clause and the file attributes you specify do not include KIND or FAMILYNAME, DUMPALL searches for one of the following matching files:

  • For a disk file with a matching file name

  • For a tape file with a matching file name

  • For a card file with a matching file name

Note: If the title is a long file title, you must specify that the kind is DISK by using an ON clause, or by specifying KIND or FAMILYNAME.

You can specify that the file is to be a tape file by using the following construct: 

<file name> ON TAPE

For each subsequent input file that you specify, DUMPALL assumes that the input file has the same file attributes as the preceding input file unless you specify otherwise. For example, assume that you have entered the following command: 

CAT F1/X ON HLPACK THEN Q/FILE GIVING NEWFILE

DUMPALL searches for the file F1/X on the disk family HLPACK. Later, it also searches for the input file Q/FILE on HLPACK. Because you specified no special attributes for the output file, DUMPALL also creates the new output file on the family HLPACK.

GIVING <file title>

GIVING <long file title>

Specifies the name of the new output file that DUMPALL is to create. Unless you use a (<file attributes>) clause for the output file, the attributes of the output file, which include KIND, MAXRECSIZE, FILEKIND, and FAMILYNAME, become the same as those of the first input file.

TO <file title>

TO <long file title>

Specifies the name of an existing output file to which DUMPALL is to add the records read from the input file or files. You can use this form of the command only with output disk files. Moreover, the file cannot be a crunched file or a code file because records cannot be added to the end of a crunched file, and only a compiler can write records into a code file.

UL

UL <old specs>

Specify that an input or output file has a KIND attribute of TAPE and has no label. You can use UL with a labeled tape; UL merely specifies that the tape be treated as unlabeled.

Specify UL only for magnetic tape files. When you use UL, it is not necessary to specify a KIND attribute value of TAPE. UL is ignored for disk and pack files.

The default INTMODE file attribute value is EBCDIC, and the default MAXRECSIZE and BLOCKSIZE attribute values are 1500. You can specify other values for these attributes with the <old specs> variable or with the (<file attributes>) syntax.

Note: The default FRAMESIZE is 48 (that is, words). If you want to specify the MAXRECSIZE and BLOCKSIZE attributes in bytes, you must include FRAMESIZE=8 as a file attribute specification.

When you use UL in an output file specification, the system creates an unlabeled tape as described in “Unlabeled Tapes” later in this section. The operating system demands as many tapes as are required to hold the data being copied to the tape. UL and FR perform the same functions for output files.

When you use UL for an input file whose options do not include SKIPTM or MULTI, DUMPALL can read more than one physical tape. In this case, when DUMPALL reads a tape mark from the tape, it closes that tape volume. DUMPALL then attempts to open the next input tape volume. This action causes the system to generate the following RSVP message: 

NO FILE UL (UNLABELED MT) #nn

You must reply to this message with either the UL (Unlabeled) or the FR (Final Reel) system command.

When you use UL in an input file specification that includes SKIPTM or MULTI, UL is equivalent to FR—that is, DUMPALL uses only one physical tape. In the latter case, when DUMPALL reads a tape mark from the tape, DUMPALL closes the file and does not generate a “NO FILE” RSVP message. If you need to copy a file from a multivolume unlabeled set of tapes, and if you need to use the SKIPTM or MULTI options, use the THEN clause of the CAT command to copy the various parts of the file from the separate tape volumes. For example, suppose the fifth file on the first tape was split into two parts by a volume-switch operation that occurred while the file was being copied to the tapes. Then you could copy the entire file from the tapes by using a command of the following form: 

CAT UL SKIPTM 4 (<file attributes>)
THEN UL (<file attributes>) TO <file title>

<old specs>

Use old specs with unlabeled or nonstandard labeled tape files to assign values to the attributes INTMODE, MAXRECSIZE, and BLOCKSIZE. Refer to “Old Specs” later in this section for more information about <old specs>.

FR

FR <old specs>

For input files, specify an unlabeled tape file that has only one reel. As in the case of UL, the tape used need not be an unlabeled tape.

Specify FR only for magnetic tape files. When you use FR, it is not necessary to specify a KIND attribute value of TAPE. DUMPALL ignores FR for disk and pack files.

The default INTMODE file attribute value is EBCDIC, and the default MAXRECSIZE and BLOCKSIZE attribute values are 1500. You can specify other values for these attributes with old specs or with the (<file attributes>) syntax.

Note: The default FRAMESIZE is 48 (that is, words). If you want to specify the MAXRECSIZE and BLOCKSIZE attributes in bytes, you must include FRAMESIZE=8 as a file attribute specification.

When used for an output file specification, FR specifies that the output tape is to be unlabeled and formatted as described under “Unlabeled Tapes” later in this section. The operating system uses as many tapes as are required to hold the data to be copied.

The use of FR instead of UL is important for input files only. That is, when you use FR in an input file specification, it indicates that only one physical tape is to be used. When DUMPALL reads a tape mark from the tape, it closes the file and does not generate a “NO FILE” RSVP message. Refer to “Input Files from Unlabeled Tapes” later in this section.

(<file attributes>)

Specifies how the file is to be written or read. Except for the file attributes you specify, DUMPALL obtains the file attribute information for each input file from the disk file header or the tape label. Except for the file attributes you specify and the FILESTRUCTURE, SERIALNO and HOSTNAME attributes, DUMPALL obtains the file attribute information for each output file from the first input file copied to that output file.

DUMPALL determines the value of the KIND attribute for input files and output files by one of the following processes:

  • If you specified either UL or FR, then KIND is TAPE.

  • If you specified a file title with an explicit ON family name clause, then KIND is TAPE or DISK depending on whether or not you specified the family name ON TAPE.

  • If you explicitly specify a value for KIND in the (<file attributes>) syntax, then DUMPALL uses that value.

  • Otherwise DUMPALL determines the value for KIND automatically as follows:

    • For the first input file in the command, DUMPALL searches for the file on disk and tape.

    • For all subsequent input files in the command for which you have not explicitly or implicitly specified a value for KIND, DUMPALL uses the KIND value from the preceding input file.

    • For the output file in the command, DUMPALL uses the KIND value from the first input file in the command.

If you do not specify a value for SAVEFACTOR for the output file, DUMPALL assigns the output file the same SAVEFACTOR value as the first input file. If that value is 0, DUMPALL uses 999 instead.

Note: A tape file with a SAVEFACTOR of zero expires the day it is created. The system treats tapes containing expired tape files as scratch tapes unless you remove the write ring from the reel or switch the write-protection knob on the tape cartridge.

If you specify the HOSTNAME file attribute, DUMPALL accesses the file on a remote host system. In this case, distributed system services (DSS) requires that you also explicitly specify the KIND file attribute.

The file attribute equation specifies how the file is to be written or read. If no file attributes are specified for the input file, DUMPALL opens the input file with the following logic:

  • Labeled tape files are opened with DEPENDENTSPECS set to TRUE, INTMODE set to EBCDIC, and EXTMODE set to the physical mode of the file.

  • Disk files are opened with DEPENDENTSPECS set to TRUE and with INTMODE and EXTMODE set to the physical mode of the input file.

The logical input file resembles the physical input file for disk files, and resembles the physical file for tape files if the tape file has a physical mode of EBCDIC.

The record and block structures of the output file are the same as those of the first input file if you do not specify any file attributes for either the input file or the output file, and if the input file is either a tape file with a physical mode of EBCDIC or a disk file. In this case, no data translations occur, so DUMPALL does not alter the records it copies from the input file or files to the output file.

Specifying input file attributes such as DEPENDENTSPECS, EXTMODE, and INTMODE might cause data translation and the alteration of other file attributes (for example, MAXRECSIZE). Specification of such attributes might also avoid data translation if the input file is a not an EBCDIC tape file. If data translation does occur, the output file might not directly resemble the input file.

Refer to “Understanding Structural File Attributes” earlier in this section for an explanation of the file structure, record size, block size, the DEPENDENTSPECS attribute, and their effects on DUMPALL.

Refer to “Specifying Data or Character Set Translations” earlier in this section for an explanation of the effects of the EXTMODE and INTMODE file attributes on DUMPALL.

<record range list>

Specifies a group of records to be processed. Refer to “Record Range List” later in this section for more information about <record range list>.

<skip specification>

Causes only the specified records of the file to be copied. If you do not specify a record range list or skip specification, DUMPALL copies the entire file. If you use the <key> option with the record range list, DUMPALL copies all records with the matching arguments. Refer to “Skip Specification” later in this section for more information about <skip specification>.

<key>

A key option allows you to select records based in part on the data in the records. Refer to “Key Option” later in this section for an explanation of <key>.

SKIPTM <integer>

Causes DUMPALL to skip past the number of tape marks specified and to bypass any records encountered between tape marks. Use SKIPTM to position an input tape at the first record of a file to be read. You can use SKIPTM only with an input file that you specify as UL or FR. SKIPTM 0 is equivalent to omitting the SKIPTM option.

Refer to “Description of Tape Formats” later in this section for an explanation of where tape marks appear on a tape.

MULTIFILE

MULTI

Specify that an input file is part of a multifile, labeled or unlabeled tape. The effect of its use is that the tape is not rewound, but is positioned so that a subsequent file on the same volume can be read from. In other words, MULTIFILE copies one or more subsequent files from the same tape. DUMPALL ignores the MULTIFILE specification if the file is not a tape file. Use MULTIFILE only if you are using a single command to read multiple files.

You must use MULTIFILE to copy a file from a multifile tape if the following conditions are met:

  • The tape is a standard labeled tape.

  • The file is not the first file on the tape.

  • The file has a nonstandard name. Normally, a tape file has a two-level name of the following form: volumeid/fileid. A nonstandard tape file name is a name with only one level, such as F1 or MYFILE.

In such a case, when DUMPALL tries to open the file, the system produces a “NO FILE <filename> (MT)” RSVP message. You must reply with the IL (Ignore Label) system command to select the tape unit on which the tape with the requested file is mounted.

Normally, when DUMPALL finishes copying a file to a tape, it closes the tape with the LOCK option. So, depending on the kind of tape unit involved, the system either unloads the tape volume or marks the unit as unloaded. However, if you specify MULTIFILE on the output file that you want copied to tape, DUMPALL does not close the tape with the LOCK option, and the tape simply rewinds. When the rewinding finishes, the system leaves the tape online and ready for use in subsequent DUMPALL commands or subsequent programs.

AUTOUNLOAD <autounload value>

Use of the AUTOUNLOAD file attribute can affect the disposition of the tape file.

AUTOUNLOAD determines whether a tape is unloaded when it is released by the system during a reel switch or a file close operation. If the value is ON, the tape is rewound and unloaded. If the value is OFF, the tape is not unloaded. If the value is DONTCARE or if this value is not specified, the load status of the tape unit depends on the AUTOUNLOAD option for that unit. Refer to “MODE (Unit Mode)” in Section 6 of the System Commands Operations Reference Manual for more information.

CRUNCH

When the output disk or pack file is closed, DUMPALL returns the unused portion of the last row of disk space to the system. DUMPALL ignores the CRUNCH option if the file is not a disk or pack file.

DONTPRINT

Suppresses the printed report of the file attributes of the input files and the output file.

Example 1

Example 1 concatenates file A to existing file B:

CAT A TO B;

Example 2

Example 2 concatenates the files A, B and C to existing file D: 

CAT A THEN B THEN C TO D;

Example 3

Example 3 concatenates the files A and B to create a new file named C. If a file named C already exists, DUMPALL replaces the existing file. The new file named C has the same file attribute values as file A. 

CAT A THEN B GIVING C;

Example 4

Example 4 concatenates the files A, B, and C to an existing file D. DUMPALL suppresses printed output. 

CAT A THEN B THEN C TO D: DONTPRINT;

Considerations for Use

If you use the CAT command to copy an input code file, the resulting output file has a FILEKIND equal to DATA.

Note: A CAT command with a GIVING clause executes just like a COPY command.

You cannot use DUMPALL to copy files with a FILEORGANIZATION attribute value equal to KEYEDIOII or KEYEDIOIISET. To copy KEYEDIOII and KEYEDIOIISET files, use the KEYEDIOII Copy Utility as described in the KEYEDIOII Programming Reference Manual.

You can use DUMPALL to copy an input file with a FILEORGANIZATION value equal to INDEXED or INDEXEDNOTRESTRICTED. DUMPALL does not copy any records that have been marked as deleted from these files. You can copy these files to output files that are NOTRESTRICTED, INDEXED, or INDEXEDNOTRESTRICTED with the following stipulations:

  • You can add records copied from these files to existing disk files that have a FILEORGANIZATION value equal to NOTRESTRICTED.

  • You can copy these input files to create a new output file with a FILEORGANIZATION value of INDEXED or INDEXEDNOTRESTRICTED if the system option KEYEDIOII is reset to FALSE.

  • You can copy these input files to create a new output file that is not an INDEXED file by specifying that the output file has a FILEORGANIZATION value of NOTRESTRICTED.

An attempt to add records to an existing INDEXED or KEYEDIOII file by means of the CAT command results in the following error message: 

CANNOT CAT TO A FILE THAT DOES NOT HAVE A FILEORGANIZATION =
NOTRESTRICTED.

If the KEYEDIOSUPPORT library is not defined as a support library by means of the SL (Support Library) system command, DUMPALL terminates with the following message when DUMPALL accesses an INDEXED file: 

FILE <filename> OPEN ERROR: SUPPORT LIBRARY UNAVAILABLE.

The rules regarding input and output file specifications for labeled and unlabeled tapes are the same as those for the COPY command with one exception. The variation of the CAT command TO <destination file> that causes the input file to be appended to an existing file is not allowed when the output file is a tape file.

Prev  Up  Next
ATTRIBUTES or FILE Command  Home  COPY Command