Transferring control in CICS® environments

Transfers in the CICS® environment are supported in the following ways:

A transfer to program statement is implemented as a CICS® XCTL command.
A transfer to transaction statement is implemented as one of the following commands:
- a CICS® START command if the genReturnImmediate build descriptor option is set to NO
- a CICS® RETURN IMMEDIATE command if the genReturnImmediate build descriptor option is set to YES
Setting genReturnImmediate to YES is supported only for CICS® for z/OS® systems
A show statement with an associated form and a returning clause is implemented as a CICS® RETURN TRANSID command.

Transfer to program

A transfer to program statement can specify an optional record. A transfer to program statement continues the same CICS® transaction. The following sections provide a more detailed description of how a transfer to program statement works in the CICS® environment.

Transfer from an EGL program to an EGL program using transfer to program

The EGL program immediately transfers control to the target program using a CICS® XCTL command. A record, if specified, is passed in the COMMAREA. A CICS® SYNCPOINT occurs on a transfer to program statement if either of the following situations occurs:

You set the synchOnPgmTransfer build descriptor option to YES and a PSB is scheduled.
You set the synchOnPgmTransfer build descriptor option to NO for the originating program and the originating program had scheduled a PSB and different default PSB names were specified for the PSB records for the two programs.

Otherwise, no CICS® SYNCPOINT occurs. The following example shows the command that EGL generates to transfer program control:

EXEC CICS XCTL('progname') COMMAREA(record)
                          LENGTH(length of record)

Transfer from an EGL program to a non-EGL program using transfer to program

The EGL program immediately transfers control to the target non-EGL program by issuing a CICS® XCTL to the program name specified in the transfer to program statement. A record, if specified, is passed in the COMMAREA. A CICS® SYNCPOINT occurs on a transfer to program statement if a PSB is scheduled.

A transfer to program from an EGL program to a non-EGL program is implemented in the same way as a transfer from one EGL program to another. You must either specify isExternal = YES on the transfer to program statement or specify fromPgm, toPgm, and linkType = EXTERNALLYDEFINED in the transferToProgram element in the linkage options part used during generation. The isExternal property or the EXTERNALLYDEFINED link type indicate that all resources allocated by Rational® COBOL Runtime for zSeries® are released. The non-EGL program receives data in the COMMAREA.

Transfer from a non-EGL program to an EGL program using CICS® XCTL

The originating program issues a CICS® XCTL command to transfer to the target EGL program. A record can be passed and will be used to initialize the record identified by the inputRecord property of the EGL program.

The originating program must be defined as a main program, and the target program name is the only required parameter. That parameter must point to a valid EGL program name.

EXEC CICS XCTL ('progname') COMMAREA(record)
                           LENGTH (length of record)

If the target program is segmented, be sure that before the target program issues a converse statement, it sets sysVar.transactionID to a transaction code associated with the target program in a CICS® TRANSACTION entry. Otherwise, when the input from the terminal is received, the default value in sysVar.transactionID (the current transaction code) causes the non-EGL program to be restarted instead of the target EGL program.

You can set sysVar.transactionID to the proper transaction code by doing one of the following:

Specifying the transaction code as the restartTransactionID build descriptor option.
Moving the transaction code to sysVar.transactionID within the program before the first converse statement.

Transfer to transaction

A transfer to transaction statement can specify an optional record. This transfer to transaction statement causes a new CICS® transaction to be invoked. Recoverable resources are committed as part of the transfer process. The new transaction is scheduled as soon as the first transaction ends. The following sections provide a more detailed description of how a transfer to transaction statement works in the CICS® environment.

Transfer from an EGL program to an EGL program using transfer to transaction

The following sections describe the differences in the transfer to transaction statement depending on the value you specify for the genReturnImmediate build descriptor option.

transfer to transaction with genReturnImmediate="NO"

If you set the genReturnImmediate build descriptor option to NO, the originating program issues an EXEC CICS® START command for the target transaction. If a record is specified in the transfer to transaction statement, the record is passed as FROM data on the EXEC CICS® START command; otherwise, the FROM and LENGTH parameters are not used.

The following example shows the format of the START command that EGL generates if a record is specified in the transfer to transaction statement:

EXEC CICS START TRANSID('transid') FROM(record) 
                                 LENGTH(length of record) 
                                 TERMID(current-terminal)

EGL always includes the TERMID option of the CICS® START command if the transfer to transaction is issued from a main text UI program. The transaction is not invoked unless the terminal is in TRANSCEIVE status in the CICS® TCT.

A START command refers to a CICS® transaction ID that is 4 characters or less. CICS® starts the new CICS® transaction on the same terminal as the originating program if the terminal is not currently in TRANSACTION status.

