Returns program control.

Sintaxe:

Nota:

The LENGTH option is required with C or C++ programs if COMMAREA is specified.

Descrição:

RETURN returns control, in addition to COMMAREA, from an application program to either an application program at the next higher logical level, or CICS.

When the command is issued in a linked-to program that is not at the highest logical level, control passes back to the program that issued the LINK command and resides one logical level higher than the program that is returning control.

If you use RETURN without any parameters, both control and the COMMAREA are handed back to the calling program.

If the task is associated with a terminal, the TRANSID option can be used to specify the transaction identifier for the next transaction that is to be associated with that terminal.
The transaction identifier comes into effect only after the highest logical level has used the RETURN command to give control to CICS, and input is received from the terminal.
Any input that is entered from the terminal, apart from an attention key, is interpreted entirely as data.
You can use TRANSID without COMMAREA when returning from any link level, but you should be aware that it might be overridden on a later RETURN command.
If a RETURN command fails at the highest logical level because of an invalid COMMAREA, the TRANSID becomes null.

When the command is issued in a program at the highest logical level, control returns to CICS.
If the task is associated with a terminal, the TRANSID option can be used to specify the transaction identifier for the next transaction that is to be associated with that terminal; this causes subsequent input that is entered from the terminal to be interpreted entirely as data.
In addition, the COMMAREA option can be used to pass data to the new task that is to be started.
For further information about passing data to other programs, see the TXSeries for Multiplatforms Application Programming Guide.

The LENGTH option specifies the length of the data that is to be passed.
The specified length must not be greater than the length of the data area that is specified in the COMMAREA option; otherwise, the results are unpredictable.
The valid range for the COMMAREA length is 1 through 32767 bytes.
If the length that is provided is outside this range, zero is assumed.
The COMMAREA, LENGTH, and IMMEDIATE 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 transaction that is returned in the TRANSID option.

Opções:

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 the TXSeries for Multiplatforms Application Programming Guide.
• 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 specified communication area 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 that is issued by a program at the highest logical level; that is, a program that is returning control to CICS.
• The specified communication area is passed to the initial program of the next transaction that runs at the terminal.
• You should be aware that if the CanStartATIs attribute that is in the Terminal Definitions (WD) entry is set to yes, the next program is not guaranteed to be part of the transaction that is specified by TRANSID unless the IMMEDIATE option is specified.

IMMEDIATE
• Ensures that the transaction that is specified in the TRANSID option is attached as the next transaction, regardless of any other transactions that are enqueued by ATI for this terminal.
• The next transaction starts immediately and seems to the operator to have been started by terminal data (this option is supported only on Universal Client terminals, not on RPC terminals).
• If the terminal is using bracket protocol, the terminal is also held in brackets.

• This option is valid only on a RETURN command that is issued by a program at the highest logical level; that is a program that is returning control to CICS.

• Nota that in a multi-region environment, use of IMMEDIATE does not affect the transaction definition because that definition is still found in the terminal-owning region (TOR).

INPUTMSG(data-area)
• Specifies data that is to be passed either to another transaction, identified by the TRANSID option, or to a calling program in a multi-program 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 conditions, the data that is in the INPUTMSG data area is passed to the first program to issue a RECEIVE command following the RETURN.
• If the data is passed to a transaction using the TRANSID option, the IMMEDIATE option is used to prevent overwriting of INPUTMSG data by the terminal.
• INPUTMSG with IMMEDIATE is supported only on Universal Client terminals, not on RPC terminals.
• See the TXSeries for Multiplatforms Application Programming Guide for more information and illustrations about the use of INPUTMSG.

INPUTMSGLEN(data-value)
• Specifies a halfword binary value that is to be used with INPUTMSG.

LENGTH(data-value)
• Specifies, as a 16-bit binary value, the length, in bytes, of the communication area.
• If a negative value is supplied, zero is assumed. See LENGTH for more information about using this option.

TRANSID(name)
• Specifies the transaction identifier that is to be used with the next input message that is entered from the terminal with which the task that issued the RETURN command has been associated.
• The specified name can consist of up to four characters and must have been defined as a transaction to CICS.

• If the CanStartATIs attribute in the WD entry is set to yes, a transaction that is started by ATI might be run before the next transaction that is started by terminal input unless the IMMEDIATE option is specified.
• If this happens, and the transaction identifier of the transaction that is started by ATI is the same as that which is specified in the TRANSID option, CICS assumes that the transaction that is started by ATI performs the same function, and erases the name that is specified in the TRANSID option.

• If IMMEDIATE is specified with this option, control is passed to the transaction that is specified in the TRANSID option, in preference to any transactions that are enqueued by ATI.

• If IMMEDIATE is not specified with this option, an ATI-initiated transaction of the same name that is enqueued to the terminal nullifies this option.

• The TRANSID option is not valid if the transaction that is issuing the RETURN command is not associated with a terminal, or is associated with an advanced program-to-program communications (APPC) logical unit. (An APPC conversation allows a program to send data to, and receive data from, a program that is running in a remote system.
• Programming that uses APPC conversations is called Distributed Transaction Programming (DTP).
• For guidance information about DTP, refer to the TXSeries for Multiplatforms Intercommunication Guide.

Condições:

INVREQ
• Occurs for the following conditions, depending on the options that are specified on the RETURN command:
  • A RETURN command with the TRANSID option is issued in a transaction that is not associated with a terminal.
  • A RETURN command with the COMMAREA or IMMEDIATE option is issued in a program that is not at the highest logical level.
  • A RETURN command with the TRANSID option is issued in a transaction that is associated with an APPC logical unit.
  • 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 for an IRC link.
  • A RETURN command is issued with an INPUTMSG option by a program that is invoked by DPL.
• Ação pré-definida: Terminates the task abnormally.

Informações relacionadas:

• LINK
• XCTL
• TXSeries for Multiplatforms Application Programming Guide
• TXSeries for Multiplatforms Administration Reference