The RETURN command is used to end a transaction or pass control to another program or transaction. It is an essential command in CICS COBOL programming, ensuring a smooth handover of control within the system.

The RETURN command can:

• Terminate the current task and return control to CICS.
• Pass control to another transaction or program.
• Pass data using a COMMAREA (Communication Area).
• Schedule another transaction to run after termination.

Syntax -

EXEC CICS RETURN
   [TRANSID(trans-id)]
   [COMMAREA(data-area) LENGTH(data-area-length)]
   [IMMEDIATE]
   [CHANNEL (name)] 
   [INPUTMSG(data-area)]
   [INPUTMSGLEN(data-value)]
   [RESP(response-field)]
   [RESP2(response-field2)]
END-EXEC.

• TRANSID(trans-id) - Specifies the next transaction ID to start after the return. If omitted, the task ends.
• COMMAREA(data-area) - Specifies a communication area available to the next program that receives control. The valid range for the COMMAREA length is 0 through 32767 bytes. If the length provided is outside range, the LENGERR condition occurs.
• LENGTH(data-area-length) - Specifies the length of the COMMAREA in bytes. If any negative value provided, ZERO assumed as length.
• IMMEDIATE - used to trigger the next transaction specified with TRANSID immediately.
• CHANNEL (name) - Specifies the channel name (1–16 characters) to be available to the next program that receives control.
• INPUTMSG(data-area) - Specifies the data to pass to the transaction in the TRANSID option or call a program in a multi-region environment.
• INPUTMSGLEN(data-value) - Specifies the length of the INPUTMSG. (Declaration: PIC S9(4) USAGE BINARY).
• RESP(response-variable) - Optional. It captures the response code of the RECEIVE MAP operation and used to check if the command executed successfully or encountered an error.
• RESP2(response2-variable) - Optional. It captures the response2 code of the RECEIVE MAP operation when the error occured.

Short Examples -

Scenario1 - Simple RETURN (End the transaction)

EXEC CICS RETURN END-EXEC.

If no parameters are provided, CICS simply ends the current task and returns control to CICS.

Scenario2 - RETURN with TRANSID (Schedule Next Transaction)

EXEC CICS RETURN
	TRANSID('TRX1')
END-EXEC.

It ends the current task but schedules another transaction (TRX1) to start immediately.

Scenario3 - RETURN with COMMAREA (Pass Data to Next Transaction)

EXEC CICS RETURN
	TRANSID('TRX2')
	COMMAREA(WS-DATA)
	LENGTH(100)
END-EXEC.

It passes a data area (communication area) to the next invocation of the transaction.

Scenario4 - RETURN with RESP (Error Handling)

EXEC CICS RETURN
	RESP(WS-RESP-CODE)
END-EXEC.

IF WS-RESP-CODE NOT = 0
	DISPLAY 'ERROR OCCURRED DURING RETURN'.

Using RESP, we can handle potential errors in RETURN execution.

Error Conditions -

Eror Condition	RESP	RESP2	Reason
INVREQ	16	1	The program issuing RETURN command with the TRANSID option is not associated with a terminal.
	16	2	A RETURN command with the CHANNEL, COMMAREA, or IMMEDIATE option is issued by a program that is not at the highest logical level.
	16	4	A RETURN command with the TRANSID option is issued in the program associated with an APPC logical unit.
	16	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.
	16	200	A RETURN command with an INPUTMSG option invoked by a program invoked by DPL.
	16	203	The CHANNEL option was specified, but the remote region which got the control does not support channels.
LENGERR	22	11	The COMMAREA length is less than 0 or greater than 32763.
	22	26	The COMMAREA ADDRESS passed was zero, but the COMMAREA length was non-zero.
	22	27	The INPUTMSG LENGTH was less than 0 or greater than 32767.
CHANNELERR	122	1	The CHANNEL name contains an illegal character or combination of characters.

---