Handler parameter

The same parameter is passed to the handler for all operations to the file.

The parameter is a data structure with several types of subfields:

Subfields that must be set by the handler for later use by RPG
The handler is responsible for setting some of the subfields in the handler parameter before returning to the RPG program. These subfields provide the information that tells RPG about the result of the operation. For example
  • For the search operation QrnOperation_CHAIN, the found subfield must be set to '1' to indicate that a matching record was found.
  • For an input capable operation, the handler must provide the data for all of the input capable fields.
Subfields that are set by RPG for use by the handler
RPG sets some subfields that tell the handler about the nature of the file, or the nature of the operation that the handler is required to perform. For example
  • The rpgOperation subfield indicates which operation to perform.
  • The rpgDevice subfield indicates the type of file defined in the RPG program.
Subfields that may be set by the handler for use by the RPG programmer
Some subfields provide feedback information that may be required by the RPG program. For example
  • If the RPG program uses the *INKx indicators, the functionKey subfield can be set to indicate that one of the function keys F1-F24 was pressed. If the RPG program monitors for status codes 1121-1126, the functionKey subfield can be set to indicate that one of the special keys such as the PRINT key was pressed.
  • If the RPG program has a File Information Data Structure (INFDS) defined for the file, and the INFDS is longer than 80 bytes, then the handler may need to provide feedback for the file using the openFeedback, ioFeedback, and deviceFeedback subfields.
Subfields that allow the handler to maintain private information
  • If the handler needs to share additional information with the RPG programmer, the second parameter of the HANDLER can be used in the RPG program to define a variable whose address will be passed to the handler in the userArea subfield of the handler parameter.
  • If the handler needs to maintain private information across calls to the handler, the stateInfo subfield can be used to hold a pointer to the information.