LENGERR
occurs if the length specified is less than the actual length of the stored data.
Default action: terminate the task abnormally.
NOTFND
occurs in any of the following situations: v
A RETRIEVE command is issued, but some prior task retrieved the data stored under the request identifier directly through temporary storage requests and then released the data. v The request identifier associated with the START command is not unique, so when a RETRIEVE command is issued, CICS cannot find the data.
Default action: terminate the task abnormally.
Examples
The following example shows how to retrieve data stored by a START command for the task, and store it in the user-supplied data area called DATAFLD.
EXEC CICS RETRIEVE
INTO(DATAFLD)
LENGTH(LENG)
The following example shows how to request retrieval of a data record stored for a task into a data area provided by CICS; the pointer reference (PREF) specified by the SET option is set to the address of the storage area reserved for the data record.
EXEC CICS RETRIEVE
SET(PREF)
LENGTH(LENG)
RETURN
Return control from an application program either to an application program at the next higher logical level or to CICS.
RETURN
TRANSID (
name
)
COMMAREA (
data-area
)
LENGTH (
data-value
)
IMMEDIATE
INPUTMSG (
data-area
)
INPUTMSGLEN (
data-value
)
Conditions:
INVREQ, LENGERR
Description
The RETURN command returns control from an application program either to an application program at the next higher logical level or to CICS.
424
CICS for iSeries Application Programming Guide V5
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; otherwise the results are unpredictable. This may
result in a LENGERR condition, as described in “Passing data to other programs” on page 201.
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 and IMMEDIATE options can be used only when the EXEC CICS 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.
See Chapter 20, “Program control,” on page 199 for more information about
program control.
Options
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. 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. In a C receiving program, this data area must be referenced by an EXEC CICS ADDRESS COMMAREA command.
The specified communication area is passed to the initial program of the next transaction 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 an EXEC CICS RETURN command issued by a program at the highest logical level, that is, a program returning control to
CICS.
If you have defined the terminal with ATISTS(*YES) in the ADDCICSTCT CL command, the next program is not guaranteed to be part of the transaction specified by TRANSID. It could be part of a transaction started by a previously specified automatic transaction initiation (ATI) that has already been passed to that program. To make sure that the communication area is passed to the correct program, either define the terminal with ATISTS(*NO) (indicating no
ATI) in the ADDCICSTCT CL command, or use the IMMEDIATE option.
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 an
EXEC CICS RETURN command issued by a program at the highest logical level, that is a program returning control to CICS.
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.
The data in the INPUTMSG data area is passed to the first program to issue an
EXEC CICS RECEIVE command following the RETURN.
Chapter 32. Application programming commands - reference
425
See Chapter 20, “Program control,” on page 199 for more information and
illustrations about the use of INPUTMSG.
INPUTMSGLEN(
data-value
)
specifies as a halfword binary value the length of the INPUTMSG data. If the value is negative, zero is assumed.
LENGTH(
data-value
)
specifies as a halfword binary value the length in bytes of the communication area. If a negative value is supplied, zero is assumed. For a description of a
safe upper limit, see “LENGTH options” on page 312.
TRANSID(
name
)
specifies the transaction identifier 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 can be up to 4 characters long and must have been defined as a transaction to CICS.
If the terminal is defined with ATISTS(*YES) in the ADDCICSTCT CL command, and the IMMEDIATE option is not specified, a transaction started by ATI may be run before the next transaction started by terminal input. If this happens, and the transaction identifier of the transaction started by ATI is the same as that specified in the TRANSID option, CICS assumes that the transaction started by ATI performs the same function and erases the “name” specified in the TRANSID 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.
Exception Conditions
INVREQ
RESP2 values:
1
A RETURN command with the TRANSID option is issued in a program that is not associated with a terminal.
2
3
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 is issued with a null address in the
COMMAREA option.
4
8
200
A RETURN command with the TRANSID option is issued in a program that is associated with an APPC logical unit.
A RETURN command is issued in a program that is not associated with a terminal.
A RETURN command is issued with an INPUTMSG option in a program invoked by DPL.
Default action: terminate the task abnormally.
LENGERR
v
The length specified on the LENGTH option is greater than the length of the data area specified in the COMMAREA option, and while that data was being copied a destructive overlap occurred because of the incorrect length. v v
The LENGTH value is outside the range 1 through 32 763.
The INPUTMSGLEN value is outside the range 1 through 32 767.
426
CICS for iSeries Application Programming Guide V5
