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 the CICS Application
Programming Guide.
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 the CICS Business Transaction Services manual.
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 the CICS Application Programming Guide 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.