The started transaction can start a non-EGL program or an EGL program defined as a main text UI program. After starting the new transaction, the program issuing the transfer to transaction statement ends.

transfer to transaction with genReturnImmediate="YES"

If you set the genReturnImmediate build descriptor option to YES, the originating program issues an EXEC CICS® RETURN IMMEDIATE command for the target program. If a record is specified, the record is passed in the 11th through nth bytes of the COMMAREA. The first 10 bytes are binary zeros indicating that this is a transfer to transaction statement passing a record. The following example shows the EXEC CICS® RETURN IMMEDIATE command that EGL generates if a record is specified on the transfer to transaction statement.

EXEC CICS RETURN TRANSID('transid') COMMAREA(name of COMMAREA)
                                 LENGTH(length of COMMAREA)
                                 IMMEDIATE

Transfer from an EGL program to a non-EGL program using transfer to transaction

A transfer to transaction statement from an EGL program to a non-EGL program is implemented in different ways depending on the genReturnImmediate build descriptor option. You must either specify isExternal = YES on the transfer to transaction statement or specify the toPgm and externallyDefined = YES in the transferToTransaction element in the linkage options part used during generation. You can use the isExternal or the externallyDefined option to provide documentation that this is a transfer to a non-EGL program. Because transfer to transaction starts a new CICS® transaction, a CICS® SYNCPOINT occurs as a result of the transfer statement.

If the genReturnImmediate build descriptor option is set to NO, the transfer to transaction statement is implemented as an EXEC CICS® START command. The record passed when using a transfer to transaction statement is put into CICS® temporary storage. The non-EGL target program must retrieve the record into its own data area. CICS® also passes the length of the retrieved data to the program. This length is zero if no record is passed. The following CICS® command retrieves the passed record:

EXEC CICS RETRIEVE INTO(myWorkingStorageArea)
                 LENGTH(workLength)

Be sure to put the length of myWorkingStorageArea into workLength before executing the RETRIEVE command.

If the genReturnImmediate build descriptor option is set to YES, then the transfer to transaction statement is implemented as an EXEC CICS® RETURN IMMEDIATE. The first 10 bytes of the COMMAREA received by the target program is binary zeros. If a record is specified in the transfer to transaction statement, that record is found in the COMMAREA starting at the 11th byte.

Transfer from a non-EGL program to an EGL program using CICS® START

The program can issue a CICS® START command for the CICS® transaction ID associated with an EGL program. The terminal must be specified in the TERMID option of the CICS® START command if a main text UI program is being started. The transaction is not invoked unless the terminal is in TRANSCEIVE status in the CICS® TCT. A record can be passed by using the FROM option of the START command. If a record is passed, it is used to initialize the record identified by the inputRecord property for the EGL program. The target EGL program can specify a form in its inputForm property that will be displayed automatically when the program loads.

The example below shows the format of the START command that can be used when passing a record to the EGL program:

EXEC CICS START TRANSID('transid') FROM(record)
                                 LENGTH(length of record)
                                 TERMID(current-terminal)

If the originating program uses the EXEC CICS® START command, you can set the genReturnImmediate build descriptor option to either YES or NO when you generate the target program.

Transfer from a non-EGL program to an EGL program using CICS® RETURN IMMEDIATE

If the EGL program was generated with the genReturnImmediate build descriptor option set to YES, the originating (non-EGL) program can issue a CICS® RETURN IMMEDIATE command for the CICS® transaction. A record can be passed in the COMMAREA and must start in the 11th byte. The first 10 bytes must be binary zeros. If a record is passed, it is used to initialize the record identified by the inputRecord property for the EGL program. The target EGL program can specify a form in its inputForm property that will be displayed automatically when the program loads.

The following example shows the format of the CICS® RETURN IMMEDIATE when you pass a record to the EGL program:

EXEC CICS RETURN TRANSID('transid')
                 COMMAREA(10 bytes of low-values + record)
                 LENGTH(10 + length of record)
                 IMMEDIATE

If you use CICS® RETURN IMMEDIATE to transfer to an EGL program, you must set the genReturnImmediate build descriptor option to YES when generating the EGL program to be started.

Transfer using show

If you want to specify a form name in a transfer of control, you must use the show statement. When you specify a form name with a show statement that includes a returning clause, the originating program displays the form and returns to CICS®. The CICS® RETURN command specifies the target transaction ID from the show statement as the next transaction to be scheduled when the program user responds to the screen. The target transaction must be associated with an EGL program. The target program must have a form specified in its inputForm property, and this form must be identical to the form specified in the show statement. The target transaction receives control after the user presses an event key.

If a record is specified in the show statement, the record is received in the COMMAREA by the target transaction and is used to initialize the record specified by the inputRecord property of the target program.

You cannot transfer to a non-EGL program using a show statement.

