The subfields of the main parameter structure
The subfields of the main parameter structure
The name of the main parameter structure is QrnOpenAccess_T.
| Subfield | Type | Set by | Used by |
|---|---|---|---|
| structLen | UINT4 | RPG | Handler |
| parameterFormat | CHAR(8) | RPG | Handler |
| userArea | Pointer 1 | RPG | Handler and RPG programmer |
| stateInfo | Pointer 3 | Handler | Handler |
| recordLevels 4 | Pointer 1 | RPG | Handler |
| inputBuffer | Pointer 1, 2 | Handler | RPG |
| inputNullMap 4 | Pointer 1, 2 | Handler | RPG |
| outputBuffer | Pointer 1, 2 | Handler | RPG |
| outputNullMap 4 | Pointer 1, 2 | Handler | RPG |
| namesValues 4 | Pointer 1, 2 | RPG and Handler | RPG and Handler |
| key | Pointer 1, 2 | Handler | RPG |
| keyNullMap 4 | Pointer 1, 2 | Handler | RPG |
| keyNamesValues 4 | Pointer 1, 2 | Handler | RPG |
| indara | Pointer 1, 2 | Handler | RPG |
| prtctl | Pointer 1, 2 | Handler | RPG |
| openFeedback | Pointer 3 | Handler | RPG |
| ioFeedback | Pointer 3 | Handler | RPG |
| deviceFeedback | Pointer 3 | Handler | RPG |
| externalFile | System object structure, QrnObject_T | RPG | Handler |
| externalMember | CHAR(10) | RPG | Handler |
| compileFile 4 | System object structure, QrnObject_T | RPG | Handler |
| recordName | CHAR(10) | RPG and Handler | RPG and Handler |
| rpgOperation | UINT4 | RPG | Handler |
| rpgStatus | INT4 | Handler | RPG |
| inputBufferLen | UINT4 | RPG | Handler |
| inputNullMapLen 4 | UINT4 | RPG | Handler |
| outputBufferLen | UINT4 | RPG | Handler |
| outputNullMapLen 4 | UINT4 | RPG | Handler |
| keyLen | UINT4 | RPG | Handler |
| keyNullMapLen 4 | UINT4 | RPG | Handler |
| inputDataLen | UINT4 | Handler | RPG |
| openFeedbackLen | UINT4 | Handler | RPG |
| ioFeedbackLen | UINT4 | Handler | RPG |
| deviceFeedbackLen | UINT4 | Handler | RPG |
| numKeys 4 | UINT4 | RPG | Handler |
| rrn | UINT4 | RPG and Handler | RPG and Handler |
| formLen | UINT4 | RPG | Handler |
| formOfl | UINT4 | RPG | Handler |
| sln | UINT4 | RPG | Handler |
| alphaCcsids | UINT4 | RPG | Handler |
| functionKey | UINT1 | Handler | RPG |
| externallyDescribed | Indicator | RPG | Handler |
| keyedFile | Indicator | RPG | Handler |
| blocked | Indicator | RPG | Handler |
| eof | Indicator | Handler | RPG |
| found | Indicator | Handler | RPG |
| equal | Indicator | Handler | RPG |
| printerOverflow | Indicator | Handler | RPG |
| inputWithLock | Indicator | RPG | Handler |
| useNamesValues 4 | Indicator | Handler | RPG |
| isSubfile 4 | Indicator | RPG | Handler |
| canHandleCcsids 4 | Indicator | Handler | RPG |
| commit | Indicator | RPG | Handler |
| rpgDevice | CHAR(1) | RPG | Handler |
Additional notes on the table
- The "Set by" and "Used by" columns refer to the data that the pointer is pointing to.
- The pointer is set by RPG. The handler sets the data pointed to by the pointer, usually with a variable or data structure based on the pointer.
- The pointer is set by the handler.
- This subfield is meaningful only for externally-described files.
Descriptions of the subfields
- alphaCcsids
- Whether alphanumeric fields have the job CCSID or the
CCSID of the fields in the externally-described file.
See Constants QrnCcsids_*.
Note: If this subfield has the value QrnCcsids_FILE indicating that alphanumeric fields have the CCSID of the fields in the file, the handler must set the canHandleCcsids subfield to '1'.
- blocked
- '1' if the file is defined to be blocked in the RPG program. '0'
otherwise. Note: This value is provided for information only. The Open-Access interface does not work with blocks of record, but the handler may use this information to control whether it block the records from the device or resource that it is dealing with.
- canHandleCcsids
- Set to '1' by the handler during the OPEN operation if the handler is able to handle alphanumeric fields with CCSIDs other than the job CCSID.
- commit
- '1' if the file should be opened under commitment control. '0' otherwise.
- compileFile
- The library and file that the RPG compiler used at compile-time
for the description of an externally-described file. Note: If an override was in effect for the file at compile-time, this reflects the actual file used at compile-time. For example, if the RPG file specification or EXTDESC keyword specifies file MYFILE, and there is an override for MYFILE to MYLIB/OTHERFILE, then the compileFile subfield will reflect library MYLIB and file OTHERFILE.
- deviceFeedback
- A pointer to the information that the handler provides to RPG
to set the device-specific feedback part of the file's File Information
Data Structure (INFDS). If this information is
not supplied by the handler, the device-specific-feedback part of
the INFDS is not updated by RPG. The length is
specified by deviceFeedbackLen.
See Setting the feedback areas in the INFDS for more information.
- deviceFeedbackLen
- The length of the device-specific-feedback information provided by the handler.
- eof
- Set to '1' by the handler if the file reached end of file for a sequential input operation or a WRITE operation to a subfile record. The handler can leave it at '0' otherwise to indicate that the record was successfully read or written.
- equal
- Set to '1' by the handler if an exact match was found by a SETLL operation. The handler can leave it at '0' otherwise.
- externalFile
- The library and file that the RPG program is opening at run time.
It is the value specified by the EXTFILE keyword
for the file. If the EXTFILE keyword was not specified,
the library is *LIBL and the file is the internal name of the file
in the RPG program.. Note: If an override is in effect for the file at run-time, this does not reflect the overridden file. For example, if the file specified by the EXTFILE keyword is MYLIB/MYFILE and there is an override present at run time that overrides file MYFILE to OTHERLIB/OTHERFILE, externalFile subfield will reflect the RPG value MYLIB/MYFILE. If the handler is interested in overrides, the handler may use an API to determine whether there is an override for the file.
- externalMember
- The member that the RPG program is opening at run time. It is the
value specified by the EXTMBR keyword for the file.
If the EXTMBR keyword was not specified, it is *FIRST. Note: If an override is in effect for the file at run-time, this does not reflect the overridden member.
- externallyDescribed
- '1' if the file is externally-described in the RPG program. '0' otherwise.
- formLen
- Printer form length. Only meaningful for a program-described PRINTER file.
- formOfl
- Printer form overflow. Only meaningful for a program-described PRINTER file.
- found
- Set to '1' by the handler if a record was found by a positioning operation (CHAIN, SETLL, SETGT). The handler can leave it at '0' if a record was not found.
- functionKey
- For a user-interface input-capable operation, a function key value of 1-24 causes an *INKx indicator to be set on in the RPG program. A value of 121-126 indicates one of the PRINT, ROLLUP, ROLLDOWN, CLEAR, HELP or HOME keys, and causes the RPG status to be set to 1121 - 1126. Any other value causes an I/O error with status 1299. See Constants QrnFunctionKey_* defining the values for the functionKey subfield.
- indara
- A pointer to the INDARA array of 99 indicators used for the WORKSTN or PRINTER I/O operation. NULL if the file is not defined to use INDARA or if the handler is using name-value information.
- inputBuffer
- A pointer to a data structure in the format of the input buffer for the file or record. The length is given by inputBufferLen. NULL if the handler is using name-value information or if the input buffer is irrelevant to the operation.
- inputBufferLen
- The length of the input buffer. Zero if the input buffer is not relevant, or if name-value information is being used.
- inputDataLen
- When the file is externally-described and the record format was
not specified by the RPG program, this subfield must be set by the
handler to indicate the length of the data provided in the input buffer. Note: This is not necessary if name-value information is being used.
- inputNullMap
- A pointer to the null-byte map of the input buffer for the file or record. The length is given by inputNullMapLen.
- inputNullMapLen
- The length of the input null-byte map. Zero if the input null-byte map is not relevant, or if name-value information is being used.
- inputWithLock
- '1' if the input operation is intended to lock the record for later update or delete. '0' otherwise.
- ioFeedback
- A pointer to the information that the handler provides to RPG
to set the I/O feedback part of the file's File Information Data Structure
(INFDS). The handler must set this pointer to storage
that can be accessed by RPG. If this information is not supplied by
the handler, the I/O-feedback part of the INFDS is
not updated by RPG. The length is specified by ioFeedbackLen.
See Setting the feedback areas in the INFDS for more information.
- ioFeedbackLen
- The length of the I/O-feedback information provided by the handler.
- isSubfile
- '1' if the record format used for the operation is a subfile record. '0' otherwise.
- key
- A pointer to a data structure in the format of the key structure for the file or record. The length is given by keyLen. NULL if the handler is using name-value information, or if the operation does not involve keys.
- keyedFile
- '1' if the file is keyed in the RPG program. '0' otherwise.
- keyLen
- The length of the key buffer. Zero if the key buffer is not relevant, or if name-value information is being used.
- keyNamesValues
- A pointer to the QrnNamesValues_T structure listing the names, types, and values of each subfield in the key structure. NULL if the handler is not using name-value information, or if the operation does not involve keys, or if the name-value mode is not available due to the RPG programmer having specified an input operation to a file name where the file has more than one record format.
- keyNullMap
- A pointer to the null-byte map of the key information for the file or record. The length is given by keyNullMapLen. NULL if the handler is using name-value information or if the key is irrelevant to the operation.
- keyNullMapLen
- The length of the key null-byte map. Zero if the key null-byte map is not relevant, or if name-value information is being used.
- namesValues
- A pointer to the QrnNamesValues_T structure listing the names, types, and values of each subfield in the record. NULL if the handler is not using name-value information, or if the operation does not involve input or output, or if the name-value mode is not available due to the RPG programmer having specified an input operation to a file name where the file has more than one record format.
- numKeys
- The number of keys for a keyed-operation to an externally-described file or format.
- openFeedback
- A pointer to the information that the handler provides to RPG
to set the open-feedback part of the file's File Information Data
Structure (INFDS). The handler must set this pointer
to storage that can be accessed by RPG. If this information is not
supplied by the handler, the open-feedback part of the INFDS is
not updated by RPG. The length is specified by openFeedbackLen.
See Setting the feedback areas in the INFDS for more information.
- openFeedbackLen
- The length of the open-feedback information provided by the handler.
- outputBuffer
- A pointer to a data structure in the format of the output buffer for the file or record. The length is given by outputBufferLen. NULL if the handler is using name-value information or if the output buffer is irrelevant to the operation.
- outputBufferLen
- The length of the output buffer. Zero if the output buffer is not relevant, or if name-value information is being used.
- outputNullMap
- A pointer to the null-byte map of the output buffer for the file or record. The length is given by outputNullMapLen. NULL if the handler is using name-value information or if the output buffer is irrelevant to the operation.
- outputNullMapLen
- The length of the output null-byte map. Zero if the output null-byte map is not relevant, or if name-value information is being used.
- parameterFormat
- The format of the parameter structure. This subfield is provided to allow for the possibility of other formats in the future. The RPG program may be able to request a different format; this subfield would indicate the format of the parameter. ROIO0100 is currently the only format.
- printerOverflow
- Set to '1' by the handler if overflow was detected on an output operation to a printer file. The handler can leave it at '0' otherwise.
- prtctl
- A pointer to the print-control structure, QrnPrtctl_T, for a PRINTER file. NULL if the file is not a PRINTER file.
- recordLevels
- A pointer to the QrnRecordLevels_T structure listing the compile-time record-level identifier for each record in the file that is used by the RPG module. NULL if the file is a program-described file.
- recordName
- RPG sets this to the record name if the current I/O operation specifies the record name or if the file has only one record format. Otherwise, RPG sets this to blank. When it is blank, and it is an input operation to an externally-described file, the handler must set this subfield to the name of the record format that was used. This subfield is only meaningful for I/O operations that work with data. It is blank for other operations such as the OPEN operation.
- rpgOperation
- The operation being performed by the RPG program. See The RPG operations to be handled for the constants QrnOperation_* that define the possible values. Usually, rpgOperation maps directly to an RPG operation code, but some operation codes have more than one possible rpgOperation value. For example, the SETLL RPG operation may map to QrnOperation_SETLL, QrnOperation_POSITION_START, or QrnOperation_POSITION_END.
- rpgDevice
- The device type of the file as defined in the RPG program. See Constants QrnRpgDevice_* defining the RPG device types.
- rpgStatus
- The handler may leave this subfield set to zero to indicate that the operation was successful. If the handler determines that the operation is not successful, and the handler does not want to send an exception message to signal the condition, the handler may set this subfield to an RPG status code to have RPG signal the exception associated with that status code. Status 1299 is the RPG status code for general I/O errors, and can be used to signal an error condition for all operations. If this subfield it set to a value that does not represent a valid RPG error status code, the resulting behavior of the RPG program is undefined. See Errors detected by the handler for more information on how the handler can indicate that it discovered an error.
- rrn
- Provided by RPG as the relative record number for an output operation
or the search argument for a keyed operation. Provided by the handler
for an input operation to a database file or a subfile. The relative
record number is available to the RPG programmer through the RECNO. Note: The RPG programmer may also attempt to obtain the relative record number through the Device-Specific Feedback area in the File Information Data Structure (INFDS). To support this, the handler must use the deviceFeedback subfield.
- sln
- The starting line number set by the RPG program for a user-interface record, related to the SLNO(*VAR) keyword for a system display file. If the SLN keyword is not specified for the file in the RPG program, this subfield will have a value of zero.
- stateInfo
- A private area defined by the handler. The handler has complete
control of this pointer. The pointer will retain its value across
calls to the handler. Usually the handler will set this pointer when
the file is open, and it will clean up any storage associated with
this pointer when the file is closed. Note: The pointer must be set to storage that will continue to exist after the handler has returned.
- structLen
- The length of the structure.
- useNamesValues
- Set to '1' by the handler if the handler uses the name-value information rather than the data structure information for I/O buffers and keys. The handler can leave it at '0' otherwise. This subfield should only be changed during the OPEN operation. The behavior is undefined when this subfield is changed after the file has been opened.
- userArea
- A pointer to a handler-defined variable owned by the RPG program.
If the handler wants to share additional information with the RPG programmer, the second parameter of the HANDLER keyword can be used on the File specification for the Open-Access file to specify a variable to be passed to the handler. This subfield is a pointer to the RPG program variable. The RPG variable can have any data type; usually it is a data structure. The RPG program and the handler must agree on the type.