call

The EGL call statement transfers control to another program and optionally passes a series of values. Control returns to the caller when the called program ends; and if the called program changes any data that was passed by way of a variable, the storage area available to the caller is changed, too.

program name

Name of the called program. The program is either generated by EGL or is considered externally defined.

The specified name cannot be a reserved word. If the caller must call a non-EGL program that has the same name as an EGL reserved word, use a different program name in the call statement, then use a linkage options part, callLink element to specify an alias, which is the name used at run time.

If the called program is a Java program, the called program name is case-sensitive; calledProgram is different from CALLEDPROGRAM. Otherwise, the determination of whether the program name is case-sensitive depends on the system on which the called program resides: case-sensitive for UNIX, case-insensitive otherwise.

In the EGL debugger, the called program name is case-insensitive.

argument

One of a series of value references, each separated from the next by a comma. An argument may be an item; a form; a record; a non-numeric literal; a non-numeric constant; or (if EGL has access to the called program at generation time) a more complex datetime, numeric, or text expression.

externallyDefined

An indicator that the program is externally defined. This indicator is available only if you set the project property for VisualAge Generator compatibility.

It is recommended that a non-EGL-generated program be identified as externally defined not in the call statement, but in the linkage options part that is used at generation time. (The related property is in the linkage options part, callLink element, and is also called externallyDefined.)

noRefresh

An indicator that a screen refresh is to be avoided when the called program returns control.

The indicator is supported (at development time) if the program property VAGCompatibility is selected or (at generation time) if the build descriptor option VAGCompatibility is set to yes.

This indicator is appropriate if the caller is in a run unit that presents text forms to a screen and either of these situations is in effect:

• The called program does not present a text form; or

• The caller writes a full-screen text form after the call.

It is recommended that you indicate your preference for screen refresh not in the call statement, but in the linkage options part that is used at generation time. (The related property is in the linkage options part, callLink element, and is called refreshScreen.)

An example is as follows:

  if (userRequest = "C")
    try
      call programA;
    onException
      myErrorHandler(12);
    end
  end

The number, type, and sequence of arguments in a call statement must correspond to the number, type, and sequence of values expected by the called program.

It is strongly recommended that the number of bytes passed in each argument be the same as the number of bytes expected.A length mismatch causes an error only if the run-time correction of that mismatch causes a type mismatch:

• If the called Java program receives too few bytes, the end of the passed data is padded with blanks.

• If the called Java program receives too many bytes, the end of the passed data is truncated.

An error occurs if blanks are added to a data item of type NUM, for example, but not if blanks are added to a data item of type CHAR.

The following rules apply to literals and constants:

• The size of a passed literal or constant must equal the size of the receiving parameter

• A numeric literal or constant cannot be passed as an argument

• A literal or constant that includes only single-byte characters may be passed to a parameter of type CHAR or MBCHAR

• A literal or constant that includes only double-byte characters may be passed only to a parameter of type DBCHAR

• A literal or constant that includes a combination of single- and double-byte characters may be passed to a parameter of type MBCHAR

Recursive calls are supported for all target systems.

The call is affected by the linkage options part, if any, that is used at generation time. (You include a linkage options part by setting the build descriptor option linkage.)

For details on linkage, see Linkage options part.

Related concepts
Linkage options part
Syntax diagram

Related reference
EGL statements
Exception handling
linkage
Primitive types