| Note: | You can use this parameter on the CPYF command only. |
You can select records on the basis of the content of characters that start in a specific position in the record or field. 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.
See the following topics for additional information about specifying data for:
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. Use single-byte blanks (X'40') to pad variable-length fields if the INCCHAR value spans multiple fields.
You can specify variable-length fields for the INCCHAR string when you specify a field name. The starting position represents the position in the data portion of the variable-length from-field value. The number of bytes that are compared is the number of bytes in the value that is specified for the INCCHAR string. If the actual data in the variable-length from-field is shorter than the value specified for the INCCHAR parameter, the from-field data is padded with single-byte blanks (X'40') for the comparison.
You cannot specify a zero-length string for the INCCHAR value.
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. The copy command performs no special processing if the you specify the *RCD special value as the field name. The command only compares buffer default values for actual null values.
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.
When you specify a field name, the command assumes that the input string is in the CCSID of the job in which the copy command runs. The input string is converted to the CCSID of the from-field. If no conversion table is defined or if an error occurs while converting the input string, a message is sent and the copy operation ends. If the command can correctly convert the value, the command uses the converted value for record selection.
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. There must be a valid conversion to the field CCSID; otherwise, an error occurs. The shift-out and shift-in characters are removed before doing the comparison. The position specifies the DBCS character position in which to begin the comparison.