Return program control.
RETURN >>-RETURN-------------------------------------------------------> >--+-------------------------------------------------------------------------------+--> '-TRANSID(name)--+---------------------------------------------+--+-----------+-' +-COMMAREA(data-area)--+--------------------+-+ '-IMMEDIATE-' | '-LENGTH(data-value)-' | '-CHANNEL(name)-------------------------------' >--+--------------------------------------------------+---------> '-INPUTMSG(data-area)--+-------------------------+-' '-INPUTMSGLEN(data-value)-' >--+-------------+--------------------------------------------->< '-ENDACTIVITY-'
Conditions: CHANNELERR, INVREQ, LENGERR
This command is threadsafe.
RETURN returns control from an application program either to an application program at the next higher logical level, or to CICS®.
When returning a communications area (COMMAREA), the LENGTH option specifies the length of the data to be passed. The LENGTH value being passed must not be greater than the length of the data area specified in the COMMAREA option. If it is, the results are unpredictable and may result in a LENGERR condition, as described in the section about passing data to other programs in Passing data to other programs .
The valid range for the COMMAREA length is 0 through 32 763 bytes. If the length provided is outside this range, the LENGERR condition occurs.
The COMMAREA, IMMEDIATE, and CHANNEL options can be used only when the RETURN command is returning control to CICS; otherwise, the INVREQ condition occurs.
No resource security checking occurs on the RETURN TRANSID command. However, transaction security checking is still available when CICS attaches the returned transaction.
For information about the use of this command in the CICS BTS environment, see the CICS Business Transaction Services manual.
Channel names are always in EBCDIC. The allowable set of characters for channel names, listed above, includes some characters that do not have the same representation in all EBCDIC code pages. We therefore recommend that, if a channel is to be shipped between regions (that is, if the transaction named on the TRANSID option is remote), the characters used in naming it should be restricted to A-Z a-z 0-9 & : = , ; < > . - and _.
This option is valid only on a RETURN command issued by a program at the highest logical level; that is, a program returning control to CICS.
The communication area specified is passed to the next program that runs at the terminal. To ensure that the communication area is passed to the correct program, include the IMMEDIATE option.
This option is valid only on a RETURN command issued by a program at the highest logical level, that is, a program returning control to CICS.
If there are no user events in the activity's event pool, the activity completes normally.
For information about BTS in general and the ENDACTIVITY option in particular, see Activity completion .
This option is ignored outside the CICS BTS environment.
Note that in a multi region environment, using IMMEDIATE does not affect the transaction definition as this is still found in the terminal-owning region (TOR).
In all cases, the data in the INPUTMSG data area is passed to the first program to issue a RECEIVE command following the RETURN.
See INPUTMSG for more information and illustrations about the use of INPUTMSG.
If TRANSID is specified for a program running on a terminal that is defined with a permanent transaction ID, the terminal's permanent transaction is initiated next rather than the transaction specified on the RETURN.
If you specify a TRANSID of binary zeros, the transaction identifier for the next program to be associated with the terminal may be determined from subsequent input from the terminal. Issuing a RETURN with a TRANSID of binary zeros and a COMMAREA can cause unpredictable results if the next transaction is not coded to handle the COMMAREA or if it receives a COMMAREA not intended for it.
If you specify TRANSID on a program that is not at the highest level, and there is a subsequent error on COMMAREA, INPUTMSG, or CHANNEL on the final RETURN, the TRANSID is cleared.
The next transaction identifier is also cleared on an abnormal termination of the transaction.
If IMMEDIATE is specified with this option, control is passed to the transaction specified in the TRANSID option in preference to any transactions enqueued by ATI.
If IMMEDIATE is not specified with this option, an ATI initiated transaction of the same name enqueued to the terminal nullifies this option.
This option is not valid if the transaction issuing the RETURN command is not associated with a terminal, or is associated with an APPC logical unit.
Default action: terminate the task abnormally.
Default action: terminate the task abnormally.