Two modes for I/O data
There are two modes available for the handler to access and provide data. This applies to input and output data, and the search argument for keyed operations. It also applies to the indicator array for files that define the INDARA keyword.
The handler can choose which mode to use when it is processing the OPEN operation by setting the useNamesValues subfield of the handler parameter to '1'.
Name-value information
This mode is available only for externally-described files.
The input and output records
and the search keys are provided as an array of information about
each field. Any *IN indicators associated with
the record are included in the array of field information, whether
or not the file is defined with the INDARA keyword.
The information includes the external short name, the data type, the
length, decimals, date and time format, the CCSID of
the data, whether the field is null-capable, and whether the field
has the null value. The data for each field is provided in a human-readable
form. For example, numeric values are formatted as they would be by
the %CHAR RPG built-in function; for example '-1.23'
.
Most values are in the job CCSID, but UCS-2 and and DBCS values are in the CCSID used in the external file. Alphanumeric fields may also be in the CCSID used in the external file. See alphaCcsids.
- The name-value information is available only for I/O to externally-described record formats and for input operations to externally-described files when there is only one record format in the file.
- When name-value information has been requested by the handler, and the information is not available, either because the file is program-described, or because the operation is an input operation to a file with more than one record format, the request for name-value information will be ignored by RPG. No exception will be given; it is up to the handler to detect this situation. The handler may send an exception, or set the return code to a failing status, or the handler may adjust to the situation and use the record data information provided by the data structures matching the I/O buffers, key structures, and indicator array.
- If the file uses INDARA, the relevant indicators appear as fields in the name-value array.
Data structures matching the I/O buffers
The data related to the I/O operation is passed to the handler in the form of I/O buffer data structures, null-indicator arrays, and INDARA indicator. These data structures and arrays are formatted exactly as they would be passed to data-management functions. No name and type information is passed to the handler. A handler that is specifically written to handle a particular file may use externally described data structures to access the buffers. A more generic handler that can handle many files may have to call an API to determine the information about the fields in the file.
If the file uses INDARA, the handler must work with the indara subfield of the handler parameter to use or set the values of any indicators used by the file.
If the RPG program uses null-indicators for the file, the null-indicator array for the record is in a separate buffer.
Open Access sets the pointers for all the buffers in the handler parameter. The handler is responsible for using or setting the data in the buffers.