Using the Fixed-Form Call Operations - IBM - RPG

You use the CALL (Call a Program) operation to make a program call and the CALLB (Call a Bound Procedure) operation to make a procedure call to programs or procedures that are not prototyped. The two call operations are very similar in their syntax and their use. To call a program or procedure, follow these general steps:

  1. Identify the object to be called in the Factor 2 entry.
  2. Optionally code an error indicator (positions 73 and 74) or an LR indicator (positions 75 and 76) or both. When a called object ends in error the error indicator, if specified, is set on. Similarly, if the called object returns with LR on, the LR indicator, if specified, is set on.
  3. To pass parameters to the called object, either specify a PLIST in the Result field of the call operation or follow the call operation immediately by PARM operations.

Either operation transfers control from the calling to the called object. After the called object is run, control returns to the first operation that can be processed after the call operation in the calling program or procedure.

The following considerations apply to either call operation:

  • The Factor 2 entry can be a variable, literal, or named constant. Note that the entry is case-sensitive.

    For CALL only: The Factor 2 entry can be library name/program name, for example, MYLIB/PGM1. If no library name is specified, then the library list is used to find the program. The name of the called program can be provided at run time by specifying a character variable in the Factor 2 entry.

    For CALLB only: To make a procedure pointer call you specify the name of the procedure pointer which contains the address of the procedure to be called.

  • A procedure can contain multiple calls to the same object with the same or different PLISTs specified.
  • When an ILE RPG procedure (including a program entry procedure) is first called, the fields are initialized and the procedure is given control. On subsequent calls to the same procedure, if it did not end on the previous call, then all fields, indicators, and files in the called procedure are the same as they were when it returned on the preceding call.
  • The system records the names of all programs called within an RPG procedure. When an RPG procedure is bound into a program (*PGM) you can query these names using DSPPGMREF, although you cannot tell which procedure or module is doing the call.

    If you call a program using a variable, you will see an entry with the name *VARIABLE (and no library name). For a module, you can query the names of procedures called using DSPMOD DETAIL(*IMPORT). Some procedures on this list will be system procedures; the names of these will usually begin with underscores or contain blanks and you do not have to be concerned with these.

  • For CALLB only: The compiler creates an operational descriptor indicating the number of parameters passed on the CALLB operation and places this value in the *PARMS field of the called procedure’s program status data structure. This number includes any parameters which are designated as omitted (*OMIT on the PARM operation). If the (D) operation extender is used with the CALLB operation the compiler also creates an operational descriptor for each character and graphic field and subfield. For more information on operational descriptors, see “Using Operational Descriptors”.
  • There are further restrictions that apply when using the CALL or CALLB operation codes. For a detailed description of these restrictions,

Examples of CALL and CALLB

For examples of using the CALL operation, see:

  • “Sample Source for Debug Examples” for example of calling an RPG program.

Passing Parameters Using PARM and PLIST

When you pass parameters using fixed-form call, you must pass parameters using the PARM and PLIST operations. All parameters are passed by reference. You can specify that an operational descriptor is to be passed and can also indicate that a parameter is omitted.

Using the PARM operation
The PARM operation is used to identify the parameters which are passed from or received by a procedure. Each parameter is defined in a separate PARM operation. You specify the name of the parameter in the Result field; the name need not be the same as in the calling/called procedure.

The Factor 1 and factor 2 entries are optional and indicate variables or literals whose value is transferred to or received from the Result Field entry depending on whether these entries are in the calling program/procedure or the called program/procedure. This shows how factor 1 and factor 2 are used.

Meaning of Factor 1 and Factor 2 Entries in PARM Operation
Meaning of Factor 1 and Factor 2 Entries in PARM Operation

Note: The moves to either the factor 1 entry or the result-field entry occur only when the called procedure returns normally to its caller. If an error occurs while attempting to move data to either entry, then the move is not completed.

If insufficient parameters are specified when calling a procedure, an error occurs when an unresolved parameter is used by the called procedure. To avoid the error, you can either:

  • Check %PARMS to determine the number of parameters passed. For an example using %PARMS, see “Checking for the Number of Passed Parameters”.
  • Specify *OMIT in the result field of the PARM operations of the unpassed parameters. The called procedure can then check to see if the parameter has been omitted by checking to see if the parameter has value of *NULL, using %ADDR(parameter) = *NULL. For more information, refer to “Omitting Parameters”.
  • Keep in mind the following when specifying a PARM operation:

  • One or more PARM operations must immediately follow a PLIST operation.
  • One or more PARM operations can immediately follow a CALL or CALLB operation.
  • When a multiple occurrence data structure is specified in the Result field of a PARM operation, all occurrences of the data structure are passed as a single field.
  • Factor 1 and the Result field of a PARM operation cannot contain a literal, a look-ahead field, a named constant, or a user-date reserved word.
  • The following rules apply to *OMIT for non-prototyped parameters:
    – *OMIT is only allowed in PARM operations that immediately follows a CALLB operation or in a PLIST used with a CALLB.
    – Factor 1 and Factor 2 of a PARM operation must be blank, if *OMIT is specified.
    – *OMIT is not allowed in a PARM operation that is part of a *ENTRY PLIST.
  • There are other restrictions that apply when using the PARM operation code.

Using the PLIST Operation

The PLIST operation:

  • Defines a name by which a list of parameters can be referenced. The list of para meters is specified by PARM operations immediately following the PLIST operation.
  • Defines the entry parameter list (*ENTRY PLIST).

Factor 1 of the PLIST operation must contain the PLIST name. This name can be specified in the Result field of one or more call operations. If the parameter list is the entry parameter list of a called procedure, then Factor 1 must contain *ENTRY.

Multiple PLISTs can appear in a procedure. However, only one *ENTRY PLIST can be specified, and only in the main procedure.

All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd Protection Status

IBM - RPG Topics