Control cards

Control cards are the main communication tool in File-AID/Batch. Control cards let you identify the functions to perform on the input data, the method to use for record selection, and the specific changes to make to the data.

File-AID control cards can use four types of elements:

• Dataset identifier
• Function/Dataset organization identifier
• Parameter identifiers
• Comments.

The first two elements are required; the last two are optional. The following figure shows the format of a control card.

Control Card Elements

Dataset identifier

The first element on a File-AID control card is the dataset identifier. This identifier connects an input data set to a function that you want to perform. The dataset identifier begins with $$DD in location 1 of the control card as follows:

$$DDxx

where xx is a number from 00 to 99 that corresponds to a matching //DDxx DD JCL statement. The xx is also used to match other optional //DDxx DD JCL statements. For example: //DD01O (output data set), //DD01RL (layout library), //DD01RF (reformat definition library).

Function/dataset organization identifier

Define the function you want to perform on the input data set with the function/dataset organization identifier. As an option, use this identifier to choose the access method that File-AID uses to process the input data set.

File-AID/Batch functions are defined in Function and Modifier Descriptions. The format used to code each function is detailed in Functions and Modifiers.

You can attach a dataset organization identifier (DSORG ID) to any function identifier; it defines the access method used to process the input data set. For example, the “DA” DSORG ID can force File-AID to process a QSAM data set as a BDAM data set. Any logical errors created in this way produce unpredictable results in the output data set. Valid DSORG IDs are listed in the following table.

(Sheet of ) Dataset Organization Identifiers

The function/DSORG identifier must begin before location 16. Leave at least one blank position between the function/DSORG identifier and the preceding dataset identifier. Character, Packed Decimal, and Hexadecimal Data Operator Elements shows a function/DSORG identifier in a control statement.

Function/Dataset Organization Identifier

The format of the function/DSORG identifier shown in the figure is:

This example copies the input data set as if it is a BDAM file, regardless of the original access method used when the data set was created.

Parameter identifier

Parameters define how to select and manipulate records. They are discussed in Parameter Descriptions. Parameter identifiers define parameters and consist of a parameter name and one or more elements. Elements define input data, output data, and data handling components of a parameter. The four most common elements used in parameter identifiers are:

• Location
• Length
• Operator
• Data.

Format rules for these four elements are listed below. The format used to code each parameter is explained in Parameters. The following figure shows the format of a typical control card using parameters.

Parameter Identifiers

Location Element

The location element defines where the desired data can be found in the record. You can specify an actual location or a relative location.

Actual Location

The actual location can be any number from 1 to 32,760 (32 KB), but it cannot exceed the record size. You can use the Record Descriptor Word (RDW) in locations 1 through 4 as the actual location in variable-length records. If you use the RDW as an actual location, the first valid data position is location 5. If you set the RDW parameter to 2 or 3, the data begins in position 1. (See RDW)

Relative Location

Distinguish a relative location from an actual location by placing a plus sign (+) or a minus sign (-) before the value. For example, to reference the next relative location in a record, use +1 for the location element. To reference three bytes before the current location, use -3 for the location element.

File-AID has two types of relative locations: one references the input record; the other references the output record.

Input Record

When File-AID retrieves an input record, the input relative location is set to 1. For variable records, the relative location for the first position of data can be 1 or 5 and is determined by the RDW parameter. See the explanation for RDW parameter usage on here. This relative location is incremented by the IF, EDIT, and REPL scanning parameters only. Non-scanning parameters (Operator is used instead of Length) do not affect the relative location. Subsequent relative location references are relative (+ or -) to this value.

When an input relative location exceeds the current record boundary, File-AID skips the record and reports it on the statistics line. The statistics line is directed to SYSPRINT after each function executes.

Output Record

The output relative location is used only with the MOVE parameter while creating records with the COPY or USER functions. When data is moved to an output location, the output relative location advances to the next available output location. This allows File-AID to calculate the record length of variable-length output records. If you are merging data from several input records into one output record, a move to the highest location must be executed during the final iteration for each output record, otherwise data will be truncated.

The output relative location is set to the first data position of the output record after each input record is read.

Operator Element

The operator element sets conditional tests on data in the location identified by the location element. Use operator elements with the EDIT, IF, ORIF, REPL, and STOP parameters.

File-AID has two sets of operator elements. One set is for character, packed decimal, or hexadecimal data; the other set is for binary data.

