Open Access Handlers
An Open Access handler is responsible for handling all the operations for an Open Access file.
The handler is called when the file is opened, when it is closed, and for any input or output operation for the file.
The parameter passed to the handler
The handler is passed a single parameter. Copy member QRNOPENACC in file QOAR/QRPGLESRC contains the data-structure template QrnOpenAccess_T which can be used with the LIKEDS keyword to define the parameter in the handler.
The handler parameter contains many pointer subfields that point to other structures. The copy file contains additional data-structure templates that can be used to define these other structures. For example, the prtctl subfield can be used as the basing pointer for a structure defined with keyword LIKEDS(QrnPrtctl_T).
The copy file also contains several named constants that can be used within the handler. For example, there are several named constants whose names begin with QrnOperation_, such as QrnOperation_OPEN, that can be used with subfield rpgOperation of the handler parameter.
The subfields provide the handler with all the information it needs to perform the required operation. For example, for an output operation, it receives the data to be written to the file.
The subfields also allow the handler to pass back all the information needed by RPG following the operation. For example, for an input operation, the handler can pass back the input data, and it can pass back information about whether the file reached end-of-file.
If the handler needs to maintain state information that is available across calls to the handler, it can use the stateInfo pointer subfield in the handler parameter. If the handler places a pointer value in this subfield during one call to the handler, the same pointer value will be avaiable for all subsequent calls to the handler for that particular file. Normally, a handler will allocate storage for the state information while it is handling the OPEN operation, and it will deallocate the storage when it is handling the CLOSE operation.
Errors in the handler
If the handler fails with an unhandled exception, the RPG operation will fail with a status code relevant to the operation. For example, if the operation is an OPEN or a CLOSE operation, the error status will be either 1216 or 1217. For other operations, the status will be 1299.
- Send an exception message that will cause the handler
to end with an unhandled exception.
This message will appear in the joblog, and the subsequent RPG
error message will refer to this error message.
The advantage of this mechanism is that the handler ends as soon as the exception message is sent, so the handler does not have to keep track of whether the operation has failed.
- Set the rpgStatus subfield of
the handler parameter to the desired RPG status code.
It may also be helpful to send a diagnostic message to
the joblog.
The advantage of this mechanism is that the handler can choose the exact status code. For example, there are several status codes associated with WORKSTN operations.
See the Rational Open Access: RPG Edition topic for information on writing an Open Access handler.