What is RETURN command - IBM Mainframe

The RETURN command when issued by the application program will return program control to either CICS or the next higher logical level application program. There is no resource security checking on the RETURN TRANSID command, but the transaction security checking is still available when CICS attaches the returned transaction. The syntax of RETURN is:

syntax of RETURN

  • COMMAREA (dataarea) - Identifies the communication area, which is to be made available to the invoking program by passing a pointer of the data area. In the COBOL receiving program, the data area is in the DFHCOMMAREA. The data area is freed by CICS prior to the next program starting, so a copy of the data area is created and a pointer to the copy is passed. To ensure the communication area is passed to the next program that runs at the terminal you can include the IMMEDIATE option. This option is only valid when the program (at the highest logical level) is returning control to CICS.
  • IMMEDIATE - Option when used will ensure the next transaction contained in the TRANSID option is attached to the terminal regardless of any transactions queued up for the terminal by ATI. The next transaction begins immediately and to the terminal operator appears as having been started by the terminal data. When bracket protocol is being used, the terminal is also held in the bracket terminal, include the IMMEDIATE option. This option is only valid when the program (at the highest logical level) is returning control to CICS.
  • INPUTMSG (dataarea) - Identifies data to be passed to another transaction, which is specified in the TRANSID option or to the calling program in a multi-program transaction. The application program can 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 contained in the INPUTMSG option is passed to the first program to issue an EXEC CICS RECEIVE command following the RETURN.
  • INPUTMSGLEN (data_value) - Halfword binary (PIC 9(4) COMP) value indicating the length of INPUTMSG. If the value is negative, zero is assumed.
  • LENGTH (data_value) - Halfword binary (PIC 9(4) COMP) value containing the length of the COMMAREA. If the value is negative then zero is assumed. This value must not be larger than the actual COMMAREA size, if it is then unpredictable results may occur along with the LENGERR condition being set. The valid range for the COMMAREA length is 0 through 32 763 bytes. The LENGERR condition occurs for values outside this range. The INVREQ condition is set when the COMMAREA and IMMEDIATE options are used on anything other than returning control to CICS.
  • TRANSID (name) - Character field (1-4 bytes) containing the next transid to be executed at the terminal. The transid must be defined in CICS as a transaction. If the IMMEDIATE option is used with this option (TRANSID), then control is passed to the transaction id specified in this option in preference to any transaction enqueued by ATI. If the IMMEDIATE option is not used with the TRANSID option, then an ATI initiated transaction of the same name enqueued to the terminal nullifies this option. This option is invalid when Issued from a non-terminal transaction, or when it is associated with an APPC logical unit.The common Handle Conditions are INVREQ and LENGERR.
  • INVREQ - INVREQ occurs for any of the following reasons:
    1. Non-terminal command issued with the TRANSID option.
    2. Application program which is not at the highest logical level issues the command with the options COMMAREA or IMMEDIATE.
    3. Command issued with a null address in the COMMAREA option.
    4. Command is issued with the TRANSID option that is associated with an APPC logical unit. The default action when INVREQ occurs is the abnormal termination of the task.
  • LENGERR - Condition is set when the length value specified is outside the allowable range (1-32,763). The error condition is also set when the LENGTH option value specified is greater than the actual size of the COMMAREA. The default action of LENGERR is the abnormal termination of the task.

An example of the RETURN command is given below:


All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

IBM Mainframe Topics