Select records based on character content (INCCHAR parameter)

You can select records on the basis of the content of characters that start in a specific position in the record or field.

Note: You can use this parameter on the CPYF command only.

You can use the INCCHAR parameter with the FROMKEY or FROMRCD parameter. You can select records first by their key value or relative record number, and then by characters in some position in the record or field.

You can test for any character string of 1 through 256 bytes. If the character string contains any special characters or blanks, you must enclose the entire string in apostrophes.

You can also specify *CT (contains) as the operator for the INCCHAR parameter. This specifies that the copy command should scan each record in the from-file for the selection character string. You can specify any valid starting position in the field or record for the start of the scan. The data will then be scanned from that position to the byte to the extreme right of the field or record.

If you specify both the INCCHAR and INCREL parameters, the copy command copies a record only if it satisfies both the INCCHAR and INCREL conditions.

This example shows how you can test for all records in the file DBIN that have an XXX starting in position 80. It then shows how you can copy these records to the file DKTOUT. Because this example includes testing for positions relative to the length of the whole record, you must specify *RCD on the INCCHAR parameter.

CPYF FROMFILE(DBIN) TOFILE(DKTOUT) +
  INCCHAR(*RCD 80 *EQ XXX)

If you were testing for an XXX in a position in a particular field in the record, you would specify the field name instead of *RCD, and the starting position of the character relative to the start of the field.

CPYF FROMFILE(DBIN) TOFILE(DKTOUT) +
  INCCHAR(FLDA 6 *EQ XXX)

A field name cannot be specified if RCDFMT(*ALL) is specified when copying from a multiple-format logical file, or if the from-file is a device file or inline data file.

For binary character fields, the INCCHAR parameter will use the binary character comparison rules. Comparisons will be performed by CPYF and no padding or truncation will be performed.

Variable-length fields used by the INCCHAR parameter
When you specify *RCD for the INCCHAR parameter, the starting position represents the position in the buffer. The 2-byte length field of variable-length fields must be considered when determining the position.
Null-capable fields used by the INCCHAR parameter
The INCCHAR parameter allows null-capable character-field and null-capable DBCS-field names to be specified. However, any logical comparison with a null-field value tests as false, and the record is not copied.
Different CCSIDs used by the INCCHAR parameter
When you specify *RCD for the INCCHAR parameter, the copy command does not perform any conversions on the input string. The command compares the byte string that you entered at the specified position in the record buffer of the from-file.
DBCS-graphic fields used by the INCCHAR parameter
When you specify a graphic field for the INCCHAR parameter, you should enclose the DBCS data in shift-out and shift-in characters. The command assumes that the data is in the associated DBCS CCSID of the job CCSID.

Parent topic: Select the records to copy