Using SPECIAL Files

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 190. 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 54 shows the file operation codes that are valid for a SPECIAL file.