Operator elements for character, packed decimal, and hexadecimal data represent conditions that can occur after a compare instruction is applied to the input data using the data element specified. These operator elements are listed in the following figure.

Character, Packed Decimal, and Hexadecimal Data Operator Elements

For fields with relational operators other than BT and NB, specify the field value to use in the comparison in alphanumeric format and File-AID/MVS converts it to the correct data type format (as in File-AID/MVS Edit formatted mode). For relational operators BT and NB, specify your Data Value as two values separated by a colon (:). The values may be hex strings, character strings, or numeric tests.

Binary operator elements represent conditions that can occur after a test-under-mask instruction is applied to the input byte using the binary data mask element specified. The binary operator elements are listed in the following table.

Binary Data Operator Elements

Length Element

The length element sets the length of the field that File-AID must examine. The length element is used instead of the operator element when the specific location of the compare data is not known. Using a length element changes the comparison parameters like IF, EDIT, and REPL to scanning parameters. The value of the length element may be any number from 0 (zero) through 255 (excluding one), but the length added to the current location cannot exceed the record size.

If you use a 0 (zero) for the length element, File-AID calculates the length of the search field that begins at the specified location and ends at the end of the record.

Data Element

The data element lets you specify data to File-AID in three ways:

• As compare data in an IF, ORIF, IFNOT, ORIFNOT, EDIT, or REPL parameter
• As the data to be moved in a MOVE parameter
• As replace data in a REPL or EDIT parameter.

The following table identifies the data types that you can specify with the data element. When you code a data element, make sure the actual data follows one of the data identifiers and is enclosed by single quotes (apostrophes) or double quotes. The following table provides examples of each data type.

Data Element Types

Japanese Data

DBCS and single byte Katakana data is accepted as data element values. File-AID removes leading or trailing shift characters from DBCS data unless the value is enclosed in double quotes.

When the KANA install option is specified for the Character Set Table in the Batch Product Option Variables, C (Character) and T (Text) identifiers are both treated as case-sensitive C (Character) data.

Character Data

Character data can be any length in the control card, but cannot extend past location 80. Character data is case-sensitive. Enclose all character data in either single quotes (apostrophes) or double quotes. Use single quotes to delimit multiple values separated by commas. Unless commas are enclosed in double quotes, commas indicate an OR condition for selecting records based on matching a list of two or more data values.

This example shows a character data element that tests for the number 10 or11:

Use double quotes to include special characters such as commas and quotes. This example shows a character data string that contains 10,’11’,12:

Character Data Length Parameter

Use the character data length parameter to specify the length of a search string or a replace string in a record. The data length for CL can be any number from 1 through 255. If you use 0 (zero), File-AID disregards the length (e.g. CL0’ABC’ is same as C’ABC’).

 Example 1:

CL10’ABC’ turns into C’ABC ’

 Example 2:

CL3’ABCDEFGHIJKLMNOPQR’ turns into C’ABC’

 Example 3:

CL5’ABC,DE,F,’ turns into C’ABC ,DE ,F ’

 Example 4:

IF=(1,EQ,CL10’ABC’),REPL=(100,CL40’XYZ’)

 Example 5:

CL20”ABC,DEFG,H” turns into C"ABC,DEFG,H "

 Example 6:

CL’ABC’ or CL256’ABC’ are invalid

CL0’ABC’ is acceptable, but it is same as C’ABC’

Text Data

Text data can be any length in the control card, but cannot extend past location 80. Text data is non-case-sensitive. Enclose all text data in either single quotes (apostrophes) or double quotes. Use single quotes to delimit multiple values separated by commas. Unless commas are enclosed in double quotes, commas indicate an OR condition for selecting records based on matching a list of two or more data values.

This example shows a text data element that tests for any combination of upper and lowercase characters ABCD:

Use double quotes to include special characters such as commas and quotes.

Text Data Length Parameter

Use the text data length parameter to specify the length of a search string or a replace string in a record. The data length for TL can be any number from 1 through 255. If you use 0 (zero), File-AID disregards the length (e.g. TL0’ABC’ is same as T’ABC’).

The Usage Notes listed for Character Data Length Parameter also apply to the text data length parameter, just substitute TL and TC for CL and C.

Hexadecimal Data

Hexadecimal data can be any length that is a multiple of two, but cannot extend past location 80.

This example shows a hexadecimal value of 10000F:

Packed Data

