Error Handling
Use the RESP and (optional) RESP2 options on the EXEC CICS commands. Then check the code to determine if an error occurred. E.g.
01 CICS-RESPONSE1 PIC S9(8) COMP VALUE +0
EXEC CICS RECEIVE
INTO (INPUT-MESSAGE-FIELD)
RESP (CICS-RESPONSE1) <- Places ‘condition code’ into working storage field.
LENGTH (EXPECTED-MESSAGE-LENGTH)
END-EXEC
EVALUATE CICS-RESPONSE1
WHEN DFHRESP(LENGERR)
PERFORM ERROR-ROUTINE
WHEN …
…
WHEN DFHRESP (NORMAL) <- check success/failure of command
PERFORM NORMAL-ROUTINE
END-EVALUATE.
RESP and RESP2 options can be added to any CICS command but are omitted below to save space
Simple I/O without maps
SEND Command
EXEC CICS SEND
FROM (data-area)
LENGTH (data-value) <- can use numeric literal or COMP field, optional as COBOL II supplies the length, but use if different length needed than the size of the data-area
ERASE <- optional to clean screen
END-EXEC.
RECEIVE Command
EXEC CICS RECEIVE
{INTO (data-area) | SET (pointer-ref)} <- INTO data-area is working storage field
SET pointer is linkage area
LENGTH (data-area)
[MAXLENGTH (data-value)]
[NOTRUNCATE]
END-EXEC
If the SET option is used then CICS does not use the current contents of the LENGTH parm but instead puts in the length of the data it has received into the field.
If MAXLENGTH is used and data received is longer than that specified CICS will truncate the data and cause a LENGERR condition in the RESP field.
If NOTRUNCATE option is used then CICS will save the ‘extra’ data and it will be available by issuing more receive commands.
On first execution within a task, the command takes data that the CICS terminal control program has already received from the terminal device and make this data available to your program. (CICS can pick up messages intended for later use by you program even before the program is loaded. If any task executes the receive command more than once CICS will determine whether additional data has arrived from the terminal and will pass along whatever it finds. If there is none, the task will wait)
Use of LINKAGE SECTION
Use the linkage section to improve program efficiency if:
Record size or device buffer size is extremely large
Use address pointers if pointer values need to be passed to another module so the other module can use the pointers to find the required data.
The following are equivalent
01 SAVE-POINTER USAGE IS POINTER.
LINKAGE SECTION.
01 YOUR-STORAGE-AREA PIC …..
PROCEDURE DIVISION. …
EXEC CICS RECEIVE
SET (ADDRESS OF YOUR-STORAGE-AREA)
LENGTH(length-field)
END-EXEC
SET SAVE-POINTER TO ADDRESS OF YOUR-STORAGE-AREA
EXEC CICS RECEIVE
SET (SAVE-POINTER)
LENGTH(length-field)
END-EXEC
SET ADDRESS OF YOUR-STORAGE-AREA TO SAVE-POINTER
Obtaining
More Storage in the Linkage Section.
Use GETMAIN only when needed more storage occasionally, or for short periods of time.
GETMAIN Command
EXEC CICS GETMAIN
SET (pointer-ref)
{LENGTH (data-value)|
FLENGTH(data-value)} <- use to allocate above 16MB line
(INITIMG(data-value) <- initialize data to zero, space,…
END-EXEC
You must have a linkage section work area specified.
The storage is freed automatically when the task terminates via the RETURN command. If the program links to another program, or for any reason does not execute a return command use the FREEMAIN command to free it up.
FREEMAIN
Command
EXEC CICS FREEMAIN
DATA(data-area) <- use name of linkage section, not pointer
END-EXEC.
Don’t try to freemain an area not belonging to your program, nor if the area was not successfully allocated, or already freemain’ed. This can cause storage violation or other errors.
Communications between Program Modules
Note that any changes made to the called program in the COMMAREA/DFHCOMMAREA will be passed back to the called program automatically when it returns.
RETURN Command
EXEC
CICS RETURN
[TRANSID(name)
[COMMAREA(data-area)
[LENGTH(data-value(]]
END-EXEC
If just RETURN is coded, the program returns to CICS, or to the calling program
Specifying TRANSID tells CICS to start that transaction as soon as someone presses and attention key on the terminal device, This will also override any tran id entered by the user
Use of COMMAREA allows data (in working storage or linkage section) to be passed to subsequent tasks.
The receiving program should always test the EIBCALEN field to ensure the received data is the expected length.
XCTL
Command
EXEC
CICS XCTL
PROGRAM(name) <- always program id, not
tran id
[COMMAREA(data-area)
LENGTH(data-value)]
END-EXEC
The calling program is released from storage. The XCTL program is
started immediately(as opposed to using RETURN that requires the user to press some
attention key)
EXEC
CICS LINK
PROGRAM(name)
[COMMAREA(data-area)
LENGTH(data-value)
END-EXEC
Resources of calling program maintained, and program control returns when called program executes a RETURN with no tran id parm. If called program does XCTL to another program and that program does a RETURN (w/o tran id parm) control will return to the original calling program.
Do not use LINK unless there is a good reason why the called program will need to return to the calling program in order to complete processing.
Possible
Error Situations
A program that tries to XCTL or LINK to a program that can’t be found in CICS tables will cause a PGMIDERR to be raised.
A COMMAREA can be used only when you are using RETURN to terminate a task. If a COMMAREA option is used in a RETURN command this is being used to return control back to a calling program rather than to CICS, then using COMMAREA with the RETURN command will raise a INVREG error condition
You should always exit from a CICS program by using RETURN, LINK, or XCTL (unless you want to use a CICS ABEND command) and not by using GOBACK or STOP RUN. Don’t let the program ‘fall out of the end of the program’
Some
Techniques of passing data
01 DFHCOMMAREA.
05 COM-SPA-AREA PIC X OCCURS
1 TO 3767 TIMES
DEPENDING
ON EIBCALEN.
Temporary Storage
Writing
EXEC CICS WRITEQ TS
QUEUE(name) <- name usually 4 char tran id and 4 char term id from EIBTRMID
FROM(data-area)
LENGTH(data-value)
[ITEM(data-area) [REWRITE]]
[MAIN|AUXILIARY] <- usually use (VSAM) AUXILLIARY storage but check standards
END-EXEC
EXEC CICS READQ TS
QUEUE(name)
{SET(pointer-ref)|INTO(data-area)} <- linkage or working storage area
LENGTH(data-area)
[ITEM(data-value)|NEXT] <- allows random access to records in queue
NUMITEMS(data-area) <-
gives total number of records in queue
END-EXEC
Deleting Queue
EXEC CICS DELETE TS
QUEUE(name)
END-EXEC
Some CICS Response codes (incomplete list)
DFHRESP(
(DISABLED) - file disabled
(INVREQ) - invalid request
(ITEMERR) - item not defined
(LENGERR) - record length error
(PGMIDERR) - program not defined to CICS
(QIDERR) - Queue not defined