MODIFICATION/SCAN statements

The FATAR Block Modification and Scan control statements (PRINT, DROP, KEEP, REPLACE, and SCAN) invoke optional facilities of FATAR to print data from TAPEIN, to scan TAPEIN data blocks for certain data or types of data, and to modify TAPEIN data blocks before they are written to TAPEOUT. The RENAME statement is also a Modification statement, but is used to rename files as they are copied to the output tape.

There may be as many Modification/Scan statements as required. More than one statement may refer to the same block on TAPEIN; if so, the statements are executed in the order in which they appear in the control statement input. An exception to this is the PRINT Statement, since each data block will be printed only once; the last PRINT Statement that applies to a given data block is the one that will control its printing.

All operands must be specified on the Modification/Scan control statements in the order shown in the statement formats below. However, it is not necessary to indicate the absence of optional operands with a comma. Because many of the operands are common on these statements, the operands are described separately in MODIFICATION/SCAN Operands, except where special notes apply to a particular statement.

These statements can be confusing to use properly. FATAR Examples of Usage contains examples of the use of each kind of Modification/Scan statement. You may wish to review them as you read the following descriptions.

PRINT statement

The PRINT statement requests that data blocks from TAPEIN be printed after other Modification Statements have been applied. By default, the length and format of the printout are controlled by the PRTLEN=, CHAR, HEX, and DUMP operands on the ANALYZE/COPY statement (that themselves default to 80 bytes in character format), but this can be overridden by the L= and CHAR/HEX/DUMP operands on the PRINT statement itself.

The PRINT ALL statement causes all blocks in all files on TAPEIN to be printed, and cannot have any other operands on it. In this case, the length and format are controlled by the above- mentioned ANALYZE/COPY operands.

The ability to use the PRINT statement may be restricted by security rules; see FATAR Security. Examples:

DROP statement

The DROP statement causes one or more blocks or records to be dropped (not copied from TAPEIN to TAPEOUT). If the DCK operand is specified, the drop will be done only if the affected block had a permanent data check when read from TAPEIN. If B=ALL is given, the entire file referenced by LF= will be dropped from TAPEOUT, including all tapemarks and labels (to drop all data from a file without dropping the file itself, specify B=1-2147483647 ).

Dropping individual records (the B=b1.r1 or B=b1.r1-b2.r2 formats), is effective only if the blocks on TAPEIN are being deblocked into records. If all of the records in a block are individually dropped, the entire block will be dropped.

Note: Unless the KEEP operand is specified on the ANALYZE/COPY statement, the default operation of FATAR is to drop (not copy to TAPEOUT) any block that has a permanent data check on TAPEIN. It is not necessary to include a DROP DCK,LF=ALL,B=ALL statement to accomplish this. Including such a DROP statement will cause FATAR to unnecessarily generate a message for every block that it did not drop.

The DROP statement is ignored for image copies (LABELS=IMAGE).

Examples:

KEEP statement

The KEEP statement causes blocks from TAPEIN to be copied to TAPEOUT, even if they would be dropped because of a DROP statement, or because of a permanent data check (the DCK operand is required to keep a data check block). Note that if you want to keep all such data check blocks, use the KEEP operand on the ANALYZE/COPY statement instead of a KEEP statement.

If the optional L= operand is given, the KEEP statement may be used to change the length of a block as it is being copied from TAPEIN to TAPEOUT. L= specifies the new block length and P=, if given, specifies location in the new block (relative to 1) where the old data will be placed. J=R requests that the old data be right-justified in the new block, with the rightmost byte of the old data block positioned at the location specified by P=; if J=R is omitted, the data is left justified, with the leftmost byte placed at the P= location. These combinations allow full control over repositioning of the data. Any extra bytes added at the front or end of the new block will be set to spaces (blanks). Whenever the length of a block is changed, deblocking of that block into logical records will be terminated.

Examples:

REPLACE statement

The REPLACE statement is used to modify data within blocks being copied from TAPEIN to TAPEOUT, and also to scan for blocks or records containing a specified data string (even if TAPEOUT is not present). If TAPEIN data blocks are being deblocked, the REPLACE Statement operates on a logical record basis.