Packed data can be up to 31 digits or a packed length of 16 bytes. Sign packed data by inserting a positive or negative sign directly after the first quote. Leading zeros are not required when testing for packed values.

File-AID/Batch determines the length of the packed field by scanning from the location you specify until it finds a valid sign (F, C, or D). All hexadecimal digits that begin at the location you specify and ending at the valid sign must be between zero and nine.

Examples of F (unsigned), C (positive), and D (negative) signed packed data are:

Packed data fields signed as F or C are considered equal.

Packed Data Length Parameter

Use the packed data length parameter to specify the length of a search string in a record. The data length for PL must be in the range of 1 through 16 (bytes). If you use 0 (zero), File-AID disregards the length (e.g. PL0’123’ is treated as P’123’).

Without Length parameter (for example, IF=(1,EQ,P’+123’), the record containing a packed field of any length starting in location 1 with a numeric value of +123 will be selected. X'123C', X'00123C', etc. through X'0000000000000000000000000000123C' are all matches for this test. With Length parameter (for example, IF=(1,EQ,PL5’+123’), only the data having X’000000123C’ at location 1 will be hit.

 Example 1:

1,EQ,PL2’+123456’ turns into X’0123456C’ turns into last 2 bytes: X’456C’ = 1,EQ,PL2’+456’

 Example 2:

PL5’+1,-2’ turns into search X’000000001C’ or X’000000002D’

Example 3:

PL’123’ or PL17’-123’ or PL005’+123’ are invalid

PL0’123’ is acceptable, but it is same as P’123’

Binary Data

Binary data checks or sets the ON or OFF condition of bit settings. A binary data element always describes one byte of data. You can represent it one of two ways:

• Hexadecimal characters. For example: B’C8’
• Eight-bit true binary value of all zeros or ones. For example: B’11001000’

Binary data elements are used to check the condition of bit settings by using one of the valid binary data operator elements as described in Binary Data Operator Elements. Binary data elements are applied with a test-under-mask instruction to the byte you reference. Truth of the condition is based on the binary data operator element specified.

The binary data element may also be used as new data in a REPL parameter. When a binary data element is used with the REPL parameter, individual target bits can be set ON or OFF by using one of the valid data element types as shown in Data Element Types.

Integer Data

Binary equivalent of decimal number specified in quotes. In this example (I’+147,-25,+1117’) using the default of fullword, File-AID searches for X’00000093’, X’FFFFFFE7’, or X’0000045D’. File-AID assumes the length of 4 or you can specify 1, 2, 4, or 8.

Integer Data Length Parameter

Use the integer data length parameter to specify the length of a search string in a record. The data length for IL must be 1, 2, 4 or 8. The specified data is examined if it fits in the length field specified.

Example 1:

IL4’+147,-25,+1117’ searches for X’00000093’ or X’FFFFFFE7’ or X’0000045D’

Example 2:

IL3’+1’ or IL004’-123’ or IL’+1’ are invalid

Example 3:

IL2’65536’ is invalid, the value is larger than the field can contain.

Duplication Factor

Use a duplication factor to avoid coding repetitive data elements. Code it as any number from 2 through 255 and place it directly before the data element. If you do not code a value, the default is 1. The value corresponds to the number of times File-AID finds the data contiguously repeated, beginning at the location you specify in the location element.

Two examples of duplication factors are:

Scanning Parameters

Use scanning parameters to search for a sequence of characters within a range of locations in a record. The scan length can be any number from 0 (zero) through 255 (excluding 1) as long as it is greater than the length of the data element. If you use 0 (zero), File-AID calculates a scan length from your specified location to the end of the record. Scanning repositions the input relative location pointer when the data value is found.

Example 1:

Example 1 generates a hexadecimal print of any record that contains the character string CLIPS in the scan field between locations 22 and 31.

Example 2:

Example 2 copies the input data set while locating any record that contains the character string TEST in the scan field between locations 6 and 55. When File-AID locates the string TEST, it replaces it with the string PROD.

Comments

Comments are used on control cards as a form of documentation. Comments appear on the SYSPRINT output when all other control cards are printed.

Code comments by leaving at least one blank position after the final parameter on a control card. If you do not specify parameters, the comment cannot begin before location 27. You can code a comment by itself on a control card by placing an asterisk (*) in location 1. Comments with an asterisk (*) in location 1 are also written to the optional SYSTOTAL DD if one is provided in the JCL. An example of coding comments is: