RETURN
Summary
Returns the program control back. RETURN returns control from an application program either to an application program at the next higher logical level or to CICS.
If the program is triggered from a LINK command, then control returns to the calling program. If the program is directly triggered from Transaction, control returns to the CICS region.
If the RETURN executed without any parameters, both control and COMMAREA are handed over to calling program. If no logical higher level existed, control returns to CICS.
If the RETURN has coded with TRANSID parameter, the corresponding program for transaction-id starts getting executed. While returning a communications area (COMMAREA), the LENGTH option specifies with the length of the data to be passed.
The LENGTH value 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.
The valid range for the COMMAREA length is 0 through 32763 bytes. If the length provided is outside this range, the LENGERR condition occurs.
Syntax -
The COMMAREA, IMMEDIATE and CHANNEL options can be used only when the RETURN command is returning control to CICS. Otherwise, the INVREQ condition occurs.
Parameters -
TRANSID(tran-name) -
Specifies the transaction identifier (1-4 characters) that needs to start execution immediately. The specified transaction should have been defined in CICS region.
The TRANSID is not valid with RETURN when the program is communicating with the programs that are existed in remote region (Advanced program to program communications – APPC). APPC communications called as Distributed Transaction Programming(DTP).
COMMAREA(data-area) -
Specifies a communication area available to the next program that receives control. In a COBOL program, the data area should define under DFHCOMMAREA.
The COMMAREA parameter is valid when the control is transferring to the next highest logical level.For the above case, there is no need to specify the COMMAREA along with RETURN command and it automatically sends the COMMAREA along with control.
The LENGTH value 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.
The valid range for the COMMAREA length is 0 through 32763 bytes. If the length provided is outside this range, the LENGERR condition occurs.
IMMEDIATE -
Ensures that the transaction in the TRANSID option is attached as the next transaction regardless of any other transactions enqueued by ATI for the current terminal.
The next transaction starts immediately and appears to the operator as having been started by terminal data. IMMEDIATE option can be used to trigger the next transaction specified with TRANSID immediately.
If IMMEDIATE option not specified along with RETURN, then it will put the current program in ATI queue and start executing the programs as per ATI queue feed. 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.
LENGTH(data-value) -
Specifies the length of the COMMAREA in bytes. LENGTH field is of 4 bytes. If any negative value provided, ZERO assumed as length.
INPUTMSG(data-area) -
Specifies the data to pass to the transaction in TRANSID option or calling a program in multi region environment.
INPUTMSGLEN(data-value) -
Specifies the length of the INPUTMSG. INPUTMSGLEN is a half word binary value (Declaration: PIC S9(4) USAGE BINARY).
CHANNEL(name) -
Specifies the channel name (1–16 characters) that is to be made available to the next program that receives control. The acceptable characters for channel name 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.
This option is valid only on a RETURN command issued by a program at the highest logical level (program returning control to CICS).
Error Conditions -
Below are the list of error conditions may occur in combination. If more than one occurs, only the first is passed to the application program.
| Error Condition | RESP2, Description & Solution | System Action |
|---|---|---|
| 122 CHANNELERR | 1 - The CHANNEL name contains an illegal character or combination of characters. Solution -Change the application program/table and remove invalid characters in the channel name. | Task abnormally terminated |
| 16 INVREQ | 1 - The program issuing RETURN command with the TRANSID option is not associated with a terminal. Solution -Use the transaction that is associated with the terminal (local transaction) and do not use remote transactions. 2 - A RETURN command with the CHANNEL, COMMAREA, or IMMEDIATE option is issued by a program that is not at the highest logical level. Solution -CHANNEL, COMMAREA or IMMEDIATE options should be used in the program that are at highest logical level. Modify the program to remove the options. 4 - A RETURN command with the TRANSID option is issued in the program associated with an APPC logical unit. Solution -The programs associated with APPC logical unit should not use in RETURN command. Modify the program to remove it. 8 - A RETURN command with the INPUTMSG option is issued in the program that is not associated with a terminal, or that is associated with an APPC logical unit, or an IRC session. Solution -RETURN with INPUTMSG option should be issued from a program that is associated with local terminal or APPC logical unit or an IRC session. Modify the program to remove it. 200 - A RETURN command with an INPUTMSG option invoked by a program invoked by DPL. Solution -RETURN with INPUTMSG should not be coded in the program invoked by DPL. Modify the application program to remove it. 203 - The CHANNEL option was specified, but the remote region which got the control does not support channels. Solution -The remote region specified with SYSID doesn’t support channels. Modify application program to remove the CHANNEL option if the specified region is correct or modify the remote region name if it is wrongly specified. | Task abnormally terminated |
| 22 LENGERR | 11 - The COMMAREA length is less than 0 or greater than 32763. Solution -Debug the application program to verify the COMMAREA length. If the COMMAREA length specified is less than zero, modify it according to the data. If the COMMAREA length is greater than 32763, use other ways to pass the data from program to program. 26 - The COMMAREA ADDRESS passed was zero, but the COMMAREA length was non-zero. Solution -Debug the application program and correct the COMMAREA ADDRESS or COMMAREA length. 27 - The INPUTMSG LENGTH was less than 0 or greater than 32767. Solution -Debug the application program to verify the INPUTMSG length. If the INPUTMSG length specified is less than zero, modify it according to the data. If the INPUTMSG length is greater than 32767, use other ways to pass the data from program to program. | Task abnormally terminated |