If D= is specified without V= or S=, the data string specified by D= will be placed in every affected data record or block at the location given by P=.

If D= is specified with V=, the data in every affected data record or block will be verified for the current contents specified by V= before the data from D= is placed there (again, the location within the block or record is given by P=). This allows you to be sure the proper data field is being replaced, or to search a set of records for the proper one to modify.

If D= is specified with S=, every affected record or block will be scanned (starting at the location specified by P=, default 1) for the data string specified by S=. If found, the replacement data given by D= will be stored at the location where the S= data was found. Normally, only one such replacement will be done in each record or block, but if the parameter ALL is also given, the scan will continue until the end of the record/block.

If V= or S= is given without D=, verification or scanning will take place as described above, but no data modification will be done. This allows the REPLACE statement to be used to scan data for specific data strings, since any block on which REPLACE successfully operates will be eligible for printing.

Examples:

SCAN statement

The SCAN statement causes specified data fields to be validated for specific type of content. Scans are performed on a logical record basis if records are being deblocked. The field to be scanned is at the location specified by P= (relative to 1) for the length specified by L=. If T=Z is specified, the field is checked for valid zoned decimal characters including decimal sign characters. If T=P is specified, the field is checked for valid packed decimal characters. For any other value of T=, there must be a corresponding TABLE Statement with the same T= value, and the SCAN statement will validate the presence or absence of the characters specified there. A message will be issued for every field that fails the SCAN test and the failing block will be printed.

Examples:

TABLE statement

The TABLE statement is used to define a set of characters for SCAN statement operations. T= must specify a unique letter (except for P and Z, which are reserved) for naming the table, so up to 24 tables can be defined. Each table can contain up to 256 characters, specified by the D= operand. The TABLE statement must precede any SCAN statement that references it. If a field being scanned contains any character not in the table, it will be flagged and its block printed. If the optional operand R is included, this operation is reversed, so that if the field contains any character that is in the table, it is flagged.

Examples:

RENAME statement

When an output tape is being created, RENAME can be used to change the name of the files created on the output tape. The LF= operand specifies to which files on the input tape this RENAME statement applies; it can be for a single file, or for all files on the tape (in the latter case, the NEWI= operand is usually used). No comments are allowed on the RENAME statement.

NEWN= specifies a full replacement data set name, up to 44 characters. If the name ends in a GDG relative generation number, e.g., NEWN=PROD.MAST(+1), a LOCATE is done to get the proper absolute generation number.

NEWI= specifies that the output data set name is to be constructed by adding or replacing one or more index levels in the original name (from the input tape); replacement index levels do not have to be the same length as the original indexes they replace. In the simplest case, FATAR will use each index level specified in NEWI in place of the corresponding index in the original name. Any remaining index levels at the end of the name are copied unchanged. This can easily be used to change the first indexes of the name.

For example, if copying data set A.B.C.D,

If a period is specified without any preceding characters, FATAR will copy one original index level from the input data set name to the output. This allows you to easily modify indexes in the middle of the name.

For example, if copying data set A.B.C.D,

If + is specified before a new index level, FATAR will insert that new index into the output data set name at that point. If ++ precedes the new index, it will be added to the end of the name. If - is specified, the next input index level will be dropped from (not copied to) the output name. For example, if copying data set A.B.C.D,

If the NEWI= value ends in a GDG relative generation number, e.g., NEWI=..NEWMAST(--2), that relative number will be added to the end of the newname, and a LOCATE done to get the proper absolute generation number.

NEWI= is a convenient way to rename every file on a multi-file input tape as it is copied to the output tape, while using some index levels from the original name and replacing other indexes or adding new indexes.

Normally, the NEWI= operand is honored only if FATAR knows the full, accurate data set name of the input file being copied; this is usually true only if the FATS/FATAR tape management interface is enabled (Tape Management System Support). To use NEWI= when the only data set name is the truncated 17-character name from the tape labels, specify the UNCOND operand; NEWI= will be applied to that truncated name except that if the truncated name starts with a period, it is discarded. If used, UNCOND must be the first operand on the RENAME statement.

RENAME is ignored when LABELS=IMAGE has been specified.

The ability to use the RENAME statement may be restricted by security rules; see FATAR Security.