HANDLER(program-or-procedure { : communication-area)})

The HANDLER keyword indicates that the file is an Open Access file. It can be specified for files with device DISK, PRINTER, SEQ, or WORKSTN.

The first parameter specifies the program or procedure that handles the input and output operations for the file. It can be specified in the following ways:

A character literal containing the name of a program or a library-qualified program. The names are case-sensitive.
```
   'MYPGM'
   '*LIBL/MYPGM'
   'MYLIB/MYPGM'
```
For example, the handler for this file is program *LIBL/MYPGM.
```
   DCL-F myfile HANDLER('MYPGM');
```
A character literal containing the name of a procedure in a service program. The service program is specified first either as simply a service-program name, or a library-qualified service program name. The service program is followed by the name of the procedure in parentheses. The names are case-sensitive.
```
   'MYSRVPGM(myProcecedure)'
   '*LIBL/MYSRVPGM(myProcedure)'
   'MYLIB/MYSRVPGM(myProcedure)'
```
For example, the handler for this file is procedure MyProc in service program MYLIB/MYSRVPGM.
```
   DCL-F myfile HANDLER('MYLIB/MYSRVPGM(MyProc)');
```

A character variable holding the name of a program or a procedure in a service program.

For example, the handler for this file is character variable handlerName. The file is opened twice with different handlers.

   DCL-F myfile HANDLER(handlerName) USROPN;
   DCL-S handlerName CHAR(50);

   handlerName = 'MYLIB/MYPGM';
   OPEN myfile;
   READ myfile;
   CLOSE myfile;

   handlerName = 'MYLIB/MYSRVPGM(myHandler)';
   OPEN myfile;
   READ myfile;
   CLOSE myfile;

A procedure pointer.

For example, the handler for this file is procedure pointer handlerPointer. The file is opened twice with different handlers.

   DCL-F myfile HANDLER(handlerPointer) USROPN;
   DCL-S handlerPointer POINTER(*PROC);

   handlerPointer = %PADDR('proc_a');
   OPEN myfile;
   READ myfile;
   CLOSE myfile;

   handlerPointer = %PADDR('proc_b');
   OPEN myfile;
   READ myfile;
   CLOSE myfile;

A prototype name.

For example, the handler for this file is prototype myHandler.

   DCL-F myfile HANDLER(myproc);

   /COPY QOAR/QRPGLESRC,QRNOPENACC
   DCL-PR myproc;
      parm LIKEDS(QrnOpenAccess_T);
   END-PR;

Note:

If the first parameter is a variable, it must be set before the file is opened.
If the handler procedure is in the same module as the Open Access file, the file must be defined with the USROPN keyword.

The second parameter is optional. It specifies a variable that is passed to the handler to allow the RPG program to share additional information directly with the handler.

In the following example, the handler expects the communication area to be a data structure with a 10-character option subfield.

Note: It is up to the RPG programmer to define the communication area variable the way the handler expects it. Usually, a copy file would be used to define a template data structure for the communication area. See Example of an Open Access Handler for a complete example of an Open Access file that shows how to use a copy file to ensure that the RPG program and the handler use the same definition for the communication area.

   DCL-F myfile HANDLER('MYPGM' : options) USROPN;

   DCL-DS options QUALIFIED;
      detail CHAR(10);
   END-DS;

   options.detail = 'FULL';
   OPEN myfile;
   . . .
   CLOSE myfile;

   options.detail = 'NONE';
   OPEN myfile;
   . . .