RPG coding to use Open Access

Other than the HANDLER keyword, there is no new RPG syntax related to using an Open-Access file.

HANDLER keyword

The RPG programmer indicates that a file is an Open-Access file by coding the HANDLER keyword on the File specification. All the operations allowed by RPG for the specified device (DISK, PRINTER, WORKSTN) are available for the Open-Access file.

The HANDLER keyword identifies the program or procedure that will handle all operations for the file.

Figure 1. Example of the HANDLER keyword

Fmyfile    CF   E          WORKSTN HANDLER('MYLIB/MYSRV(hdlMyfile)')
The HANDLER keyword has two parameters:
Handler
This keyword parameter can have one of the following values:
  • A character literal or character variable identifying a procedure in a service program. The value must be in the form 'LIBRARY/SRVPGM(procedure)' or 'SRVPGM(procedure)'. The names are case-sensitive.
  • A character literal or character variable identifying a program. The value must be in the form 'LIBRARY/PGM' or 'PGM'. The names are case-sensitive.
  • A prototype for a bound procedure.
  • A procedure pointer literal (%PADDR) or variable.

When the handler is identified by a prototype or by %PADDR, it is resolved at bind time of the RPG program. When the handler is identified by a character literal or character variable, it is resolved each time the Open-Access file is opened.

Parameter passed to the handler (optional)
This keyword parameter identifies an RPG variable to be passed to the handler from the RPG program.

This parameter can be used to pass additional information to the handler that is not available through an RPG file operation.

For example, to process a file in the Integrated File System, the handler needs to know the path to the file. The RPG programmer can provide this through the second HANDLER keyword parameter. The second parameter is the name of a variable, usually a data structure. In the example below, the variable is the data structure ifsDs. When the handler is called, it will receive a pointer to the ifsDs data structure.

The provider of the handler would tell the RPG programmer whether the additional information was required, and what data structure to use as a template. Usually, the provider of the handler would provide a template data structure in a /COPY file. In the example, the library MYLIB contains the handler service program HDL_IFS containing procedure readIfs, the database file HDL_IFS, and the /COPY File QRPGLESRC with member HDL_IFS. The copy file has the template data structure hdlIfs_t.
Figure 2. Example of the HANDLER keyword with two parameters

FmyIfsFile IF   E   DISK  EXTDESC('MYLIB/HDL_IFS')
F                         USROPN
F                         HANDLER(‘MYLIB/HDL_IFS(readIfs)
F                               : ifsDs)
 /copy MYLIB/QRPGLESRC,HDL_IFS
D ifsDs         DS        LIKEDS(hdlIfs_t)
 /FREE
    ifsDs.path = '/home/mydir/myIfsFile.txt';
    OPEN myIfsFile;

Comparison to RPG SPECIAL files

An Open-Access file is similar in nature to a SPECIAL file. A SPECIAL file also uses a user-written program to handle the operations for the file, and it allows additional parameters to be passed to the handler from the RPG program.

Some of the differences between Open-Access files and SPECIAL files are
  • A SPECIAL file only allows the operations available for a sequential (SEQ) file. An Open-Access file can be defined for any type of RPG device, and can use all the operations available for that device.
  • A SPECIAL file handler only receives a minimal amount of information about the file operation. An Open-Access file handler receives much more information such as the name of the file, record format, the names and types of the fields.
  • A SPECIAL file handler can only pass back a minimal amount of feedback information: the result status of 0, 1 or 2, and a 5-digit SPECIAL error code value. If an error occurs for a SPECIAL file, the RPG status code is always 1231 (Error in SPECIAL file). An Open-Access handler has the ability to pass back much more information such as the RPG status code, the file feedback areas, the relative record number, function-key pressed, printer overflow.
  • A SPECIAL file handler can only be a program. An Open-Access handler can be a program or a procedure.