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. If the called program changes any passed data, the storage area that is available to the caller is also changed. For more information about the difference between main and called programs, see “Program part.”

Program calls can be local or remote. The definition of a local call depends on the platform:

The called program is either generated by EGL or is considered to be externally defined. For details about how to indicate that the program is externally defined, see the description of the isExternal property in the “Syntax” section of this topic.

The number, type, and sequence of arguments that you pass in a call statement must correspond to the number, type, and sequence of parameters that the called program expects. There is no limit to the number of parameters you can pass on a local call. For remote calls, the number and size of parameters that can be passed are limited. 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 the required implementations to verify that they support the amount of data you need to pass.

The following rules apply to literals and constants:

For additional details about using the call statement for service invocation, see “Coding a call statement and callback functions for service access.”

When you call a program that was 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 or by specifying a type with the literal. For more information about the textLiteralDefaultIsString property, see textLiteralDefaultIsString; for information about literals, 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 to be externally defined. Many program names, such as those on UNIX or written in Java, are case sensitive. Program names in the EGL debugger are not case sensitive. The name can be a direct part reference without quotation marks, a literal string in quotation marks, or a variable or constant name.
argument
One of a series of value references that are separated by commas. An argument can be a primitive variable, a form, a record, an array of primitive types, an array of records, a non-numeric literal, or a non-numeric constant. If EGL can access the called program at generation time, the argument can be a more complex date/time, numeric, or text expression. You cannot pass a field of type ANY, ArrayDictionary, BLOB, CLOB, DataTable, or Dictionary. You cannot pass arrays of those types, or records that include any of those types. For local calls, there is no limit to the number of arguments. Remote calls might not support more than 30 arguments.
properties
The following properties are supported:
isExternal
A Boolean property:
  • NO, the default, indicates that the callLink element in the linkage options part specifies whether an external program is being called. Placing a value in the callLink element is more flexible; the setting is not embedded in the code.

    The relevant attribute in the callLink element is pgmType for local calls, or remotePgmType for remote or EJB calls.

  • YES indicates that a non-EGL-generated program is being called
isNoRefresh
A Boolean property that is meaningful only when the caller presents text forms and one of the following situations is in effect:
  • The called program does not present a text form.
  • The caller writes a full-screen text form after the call.

This property has two values:

  • NO, the default, indicates that the callLink element in the linkage options part specifies whether a screen refresh is avoided. Setting a value in the callLink element (specifically, in the refreshScreen attribute) is more flexible; the decision is not embedded in the code.
  • YES indicates that a screen refresh is avoided when the called program returns control.
linkageKey
A string that references the callLink element in a linkage options part. The string matches the pgm attribute in that element. For more details, see “linkageKey.”
timeout
An integer that represents the maximum valid number of milliseconds that elapse between a service invocation and reply. For a call statement, this property is solely for Rich UI applications where the value is the maximum number of milliseconds between when the EGL Rich UI Proxy, on the web server, invokes a service and when the Proxy receives a response. For more details, see “Coding a call statement and callback function for service access.”

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)
An IMS™ transaction
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)
An IMS transaction
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)
An IMS transaction
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
A Java program on IBM® i
A COBOL program on IBM i
A non-EGL program that was written in C or C++
An IMS/VS program (generated by EGL or not)
An IMS transaction
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
A Java program on IBM i
A COBOL program on IBM i
A non-EGL program that was written in C or C++
An IMS/VS program (generated by EGL or not)
An IMS transaction
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
A Java program on IBM i
A COBOL program on IBM i
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 IBM i An EGL COBOL program on IBM i
A non-EGL program written in any language and running on IBM i
A non-EGL program written in any language and running on IBM i An EGL COBOL program on IBM i
A non-EGL program written in any language and running on IBM i

To call EGL-generated Java code from non-EGL-generated Java code, use an EGL external type or a Java access function.

Example

The following example shows a called program that calculates 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 that are passed in each argument must be the same as the number of bytes that are expected by the receiving parameter. For more information, see "Compatibility."

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 that are 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 are permitted for the zSeries only. This support depends upon COBOL allowing the recursion. This is typically not a problem under CICS, but could be a problem in batch mode. Recursive calls must be enabled by setting the symbolic parameter ALLOWRECURSIVEPROGRAMS to YES. For more information, see Predefined symbolic parameters that can be set by the user.
CICS If the number of bytes that are passed in each argument does not equal the number of bytes that are 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