transfer

The EGL transfer statement gives control from one main program to another, ends the transferring program, and optionally passes a record whose data is accepted into the receiving program's input record. You cannot use a transfer statement in a called program.

Your program can transfer control by a statement of the form transfer to a transaction or by a statement of the form transfer to a program:
  • A transfer to a transaction acts as follows--
    • In a main program that runs on IMS/VS or on CICS® for z/OS®, this statement commits recoverable resources, closes files, closes cursors, and starts a new transaction.
    • In a program that runs as a z/OS main batch program, as an IMS™ BMP, or as a Java™ main text or main batch program, the statement starts a program in the same run unit, but pre-transfer behavior depends on the setting of build descriptor option synchOnTrxTransfer--
      • If the value of synchOnTrxTransfer is NO (the default), the transfer statement does not close or commit resources, which are available to the invoked program.
      • If the value of synchOnTrxTransfer is YES, the transfer statement commits recoverable resources, closes files, and closes cursors.
    • In a program of type VGWebTransaction, a transfer to a transaction is not valid; instead, use one of the following statements:
      • A transfer statement of the form transfer to a program (for transferring to another VGWebTransaction program or to a main batch program); or
      • A forward statement (for forwarding control to a URL).
    • In a PageHandler, a transfer to a transaction is not valid; use the forward statement instead.
  • A transfer to a program starts a program in the same run unit. With exceptions that are described later and that relate to DL/I processing, a transfer to a program does not cause a synchronization point: does not close files or cursors and does not commit or rollback recoverable resources.
    A transfer to a program is available in programs of type VGWebTransaction (on any system) and in any main COBOL program:
    • On CICS for z/OS, the transfer 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 begins by scheduling a different PSB or no PSB at all; or
      • The receiving program begins by scheduling the same PSB, but the build descriptor option synchOnPgmTransfer is set to YES, which is the default value.

      EGL implements the 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.

    • For z/OS batch and IMS BMP programs, a transfer to a program is valid. If the receiving program was generated neither by EGL nor 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.
    • For IMS/VS programs, a transfer to a program is supported only if the receiving program was generated by EGL or VisualAge Generator.

      If the initial program in a transaction is a main batch program, transfer to a main transaction program is not supported. If the initial program is a main transaction, transfer is not valid to a main batch program that accesses the I/O PCB.

The linkage options part, transferLink element has no effect when you are transferring control from Java code to Java code, but is meaningful otherwise.

If you are transferring control code to code that was not written with EGL or VisualAge Generator, it is recommended that you set the linkage options part, transferLink element as follows:
  • If you are transferring to a transaction, set the externallyDefined property to yes.
  • If you are transferring to a program, set the linkType property to externallyDefined

If you are running in VisualAge Generator compatibility mode, you can specify the option externallyDefined in the transfer statement, as occurs for programs migrated from VisualAge Generator; but it is recommended that you set the equivalent value in the linkage options part instead. For details on VisualAge Generator compatibility mode, see Compatibility with VisualAge Generator.


Syntax diagram for the transfer statement
program targetName (the default)
The program that receives control. If you are generating for COBOL and specify a program name of more than 8 characters, the program name is truncated to 8 characters with character substitutions (if needed), as described in Name aliasing.
transaction targetName
The transaction or program that receives control, as described earlier.
sysVar.transferName
A system function that contains a target name that can be set at run time. For details, see sysVar.transferName.
passing recordName
A record that is received as the input record in the target program. The passed record may 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 of type basicRecord.
externallyDefined
Not recommended for new development, as described earlier.

Related reference
transferName

Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.