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.

When the value for a field is set by the handler, the handler must set the value in the same human-readable form that Open Access uses to provide the values for output-capable fields.
Remember:
  1. 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.
  2. 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.
  3. 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.