RETURN

Description

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.

Options

CHANNEL(name)

specifies the name (1–16 characters) of a channel that is to be made available to the next program that receives control. The acceptable characters are A-Z a-z 0-9 $ @ # / % & ? ! : | " = ¬ , ; < > . - and _. Leading and embedded blank characters are not permitted. If the name supplied is less than 16 characters, it is padded with trailing blanks up to 16 characters. If the channel does not exist, it is created. This new channel remains in scope until the link level changes. For more information about channel scope, see The scope of a channel.

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 _.

You can specify the channel name DFHTRANSACTION to use a transaction channel. A transaction channel does not go out of scope when the link level changes: it is always accessible in the transaction. For more information, see Channels and containers.

The program that issues the RETURN command can do one of the following:

• Have already created the channel by means of one or more PUT CONTAINER CHANNEL commands
• Specify its current channel, by name
• Name a non-existent channel, in which case a new, empty, channel is created

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.

COMMAREA(data-area)

specifies a communication area that is to be made available to the next program that receives control. In a COBOL receiving program, you must give this data area the name DFHCOMMAREA. See Sharing data across transactions for more information about the CICS COMMAREA. Because the data area is freed before the next program starts, a copy of the data area is created and a pointer to the copy is passed.

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.

ENDACTIVITY

This option is for use by programs that implement CICS business transaction services (BTS) activities. It specifies that the current activity is completing, and is not to be reactivated.

If there are no user events in the activity's event pool, the activity completes normally.

If there are user events (fired or unfired) in the activity's event pool:

• If one or more of the events are activity completion events, the activity abends. Trying to force an activity to complete before it has dealt with one or more of its child activities is a program logic error.
• If none of the events are activity completion events, the events are deleted and 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.

IMMEDIATE

ensures that the transaction specified in the TRANSID option is attached as the next transaction regardless of any other transactions enqueued by ATI for this terminal. The next transaction starts immediately and appears to the operator as having been started by terminal data. If the terminal is using bracket protocol, the terminal is also held in bracket. 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.

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).

INPUTMSG(data-area)

specifies data to be passed either to another transaction, identified by the TRANSID option, or to a calling program in a multiprogram transaction. You can also use INPUTMSG when returning control to CICS from a user-written dynamic transaction routing program, when you might want to modify the initial input.

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.

INPUTMSGLEN(data-value)

specifies a halfword binary value to be used with INPUTMSG.

LENGTH(data-value)

specifies a halfword binary value that is the length in bytes of the COMMAREA. For a description of a safe upper limit, see Translation considerations: LENGTH options in EXEC CICS commands.

TRANSID(name)

specifies the transaction identifier (1–4 characters) to be used with the next input message entered from the terminal with which the task that issued the RETURN command has been associated. The specified name must have been defined as a transaction to CICS.

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.

Conditions

122 CHANNELERR

RESP2 values:

1

The name specified on the CHANNEL option contains an illegal character or combination of characters.

16 INVREQ

RESP2 values:

1

A RETURN command with the TRANSID option is issued in a program that is not associated with a terminal.

2

A RETURN command with the CHANNEL, COMMAREA, or IMMEDIATE option is issued by a program that is not at the highest logical level.

4

A RETURN command with the TRANSID option is issued in a program that is associated with an APPC logical unit.

8

A RETURN command with the INPUTMSG option is issued for a program that is not associated with a terminal, or that is associated with an APPC logical unit, or an IRC session.

30

PG domain not initialized. Parameters are not allowed on the EXEC RETURN statement in first stage PLT programs.

200

A RETURN command is issued with an INPUTMSG option by a program invoked by DPL.

203

The CHANNEL option was specified but the remote region to which control is returned does not support channels.

Default action: terminate the task abnormally.

22 LENGERR

RESP2 values:

11

The COMMAREA length is less than 0 or greater than 32763.

26

The COMMAREA ADDRESS passed was zero, but the commarea length was non-zero.

27

The INPUTMSG LENGTH was less than 0 or greater than 32767.

Default action: terminate the task abnormally.