Although the extensions to RPG syntax that came with RPG II and RPG III (and undoubtedly RPG IV as well) remove any barriers that prevent RPG programs from completing any task that can be achieved with any other programming language, the original RPG does have some shortcomings. However, when confronted with a task that RPG syntax can't handle, it is easy to call an external routine written in Assembler.
Three operation codes are provided for this function: EXIT, RLABL, and ULABL.
The EXIT operation names the ENTRY name or CSECT name of the Assembler program to be called. In fact, the EXIT operation transfers control to the Assembler program at the point in the Calculation specifications where the EXIT operation is coded. The requisite RLABL and/or ULABL operations that are coded along with the EXIT operation are typically coded following the EXIT operation. Upon completion of the Assembler program, control returns to the RPG main program and execution continues with the next operation following the last RLABL or ULABL associated with the EXIT.
The Assembler CSECT or ENTRY name must be coded in the Factor 2 field (columns 33-42).
Like other Calculation Specifications, the EXIT operation is executed in sequence with other specifications at the same level (detail or total time) and may be controlled by resulting and control level indicators. If the EXIT operation is either the first or the last entry of the detail or total time specifications, the branch to the subprogram will take place as follows:
Operation placement When the branch will occur first detail at the end of the data routine - after the data is extracted from the input record(s) last detail immediately before heading output records are written first total at the end of the input routine - after the record type(s) have been determined and the control field break(s) have been tested last total immediately before total output records are written
The RLABL operation specifies data fields defined in the RPG program that are to be made available to the Assembler subprogram. The data field name must be coded in the Result field (columns 43-48). Optionally, the length of the data field and number of decimal positions may be entered (columns 49-51 and 52 respectively). I can find nothing (in my admittedly small amount or RPG reference sources) about the effect of coding length and decimal positions, but from my knowledge of the linkage mechanism, I can't believe these entries will have much affect on the transfer of information between the main program and the subprogram.
The ULABL operation specifies data fields that are defined in the Assembler subprogram that are to be referenced by the RPG main program after control returns from the subprogram. The data field name must be coded in the Result field (columns 43-48). This name must be the same as the name declared in the Assembler subprogram in an ENTRY statement in order for the linkage to be established correctly. The field length must be coded for ULABL fields (columns 49-51) and the number of decimal positions must be entered if the field is to be treated as a numeric field by the RPG program (column 52). Remember, fields named in ULABL operations are defined in the Assembler subprogram, but you must give the RPG compiler the information it needs to process the fields properly when referenced by other RPG statements.
RLABL and ULABL operations may be interspersed, and can occur anywhere in the Calculation specifications. By convention, RLABL and ULABL operations are placed immediately preceding or following the EXIT operation with which they are associated. Functionally, these operations simply identify the symbols to be resolved by the linkage editor and do not actually generate any additional code in the RPG program.
Any RPG defined data field or indicator may be named in an RLABL operation, including table fields. The Assembler subprogram can reference the data accessed from a LOKUP operation by referring to the data field TABXXX, that is, the table name of the function accessed.
Indicators may be made available to the Assembler subprogram by using the field name INnn where nn refers to the indicator identifier.
Both data fields and indicators made available to an Assembler subprogram must be defined in the RPG main program in an operation distinct from and in addition to the RLABL operation. For example, if an Assembler subprogram is to be able to set on indicator 50 to signal a particular condition to the RPG main program upon return, it would be necessary to include indicator 50 in a SETOF operation in addition to the indicator appearing in a RLABL field, if indicator 50 were not defined in any other manner in the RPG program.
To test indicators in an Assembler subprogram:
- if on, the data at INxx will be hexadecimal F0,
- if off, the data at INxx will be hexadecimal 00.
To set indicators in an Assembler subprogram:
- to set an indicator on, set the data located at INxx to hexadecimal F0,
- to set an indicator off, set the data located at INxx to hexadecimal 00.
Indicators 00 and L0 must never be set off.
Managing the linkage between an RPG main and Assembler subprograms is almost easier than the mechanism used to pass variables used in other higher level languages. The RLABL operation makes data field names defined in the RPG main program visable externally to the RPG object program. That is, they become ENTRY names in the symbol dictionary. The ULABL operation defines external references using the name supplied as an entry in the symbol dictionary. These field references, along with the names of the Assembler CSECT(s) named in EXIT operations will be resolved by the Linkage Editor.
External subprograms may be supplied to the Linkage Editor either by using libraries of separately assembled and link edited modules (DD SYSLIB) or by including specific datasets containing the object modules and referencing these datasets in Linkage Editor control statements.
This page was last updated on January 17, 2015.