transfer

A transfer statement transfers control from one main program to another, ending the source program. The source program can optionally pass a record into the input record of the target program. The target program can optionally use another transfer statement to transfer to the source program again (as in a menu program). You cannot use a transfer statement to transfer to a called program. For more about the difference between main and called programs, see Program part.

There are two forms of the EGL transfer statement. You cannot use either form of the statement in a called program. The two forms have the following individual limitations:

The program or transaction you transfer to is either generated by EGL or is considered externally defined. For externally defined programs, you must either set the isExternallyDefined property to YES on the transfer statement or create a transferToProgram or a transferToTransaction element in a linkage options part. For more information on this subject, see Using linkage options parts in a call or transfer.

Syntax

Syntax diagram for the transfer statement
targetName
The main program or transaction that receives control. The name can be a direct part reference (no quotes), a literal string (in quotation marks), or a variable or constant name.
recordName
A record that is received as the input record in the target program. The passed record can be of any type, but the length and primitive types must be compatible with the record that receives the data. The input record in the target program must be a basic record.
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 transfers

The next table shows the valid transfers to or from EGL-generated code.

Table 1. Valid transfers in EGL
Transferring object Target object
An EGL Java™ program that is outside of J2EE An EGL Java program (non-J2EE)
An EGL Java program that is in a J2EE application client An EGL Java program in the same J2EE application client
An EGL Java program in a J2EE Web application An EGL Java program in the same J2EE Web application
An EGL CICS® COBOL program An EGL CICS COBOL program
A non-EGL program that was written in any language and runs under CICS
An EGL z/OS® batch program An EGL z/OS batch program
A non-EGL batch program (written in any language and running outside of CICS on z/OS)
A non-EGL CICS program An EGL CICS COBOL program
A non-EGL CICS COBOL program
An EGL 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

In the following example, the current program transfers control to a program named processCustomer:
transfer to program com.CompanyB.CustomerPackage.processCustomer;

Compatibility

Table 2. Compatibility considerations for the transfer statement
Platform Issue
Batch environments (z/OS main batch program, IMS™ BMP, or Java main text or main batch program) The transfer to transaction statement starts a program in the same run unit, but pre-transfer behavior depends on the setting of the synchOnTrxTransfer build descriptor option:
  • If the value of synchOnTrxTransfer is NO (the default), the transfer to transaction statement does not close or commit resources, which are available to the invoked program.
  • If the value of synchOnTrxTransfer is YES, the transfer to transaction statement commits recoverable resources, closes files, and closes cursors.
CICS for z/OS A transfer to program does not cause a synchronization point unless a PSB is scheduled when the transfer occurs and when one of the following situations is in effect:
  • The receiving program is defined with a different PSB or no PSB at all.
  • The transfer from program specifies the synchOnPgmTransfer="YES" build descriptor option, which is the default value.
  • The transfer is to a non-EGL (externally defined) program.

EGL implements the transfer to program statement with the CICS XCTL command and uses the COMMAREA option of that command to pass the record, after which the record data starts in the first byte of the CICS common area.

The targetName for a transfer to transaction statement must be a CICS transaction ID.

The transfer to transaction statement commits recoverable resources, closes files, closes cursors, and starts a new transaction. EGL implements a transfer to transaction as a CICS START command.

IMS BMP If the receiving program was not generated by EGL or by VisualAge® Generator, EGL uses the OS XCTL macro to implement the transfer. In any case, it is not valid to transfer between a z/OS batch program and an IMS BMP program.
IMS/VS
The following considerations apply:
  • If the initial program in a transaction is a main basic program, the transfer to program statement is not supported where the target program is a main Text UI program.
  • If the initial program in a transaction is a main Text UI program, the transfer to program statement is not supported if the target program is a main basic program that accesses the I/O PCB. Almost any main basic program reads from the I/O PCB, so transfer from a main Text UI program to a main basic program is almost never supported.
  • When you transfer control from an EGL-generated IMS/VS program to an EGL-generated IMS/VS program using either transfer statement, the conversational status of the two programs must be the same: either both must be conversational, or both must be nonconversational. Both programs must specify the same values for the following build descriptor options: spaSize, spaADF, and spaStatusBytePosition.
  • A transfer to program statement is supported on IMS/VS only if the target program was generated by EGL or VisualAge Generator.
  • The targetName for a transfer to transaction statement must be an IMS transaction ID.
The transfer to transaction statement commits recoverable resources, closes files, closes cursors, and starts a new transaction.
Java The transferToProgram and transferToTransaction elements of the linkage options part have no effect when you are transferring control from Java code to Java code.
JSF A transfer to transaction statement is not valid for page handlers (use the forward statement instead).
Rich UI The transfer statement is not supported.
z/OS batch See IMS BMP above

Feedback