Using asynchronous tasks

You can use the EGL system function vgLib.startTransaction() to start an asynchronous transaction. You can write the program that is started for the asynchronous transaction in either EGL or non-EGL. You can also write a non-EGL program to start an EGL program asynchronously. The following sections describe the techniques.

Starting asynchronous tasks from an EGL program

An EGL program starts an asynchronous task with a vgLib.startTransaction() statement that generates a CICS® START command. For example, the vgLib.startTransaction() function might look like:

vgLib.startTransaction(requestRecord, prID, termID);

The default behavior is to start a program that resides in the same CICS® region; however, you can specify a different region by defining the asynchLink element in the linkage options part that is used when you generate the program that calls the vgLib.startTransaction() system function. The prID and termID parameters are ignored if the target transaction is started on a remote system.

The requestRecord must be in the following format:

Bytes 1-2 of the record must be a SMALLINT field that is set to the length of the data portion of the record plus 10.
Bytes 3-6 must contain the CICS® transaction ID.
Bytes 7-10 must be blank.
The data portion of the requestRecord starts in byte 11. Only the actual data portion of the record is passed in the FROM option of the CICS® START command. If the started transaction is associated with an EGL program, that EGL program receives the data portion of the requestRecord into the record specified by the inputRecord property.

Depending on the value of the termID parameter, EGL issues the CICS® START command with or without an associated device:

If termID is not specified, EGL associates the current terminal with the target transaction; specifically, EGL assigns the current terminal identifier to the TERMID option in the CICS® START command.
If termID is specified and its value is not binary zeros, EGL associates the specified device (terminal or printer) with the target transaction; specifically, EGL assigns the value of termID to the TERMID option in the CICS® START command but does not include the RTERMID option. Results are not predictable if the value in termID is the CICS® terminal ID that is associated with the current transaction. To end the current transaction and start a new transaction at the current terminal, use the transfer to transaction or show statement rather than the vgLib.startTransaction() system function.
If the value of the termID parameter is binary zeros, EGL associates no terminal with the target transaction; specifically, EGL assigns the value of the prID parameter to the RTERMID option in the CICS® START command but does not include the TERMID option. In addition, if you set the build descriptor option printDestination to TERMINALID when you generate the started EGL program, the prID parameter is the printer ID that is used to initialize the converseVar.printerAssociation system variable in the target transaction. To set the termID CHAR field to binary zeros, use an assignment statement containing a hex literal for 4 bytes of binary zeros, as in the following example:
```
myCHAR = x"00000000";
```
The target transaction must have a CICS® TRANSACTION entry.
If the first program in the started transaction is a non-EGL program, it must issue a CICS® RETRIEVE to get the passed work area and terminal information. For more information, see Retrieving data for a started task in a non-EGL program.

Starting an EGL program asynchronously from a non-EGL program

To start an asynchronous transaction that is associated with an EGL program from a non-EGL program, issue a CICS® START command like the following:

EXEC CICS START ('transid') FROM(workRecord) LENGTH(length of workRecord)
                TERMID(destTermid)
                RTERMID(asyncPrintDest)

The started EGL program must be a main basic program. It uses the workRecord to initialize the record specified by the inputRecord property of the EGL program.

The RTERMID and TERMID options have the following meanings when starting asynchronous tasks:

If you want to start an asynchronous task without an associated CICS® terminal ID, then omit the TERMID keyword from the START command.
If you want to start a task with an associated terminal ID, then the value you specify in the TERMID option should be a valid CICS® terminal ID. The results are not predictable if you specify the terminal ID that is associated with the current transaction.
The value in the RTERMID option should be the print destination for the started EGL program. If you set the build descriptor option printDestination to TERMINALID when you generate the started EGL program, the RTERMID value is used to initialize converseVar.printerAssociation in the started EGL program.

Retrieving data for a started task in a non-EGL program

Non-EGL programs started with the vgLib.startTransaction() system function must always include the RTERMID option on the CICS® RETRIEVE command that is used to retrieve the passed record, even though the value might be all zeros.

The program can receive the data that was passed by doing the following:

EXEC CICS RETRIEVE INTO (workRecord) LENGTH(length of workRecord)
                         RTERMID(userRtermid)

The options for the CICS® RETRIEVE command have the following meanings when the non-EGL program is started as a result of vgLib.startTransaction():

workRecord must be defined to match the data portion of the requestRecord that you used in the vgLib.startTransaction() system function (from byte 11 through the end of the requestRecord).
Be sure to put the length of workRecord into LENGTH.
If the RTERMID option contains 4 bytes of binary zeros, it should be ignored. If the RTERMID option is not 4 bytes of binary zeros, it contains the printer (prID parameter) specified for the vgLib.startTransaction() function.