RETRIEVE

EXEC CICS RETRIEVE fetches the data that a START command stored for a new task.

Every task started with START ... FROM(data) begins by issuing RETRIEVE to collect that data.

What RETRIEVE does

• Reads the data area passed by the FROM option of the START command.
• INTO names the receiving field and LENGTH gives its size.
• RTRANSID returns the trans-id of the transaction that issued the START.
• If the task was not started by a START command, the ENDDATA condition is raised.

When to use RETRIEVE

• As the first command in any program that can be started by a START request.
• In batch-style CICS programs: report printing, delayed updates, and file extracts.
• With the WAIT option, a terminal-attached task can wait for START data to arrive.
• Always check RESP or handle ENDDATA so a missing request does not abend the task.

RETRIEVE and START are partners

• START writes the data and schedules the task; RETRIEVE reads the data inside the new task.
• Both commands must agree on the data length and layout.
• The REQID on START identifies the request; RETRIEVE does not need it.
• A CANCEL command can remove a pending START request before it fires.

Example of RETRIEVE

• The started task opens by retrieving the data area, then checks the response code.
• EXEC CICS RETRIEVE INTO(WS-START-DATA) LENGTH(WS-DATA-LEN) RESP(WS-RESP) END-EXEC. IF WS-RESP NOT = DFHRESP(NORMAL) *--- no start data: task was not started by START --- PERFORM 9000-NO-DATA-ERROR END-IF.
• Testing RESP protects the program when someone starts the transaction manually from a terminal.