Handling input data

Using the recordName subfield

If the file is externally described, the RPG program must know which record format is associated with the input data.

• If the recordName subfield is not blank, the RPG program explicitly specified the required record format, or there is only one record format for the file. In this case, the handler must provide input data for the specified record format.
• If the recordName subfield is blank, the RPG program did not specify a specific record format. In this case, the handler must set the recordName subfield to indicate which record format is associated with the input data.

Using the rrn subfield

If relative record numbers are relevant for the file or record format, the handler may provide this value in the rrn subfield. The RPG programmer can obtain this value using the RECNO keyword on the File specification.

Handling input data using data structures

• Use the inputBuffer pointer subfield to locate the input buffer for the file and use the inputBufferLen subfield to determine the number of bytes provided for the input buffer.
• For an externally-described file, use the inputNullMap pointer subfield to access the input null map for the file and use the inputNullMapLen subfield to determine the number of bytes provided for the input null map. The input null map is an array of indicators with one element for each field in the record. For a field which is null-capable, a value of '1' indicates that the field has the null value, and a value of '0' indicates that the field does not have the null value. For a field which is not null-capable, the value should always be '0'. If the inputNullMap pointer is null, the input null map is not relevant for the file within the RPG program.
• For an externally-described file, set the value of each field in the input buffer according to the data type of the field, and if null-values are relevant for the file, set the indicator in the input null map for each null-capable field.
• For a program-described file, set the input buffer according to the definition of the record that is agreed upon by the RPG programmer and the handler provider.

Handling input data using name-value information

• Use the namesValues pointer subfield to access the array of information about each field in the record format.
• For each input field, or each input or output field in the case of a subfile record format
  • Use the value pointer subfield to locate the buffer available for the field.
  • Use the valueMaxLenBytes subfield to determine the maximum length available for the data.
  • Set the value of the field in the buffer, according to the data type of the field. See Data types used in name-value information for more information.
  • Set the valueLenBytes subfield to indicate the number of bytes that were set by the handler in the buffer.
  • If the isNullCapable subfield indicates that the field is null-capable, set the hasNullValue to '1' if the field has the null value, and to '0' otherwise.
    Remember: The data for a field must be set to a valid value even if the hasNullValue subfield is set to '1'.