call

The EGL call statement transfers control from a main program to a called program; the called program returns control to the main program when it ends. The main program optionally passes parameters to the called parameter; and if the called program changes any passed data, the storage area available to the caller is also changed. For more about the difference between main and called programs, see "Program part."

The called program is either generated by EGL or is considered externally defined. For externally defined programs, you have two options:

The number, type, and sequence of arguments that you pass in a call statement must correspond to the number, type, and sequence of parameters expected by the called program. For remote calls, there are limits to the number and size of parameters that can be passed. All remote call implementations support passing at least 30 parameters with a combined parameter length of less than 32,000 bytes. If your design requires more than 30 parameters or passing more than 32,000 bytes per call, test with all required implementations to verify that they support the amount of data you need to pass.

The following rules apply to literals and constants:

When calling a program migrated from VisualAge® Generator, remember that VisualAge Generator developers generally use fixed text variable types. You can control the type of character literals through the textLiteralDefaultIsString property (see textLiteralDefaultIsString) or by specifying a type with the literal (see Literals.)

Syntax

Syntax diagram for the call statement
programName
Name of the called program. The program is either generated by EGL or is considered externally defined. Many program names, such as those written in Java™ or residing on UNIX®, are case sensitive. Program names in the EGL debugger are not case sensitive. The name can be a direct part reference (no quotation marks), a literal string (in quotation marks), or a variable or constant name.
argument
One of a series of value references, each separated from the next by a comma. An argument can be a primitive variable; a form; a record; an array of primitive types; an array of records; a non-numeric literal; a non-numeric constant; or (if EGL has access to the called program at generation time) a more complex date/time, numeric, or text expression. You cannot pass a field of type ANY, ArrayDictionary, BLOB, CLOB, DataTable, or Dictionary. Also, you cannot pass arrays of those types, or records that include any of those types.
properties
A set of name-value pairs, enclosed in braces and separated by commas, that provide more information about the statement. See Transfer of control statement properties.

Valid calls

The following table shows the valid calls to or from EGL-generated code.

Table 1. Valid calls in EGL
Calling object Called object
An EGL-generated Java wrapper in a Java class that is outside of J2EE An EGL-generated Java program (non-J2EE)
An EGL-generated Java program in a J2EE application client
An EGL-generated EJB session bean
An IMS/VS program (generated by EGL or not)
A CICS® program (generated by EGL or not)
An EGL-generated Java wrapper in a J2EE application client An EGL-generated Java program (non-J2EE)
An EGL-generated Java program in a J2EE application client
An EGL-generated EJB session bean
An IMS/VS program (generated by EGL or not)
A CICS program (generated by EGL or not)
An EGL-generated Java wrapper in a J2EE Web application An EGL-generated Java program (non-J2EE)
An EGL-generated Java program in a J2EE application client
An EGL-generated Java program in the same J2EE Web application
An EGL-generated EJB session bean
An IMS/VS program (generated by EGL or not)
A CICS program (generated by EGL or not)
An EGL-generated Java program that is outside of J2EE An EGL Java program (non-J2EE)
An EGL Java program in a J2EE application client
An EGL EJB session bean
An iSeries Java program
An iSeries COBOL program
A non-EGL program that was written in C or C++
An IMS/VS program (generated by EGL or not)
A CICS program (generated by EGL or not)
An EGL Java program that is in a J2EE application client An EGL Java program (non-J2EE)
An EGL Java program in a J2EE application client
An EGL EJB session bean
An iSeries Java program
An iSeries COBOL program
A non-EGL program that was written in C or C++
An IMS/VS program (generated by EGL or not)
A CICS program (generated by EGL or not)
An EGL Java program in a J2EE Web application An EGL Java program (non-J2EE)
An EGL Java program in a J2EE application client
An EGL Java program in the same J2EE Web application
An iSeries Java program
An iSeries COBOL program
A non-generated program written in C or C++
A CICS program (generated by EGL or not)
An EGL EJB session bean An EGL Java program (non-J2EE)
An EGL Java program in a J2EE application client
An EGL EJB session bean
A non-generated program written in C or C++
A CICS program (generated by EGL or not)
An EGL CICS program A CICS program (generated by EGL or not)
An EGL z/OS® batch program
An EGL z/OS batch program A batch program written in any language (including EGL) and running on z/OS (outside of CICS or IMS™)
A non-EGL CICS program A CICS COBOL program (generated by EGL or not)
A batch program written in any language (including EGL) and running on z/OS (outside of CICS or IMS)
An EGL COBOL program on iSeries® An EGL COBOL program on iSeries
A non-EGL program written in any language and running on iSeries
A non-EGL program written in any language and running on iSeries An EGL COBOL program on iSeries
A non-EGL program written in any language and running on iSeries

Example

The following example shows a called program that figures interest on a loan:

  if (userRequest == "C")
    try
      call programA(myCustomer, interestRate);
    onException(myEx InvocationException)
      myErrorHandler(12);
    end
  end

Error conditions

The number of bytes passed in each argument must be the same as the number of bytes expected by the receiving parameter; see "Compatibility."

Note that an exception in a remotely called program never propagates directly to the calling program. Instead it is wrapped by an InvocationException. If the remotely called program does not handle an exception, the called program ends and the caller throws an InvocationException.

Compatibility

Table 2. Compatibility considerations for the call statement
Platform Issue
Java generation
  • A length mismatch causes an error only if the runtime correction of that mismatch causes a type mismatch:
    • If the called program receives too few bytes, the end of the passed data is padded with blanks.
    • If the called program receives too many bytes, the end of the passed data is truncated.
    For example, if blanks are added to a variable of type NUM and the called program attempts to use the data in that variable, EGL throws a RuntimeException. If blanks are added to a variable of type CHAR, no exception occurs.
  • For SMALLFLOAT and FLOAT variables passed as arguments on a call statement or on a service function invocation, the Java runtime uses the IBM® 370 format when the remoteComType is CICSECI, CICSJ2C, CICSSSL, IMSJ2C, or IMSTCP. The Java runtime uses the IEEE format when converting data for other kinds of calls or function invocations.
COBOL generation Recursive program calls (calling programs from inside themselves) are not permitted.
CICS If the number of bytes passed in each argument does not equal the number of bytes expected by a CICS program, a runtime abend occurs.
Rich UI A version of the call statement is supported, but only to invoke services. For details, see Coding a call statement and callback function for service access.

Feedback