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 transfer statement is not valid in a called program.

The transfer statement is of two kinds:
  • A transfer to transaction statement can commit or roll back recoverable resources.
  • A transfer to program statement does not cause a synchronization point, does not close files or cursors, and does not commit or roll back recoverable resources. The source and target programs must be in the same run unit.

For details about the runtime behavior, see the Compatibility section in this topic.

The program that is the target 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 next section.

Syntax


Syntax diagram for the transfer statement
targetName
The main program or transaction that receives control. The name can be a part reference without quotation marks, a literal string in quotation marks, a constant, or sysVar.transferName or another variable.
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
The following properties are supported:
isExternal
A Boolean property:
  • NO, the default, indicates that an element in the linkage part specifies whether an external program is the target of the transfer. This setting is recommended because placing a value in the linkage part is more flexible; the setting is not embedded in the code.

    If you are coding a transfer to transaction statement, the linkage part element is transferToTransaction and the attribute is externallyDefined. If you are coding a transfer to program statement, the linkage part element is transferToProgram and the attribute is linkType.

  • YES indicates that a non-EGL-generated program is the target of the transfer.
linkageKey
A string that references the transferToProgram or transferToTransaction element in a linkage options part. The string matches the toPgm attribute in that element. For additional details, see linkageKey.

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 that 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 in a given transaction An EGL CICS® COBOL program in the same transaction
A non-EGL CICS® COBOL program in the same transaction
CICS® transaction, written in any language CICS® transaction, written in any language
An EGL-generated IMS/VS program in a given transaction An EGL-generated IMS/VS program in the same transaction
IMS™ transaction, written in any language IMS™ transaction, written in any language
An EGL 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 transfer from EGL-generated Java™ code to non-EGL-generated Java™ code, use one of the following mechanisms: an EGL external type, a Java™ access function, or vgLib.startTransaction.

EGL supports the use of a deferred switch, such that one transaction shows a form and, when the user submits that form, another transaction is invoked. For details, see show.

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. 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.

Transfers between a z/OS® batch program and an IMS™ BMP program is not supported.

EGL uses the OS XCTL macro to run a transfer from an IMS™ BMP to a program that was not generated by EGL or VisualAge® Generator.

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.
  • 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. The data starts in the first byte of the CICS® common area, and the maximum record length is 32763.

A transfer to transaction statement commits recoverable resources, closes files, closes cursors, and starts a new transaction. The targetName in this case is a CICS® transaction ID. EGL implements the statement with the CICS® START command and uses the COMMAREA option of that command to pass the record. The record data starts in the first byte of the CICS® common area, and the maximum record length is 32763.
IMS™ BMP See the Batch environments row.
IMS/VS
  • 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. Because most main basic programs read from the I/O PCB, transfers from a main Text UI program to a main basic program are rarely supported.
  • When you use a transfer statement to transfer control from an EGL-generated IMS/VS program to an EGL-generated IMS/VS program, the conversational status of both programs must be the same: either conversational or 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 can provide the package name for the receiving program if the name is not provided through import statements or explicitly through code package names. Transfer to a non-EGL-generated program is not supported.
Rich UI The transfer statement is not supported.
z/OS® batch See the Batch environments row.