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.
EXEC CICS XCTL('progname') COMMAREA(record)
LENGTH(length of record)
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.
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.
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.
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.
The following sections describe the differences in the transfer to transaction statement depending on the value you specify for the genReturnImmediate build descriptor option.
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.
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.
EXEC CICS RETURN TRANSID('transid') COMMAREA(name of COMMAREA)
LENGTH(length of COMMAREA)
IMMEDIATE
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.
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.
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.
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.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.
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.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.
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.
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.
myCHAR = x"00000000";
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.
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.
EXEC CICS RETRIEVE INTO (workRecord) LENGTH(length of workRecord)
RTERMID(userRtermid)