The RPG device name SPECIAL (positions 36 - 42 of the file description
specifications) allows you to specify an input and/or output device that is
not directly supported by the ILE RPG operations. The input and output operations
for the file are controlled by a user-written routine. The name of the user-written
routine, must be identified in the file description specifications using the
keyword PGMNAME('program name').
ILE RPG calls this user-written routine to open the file, read and write
the records, and close the file.
ILE RPG also creates a parameter list for
use by the user-written routine. The parameter list contains:
- option code parameter (option)
- return status parameter (status)
- error-found parameter (error)
- record area parameter (area).
This parameter list is accessed by the ILE RPG compiler and by the user-written
routine; it cannot be accessed by the program that contains the SPECIAL file.
The following describes the parameters in this RPG-created parameter list:
- Option
- The option parameter is a one-position character field that indicates
the action the user-written routine is to process. Depending on the operation
being processed on the SPECIAL file (OPEN, CLOSE, FEOD, READ, WRITE, DELETE,
UPDATE), one of the following values is passed to the user-written routine
from ILE RPG:
- Value Passed
- Description
- O
- Open the file.
- C
- Close the file.
- F
- Force the end of file.
- R
- Read a record and place it in the area defined by the area parameter.
- W
- The ILE RPG program has placed a record in the area defined by the area
parameter; the record is to be written out.
- D
- Delete the record.
- U
- The record is an update of the last record read.
- Status
- The status parameter is a one-position character field that indicates
the status of the user-written routine when control is returned to the ILE RPG program.
Status must contain one of the following return values when the user-written
routine returns control to the ILE RPG program:
- Return Value
- Description
- 0
- Normal return. The requested action was processed.
- 1
- The input file is at end of file, and no record has been returned. If
the file is an output file, this return value is an error.
- 2
- The requested action was not processed; error condition exists.
- Error
- The error parameter is a five-digit zoned numeric field with zero decimal
positions. If the user-written routine detects an error, the error parameter
contains an indication or value representing the type of error. The value
is placed in the first five positions of location *RECORD in the INFDS when
the status parameter contains 2.
- Area
- The area parameter is a character field whose length is equal to the
record length associated with the SPECIAL file. This field is used to pass
the record to or receive the record from the ILE RPG program.
You can add additional parameters to the RPG-created parameter list. Specify
the keyword PLIST(parameter list name) on the file
description specifications for the SPECIAL file. See Figure 1.
Then use the PLIST operation in the calculation specifications to define the
additional parameters.
The user-written routine, specified by the keyword PGMNAME of the file
description specifications for the SPECIAL file, must contain an entry parameter
list that includes both the RPG-created parameters and the user-specified
parameters.
If the SPECIAL file is specified as a primary file, the user-specified
parameters must be initialized before the first primary read. You can initialize
these parameters with a factor 2 entry on the PARM statements or by the specification
of a compile-time array or an array element as a parameter.
Table 1 shows the file operation codes that are valid for
a SPECIAL file.
Table 1. Valid File Operations for a SPECIAL File| File Description
Specifications Positions |
Calculation Specifications Positions |
| 17 |
18 |
26-35 |
| I |
P/S |
CLOSE, FEOD |
| C |
P/S |
WRITE, CLOSE, FEOD |
| U |
P/S |
UPDATE, DELETE, CLOSE, FEOD |
| O |
|
WRITE, OPEN, CLOSE, FEOD |
| I |
F |
READ, OPEN, CLOSE, FEOD |
| C |
F |
READ, WRITE, OPEN, CLOSE, FEOD |
| U |
F |
READ, UPDATE, DELETE, OPEN, CLOSE, FEOD |