Spi Trade Cics Course Ware (Adv Cics)

Version 2 SPI Confidential 1

Advanced CICS


ContentsA. Coding CICS ProgramB. Sample ProgramC. Temporary storage controlD. Some more CICS commands &

programming techniquesE. Processing files sequentiallyF. More CICS control featuresG. Legacy coding conventions


A. Coding CICS Program


How to code a CICS program

• How to control the execution of the programs within a task

• How to work with mapsets• How to work with files• Other coding essentials

A01


How to control the execution of the programs within a task

• The operation of program control commands

• RETURN command• XCTL command• LINK command• COBOL CALL statement• ABEND command

A02


The operation of program control commands

A02a


Flow of control between programs and subprogramsA02a1


RETURN commandA02b


XCTL commandA02c


LINK commandA02d


COBOL CALL statement

Syntax:CALL (‘subprogram-name | data-area)

[USING identifier-1 …]

Example:MOVE COMMUNICATION-AREA TO

DFHCOMMAREA.CALL ‘GETINV’ USING DFHEIBLK,

DFHCOMMAREA, INV-INVOICE-NUMBER.

A02e


ABEND command

Syntax:EXEC CICS

ABEND [ABCODE (abend-code)][NODUMP]

END-EXEC

A02f


How to work with mapsets

Syntax of SEND MAPEXEC CICS

SEND MAP (map-name)[MAPSET(mapset-name)][FROM (data-name)][MAPONLY | DATAONLY][ERASE | ERASEAUP][ALARM][CURSOR [(data-value)]]

END-EXEC

Syntax of RECEIVE MAPEXEC CICS

RECEIVE MAP(map-name) [MAPSET(mapset-name)] [INTO (data-name)]

END-EXEC

A03


How to work with files

• READ command• WRITE command• REWRITE command• DELETE command• UNLOCK command

A04


READ commandSyntax:EXEC CICS

READ FILE (filename) INTO (data-name) RIDFLD (data-name)[RRN | RBA][UPDATE]

END-EXEC

Example:EXEC CICS

READ FILE (‘CUSTMAS’) INTO (CUSTOMER-MASTER-RECORD) RIDFLD (CM-CUSTOMER-NUMBER) UPDATE RESP(RESPONSE-CODE)

END-EXEC

A04a


WRITE commandSyntax:EXEC CICS

WRITE FILE (filename) FROM (data-name) RIDFLD (data-name)[RRN | RBA]

END-EXEC

Example:EXEC CICS

WRITE FILE (‘CUSTMAS’) INTO (CUSTOMER-MASTER-RECORD) RIDFLD (CM-CUSTOMER-NUMBER) RESP(RESPONSE-CODE)

END-EXEC

A04b


REWRITE commandSyntax:EXEC CICS

REWRITE FILE (filename) FROM (data-name)

END-EXEC

Example:EXEC CICS

REWRITE FILE (‘CUSTMAS’) FROM (CUSTOMER-MASTER-RECORD) RESP(RESPONSE-CODE)

END-EXEC

A04c


DELETE commandSyntax:EXEC CICS

DELETE FILE (filename) RIDFLD (data-name)[RRN | RBA]

END-EXEC

Example (record previously read for update):EXEC CICS

DELETE FILE (‘CUSTMAS’) RESP(RESPONSE-CODE)

END-EXEC

Example (record not previously read for update):EXEC CICS

DELETE FILE (‘CUSTMAS’) RIDFLD (CUSTOMER-MASTER-RECORD) RESP(RESPONSE-CODE)

END-EXEC

A04d


UNLOCK commandSyntax:EXEC CICS

UNLOCK FILE (filename)END-EXEC

Example:EXEC CICS

UNLOCK FILE (‘CUSTMAS’)END-EXEC

A04e


Potential problems when updating file

• One program changes or deletes a record while another is trying to update it

• Deadlock: Two tasks are each waiting for a resource that the other is holding.

A04f


Other coding essentials

• Common exceptional conditions• Using response code• Defining communication area• Managing event context of a

program

A05


Common exceptional conditionsA05a


Using response codeSyntax:[RESP (data-name)]

Example:EXEC CICS

READ FILE (‘CUSTMAS’) INTO (CUSTOMER-MASTER-RECORD) RIDFLD (CM-CUSTOMER-NUMBER) RESP(RESPONSE-CODE)

END-EXEC

EVALUATE RESPONSE-CODEWHEN DFHRESP(NORMAL)

MOVE input-fields TO display-areaWHEN DFHRESP(NOTFND)

MOVE “Customer does not exist” TO message-display-areaWHEN OTHER

EXEC CICSABEND

END-EXECEND-EVALUATE

A05b


Defining communication area01 COMMUNICATION-AREA.

05 CA-CONTEXT-FLAG PIC X.88 PROCESS-KEY-MAP VALUE ‘1’.88 PROCESS-ADD-CUSTOMER VALUE ‘2’.88 PROCESS-CHANGE-CUSTOMER VALUE ‘3’.88 PROCESS-DEL-CUSTOMER VALUE ‘4’.

05 CA-CUSTOMER-RECORD.10 CA-CUSTOMER-NUMBER PIC X(6).10 FILLER PIC X(112).

A05c


Sample Program (Requirement)A05d


Event/response chartA05e


Managing event context of a programA05f


B. Sample CICS Program


Structure chartB01


Program codeB02a


Program code (contd.)B02b


Program code (contd.)B02c


Program code (contd.)B02d


Program code (contd.)B02e


Program code (contd.)B02f


Program code (contd.)B02g


Program code (contd.)B02h


C. Temporary storage control


Temporary storage queue conceptsC01


WRITEQ TS commandC02

Syntax:

EXEC CICS WRITEQ TS {QUEUE | QNAME} (queue-name)

FROM (data-name) [ITEM (data-name) REWRITE] [NUMITEMS(data-name)] [MAIN | AUXILIARY]

END-EXEC

Example:

Add record to TSQEXEC CICS

WRITEQ TS QUEUE (TS-QUEUE-NAME) FROM (TS-QUEUE-RECORD)

END-EXEC

Update an existing record in TSQEXEC CICS

WRITEQ TS QUEUE (TS-QUEUE-NAME) FROM (TS-QUEUE-RECORD) ITEM (TS-ITEM-NUMBER) REWRITE RESP (RESPONSE-CODE

END-EXEC


READQ TS commandC03

Syntax:

EXEC CICS READQ TS { QUEUE | QNAME} (queue-name)

INTO (data-name) [ ITEM (data-name) |

literal |NEXT ]

[ NUMITEMS (data-name) ]END-EXEC

Example:

Read a record from TSQ randomlyEXEC CICS

READQ TS QUEUE (TS-QUEUE-NAME) INTO (TS-QUEUE-RECORD) ITEM (TS-ITEM-NUMBER) RESP (RESPONSE-CODE)

END-EXEC

Read the next record from TSQEXEC CICS

READQ TS QUEUE (TS-QUEUE-NAME) INTO (TS-QUEUE-RECORD) NEXT

END-EXEC


DELETEQ TS commandC04

Syntax:

EXEC CICS DELETEQ TS { QUEUE | QNAME} (queue-name)END-EXEC

Example:

Delete a TSQEXEC CICS

DELETEQ TS QUEUE (TS-QUEUE-NAME)RESP (RESPONSE-CODE

END-EXEC


Sample program using TSQC05a


Sample program using TSQ (contd.)C05b


Sample program using TSQ (contd.)C05c


Temporary storage command - CEBR

The CEBR command lets one browse the contents of a temporary storage queue which may be required while testing a program.

The syntax is as follows: CEBR (queue-name)

This brings up the details of the queue specified in the queue-name option, as shown below.


D. Some more CICS commands & programming techniques


Some more CICS commands & programming techniques

• Terminal handling techniques– Positioning the cursor– Modifying field attributes– Optimizing data transmission– Identifying data entry fields– Editing input data– Editing numeric data– Sample programs that edit numeric data– Using SEND TEXT command

• Handling unrecoverable errors– Invoking a general error handling program– COBOL code for general error handling

• Accessing data using Linkage Section– Using fields in the EIB– Accessing CICS areas

• Formatting date & time– Using ASKTIME command– Using FORMATTIME command

D01


Terminal handling techniques: Positioning the cursor

Using IC option in DFHMDFCUSTNO DFHMDF POS=(2,26), X

LENGTH=6, XATTRB=(NORM, UNPROT, IC), X

. . .

Using direct cursor positioningEXEC CICS

SEND MAP (‘MNTMAP1’)MAPSET(‘MNTSET1’)FROM(MNTMAP1O)CURSOR(346)

END-EXEC

Using symbolic cursor positioningMOVE -1 TO CUSTNOIL.

EXEC CICSSEND MAP (‘MNTMAP1’)

MAPSET(‘MNTSET1’)FROM(MNTMAP1O)CURSOR

END-EXEC

D02a


Terminal handling techniques: Modifying field attributesD02b1


Terminal handling techniques: Modifying field attributesD02b2


Terminal handling techniques: Optimizing data transmission

D02c1

Minimize data sent from program to terminalMove Low-Value to symbolic map fields present on screen and should remain unchangedUse DATAONLY with SEND MAP when sending data using a map already onscreen


Terminal handling techniques: Optimizing data transmission (contd.)

D02c2

Minimize data sent to program when user presses attention keyMaintain copy of screen-fields in CASpecifying FRSET on SEND MAP to turn off the MDT of all unprotected fieldsAfter issuing RECEIVE MAP, merge new entries with fields saved in CA from previous transmission


Terminal handling techniques: Screen format recommendations

D02d1


Terminal handling techniques: Screen format recommendations

D02d2


Terminal handling techniques: Identifying data entry fields

D02d3


Terminal handling techniques: Editing input dataD02e


Terminal handling techniques: Editing numeric data

D02f


Terminal handling techniques: Sample program that edits numeric data (INTEDIT)

D02g1


Terminal handling techniques: Sample program that edits numeric data (NUMEDIT)

D02g2a


Terminal handling techniques: Sample program that edits numeric data (NUMEDIT)

D02g2b


Terminal handling techniques: Using SEND TEXT command

Syntax:EXEC CICS

SEND TEXT FROM (data-name)[ERASE][FREEKB]

END-EXEC

Example:WORKING-STORAGE SECTION.01 TERMINATION-MESSAGE PIC X(14) VALUE “Session ended”.

.

.PROCEDURE DIVISION.

.

.EXEC CICS

SEND TEXT FROM (TERMINATION-MESSAGE) ERASE FREEKB

END-EXEC

D02h


Handling unrecoverable errors: Invoking a general error handling program

D03a


Handling unrecoverable errors: COBOL code for general error handling

D03b


Accessing data using Linkage SectionUsing fields in the EIB

D04a


Accessing data using Linkage SectionAccessing CICS areasD04b

Syntax:

EXEC CICSADDRESS [CWA (pointer)]

[TWA (pointer)] [TCTUA (pointer)]

END-EXEC

Sample:

LINKAGE SECTION.

* 01 DFHCOMMAREA PIC X.* 01 COMMON-WORK-AREA.

05 CWA-CURRENT-DATE PIC X(8).05 CWA-COMPANY-NAMEPIC X(30).

* PROCEDURE DIVISION.* .

.EXEC CICS

ADDRESS CWA (ADDRESS OF COMMON-WORK-AREA)END-EXEC.MOVE CWA-COMPANY-NAME TO COMPO.


Formatting date & timeUsing ASKTIME command

D05a

SYNTAX:

EXEC CICSASKTIME [ABSTIME (data-name)

END-EXEC

Sample: WORKING-STORAGE SECTION.

..

01 DATE-AND-TIME-FIELDS.05 ABSOLUTE-TIME PIC S9(15) COMP-3...

PROCEDURE DIVISION...EXEC CICS

ASKTIME ABSTIME (ABSOLUTE-TIME))END-EXEC...


Formatting date & timeUsing FORMATTIME commandD05b1


Formatting date & timeUsing FORMATTIME command (contd.)D05b2


Formatting date & timeUsing FORMATTIME command (contd.)

D05b3

SamplesFormat default date & time

EXEC CICSFORMATTIME ABSTIME (ABSOLUTE-TIME)

DATE(WS-DATE) DATESEP TIME(WS-TIME) TIMESEP

END-EXEC

Format dd-mm-yyyy dateEXEC CICS

FORMATTIME ABSTIME (ABSOLUTE-TIME) DDMMYYYY(WS-FULL-

DATE) DATESEP(‘-’)

END-EXEC


E. Processing files sequentially


Processing files sequentially

• STARTBR• READNEXT & READPREV• ENDBR• RESETBR

E01


Processing files sequentially STARTBR

E02a

Syntax of STARTBREXEC CICS

STARTBR FILE(filename) RIDFLD(data-name)

[RRN | RBA] [GTEQ | EQUAL] [GENERIC] [KEYLENGTH (data-name) | literal]

END-EXEC

Sample of STARTBREXEC CICS

STARTBR FILE(‘CUSTMAS’) RIDFLD(CM-CUSTOMER-NUMBER)

RESP(RESPONSE-CODE)END-EXEC


Processing files sequentially Controlling STARTBR position

E02b


Processing files sequentially READNEXT & READPREV

E03a

Syntax of READNEXT & READPREV

EXEC CICS [READNEXT | READPREV] FILE(filename)

INTO(data-name) RIDFLD(data-name) [RRN | RBA] [KEYLENGTH (data-name) | literal]

END-EXEC


Processing files sequentially A typical READNEXT procedure

E03b


Processing files sequentially ENDBR

Syntax of ENDBR

EXEC CICS ENDBR FILE(filename)

END-EXEC

SampleEXEC CICS

ENDBR FILE(‘INVOICE’)END-EXEC

E04


Processing files sequentially RESETBR

E05

Syntax of RESETBREXEC CICS

RESETBR FILE(filename) RIDFLD(data-name)

[RRN | RBA][GTEQ | EQUAL][GENERIC][KEYLENGTH (data-name | literal)]

END-EXEC

SampleEXEC CICS

RESETBR FILE(‘CUSTMAS’)RIDFLD(CM-CUSTOMER-NUMBER)EQUALRESP(RESPONSE-CODE)

END-EXEC


Processing files sequentially Exceptional conditions

E06


F. More CICS control features


More CICS control features

• Interval control– Automatic time-ordered transaction– START– RETRIEVE– CANCEL– DELAY

• Task control– SUSPEND– ENQ & DEQ

• Storage control– GETMAIN– FREEMAIN

F01


Interval control Automatic time-ordered transaction initiation

F02a


Interval controlAutomatic time-ordered transaction initiation (contd.)

F02b


Interval control START

F03a


Interval control START examples

F03b


Interval control RETRIEVE

F04

Syntax of RETRIEVEEXEC CICS

RETRIEVE INTO(data-name)[RTRANSID(data-name)][RTERMID(data-name)][QUEUE(data-name)]

END-EXEC

SampleEXEC CICS

RETRIEVE INTO(ITEM-NUMBER)RESP(RESPONSE-CODE)

END-EXEC

Ref:EXEC CICS

START TRANSID(‘LST1’) FROM(ITEM-NUMBER)

END-EXEC


Interval control CANCEL

Syntax of CANCELEXEC CICS

CANCEL REQID(request-id)END-EXEC

F05


Interval Control DELAY - syntax

EXEC CICS DELAY ( (INTERVAL(HHMMSS) ) (TIME(HHMMSS) ) (FOR (HOURS (HH)) (MINUTES(MM)) (SECONDS(SS)) ) (UNTIL (HOURS (HH)) (MINUTES(MM)) (SECONDS(SS)) ) (REQID (name)) END-EXEC.

INTERVAL : A 7 digit packed decimal (PIC S9(7) COMP-3) specifies the duration for delay coded in the form of HHMMSS

TIME : A 7 digit packed decimal (PIC S9(7) COMP-3) specifies the time of the day when the delay will end coded in the form of HHMMSS

FOR : Specifies that the HOURS,MINUTES and SECONDS options indicate a duration for the delay.

UNTIL: Specifies that the HOURS,MINUTES and SECONDS options indicate a time of the day when th DELAY will end.

HOURS : Specifies PIC S9(8)COMP in the range of 0 to 99MINUTES: Specifies PIC S9(8)COMP in the range of 0 to 59SECONDS: Specifies PIC S9(8)COMP in the range of 0 to 99REQID : Specifies a 1-8 character request indenitifier that is associated with the DELAY

command.

F06a


Interval Control DELAY – contd.

The Delay command helps in suspending the task until a specified time interval has elapsed or a specified time of day has arrived.

This is not used widely as there are not much good uses of this command.

In some cases it might be necessary to force a minimum response time on terminal transactions, and in such cases DELAY command can be used.

Issue a DELAY command just before the SEND MAP command by specifying the time limit in the TIME or UNTIL option. A better alternative is to use POST,WAIT command.

The DELAY command can be used in one more possible area, i.e when the program needs to retry an operation after a failure allowing time for the operator to correct the problem that caused the failure. In this case the task can be delayed for some time say 15 second before the retrying the operation. But make sure to limit the number of retries so that the task doesn't wait indefinitely.

F06b


Interval Control DELAY – contd.

There are two ways to use the HOURS,MINUTES,SECONDS options following the FOR option.

If used in combination the ranges are 0-99 for hours, 0-59 for minutes and 0-59 for seconds, if a single option is specified then a larger range can be specified.

For Ex: FOR Minutes(1) Seconds(30) cane also be specified as SECONDS(90).

If the REQID option is used, then make sure to pass the request identifier value to the other programs so that they can be used to CANCEL the DELAY request.

POST and WAIT commands also achieve the same result.The CANCEL command specified with the same request ID will

terminate/cancel the already issued DLEAY or POST command.

EXEC CICS CANCELREQID(id)

END-EXEC.

F06c


Task Control SUSPEND.

Syntax

EXEC CICSSUSPEND

END-EXEC

F07


Task Control ENQ and DEQ.

SyntaxEXEC CICS

{ENQ | DEQ} RESOURCE(data-name)END-EXEC

SamplesEXEC CICS

ENQ RESOURCE(DSTINATION-ID)END-EXEC

EXEC CICSDEQ RESOURCE(DSTINATION-ID)

END-EXEC

F08


Storage Control GETMAIN

SyntaxEXEC CICS

GETMAIN SET(pointer) FLENGTH(data-name | literal) [BELOW][INITIMG(data-name)]

F09


Storage Control FREEMAIN

SyntaxEXEC CICS

FREEMAIN DATA(data-name)DATAPOINTER(pointer)

END-EXEC

SamplesEXEC CICS

FREEMAIN DATA(PRODUCT-RECORD)END-EXEC

EXEC CICSFREEMAIN DATAPOINTER(ADDRESS OF PRODUCT-RECORD)

END-EXEC

F10


G. Legacy coding conventions


Legacy coding conventions

• HANDLE AID• HANDLE CONDITION

G01


Legacy coding conventions HANDLE AID

G02a

Syntax of HANDLE AIDEXEC CICS

HANDLE AIDoption [(procedure-name)] …

END-EXEC

SamplesHandles two AID keysEXEC CICS

HANDLE AID PF3(1100-PF3) CLEAR(1100-CLEAR)

END-EXEC

Handles all AID keys except ENTEREXEC CICS

HANDLE AID PF3(1100-PF3) ANYKEY(1100-

ANYKEY) CLEAR

END-EXEC

Common options

PA1-PA3, PF1-PF24,ENTER,CLEAR,ANYKEY


Legacy coding conventionsHANDLE AID sampleG02b


Legacy coding conventions HANDLE CONDITION

Syntax of HANDLE CONDITIONEXEC CICS

HANDLE CONDITION condition-name [(procedure-name)] …END-EXEC

G03a


Legacy coding conventionsHANDLE CONDITION sampleG03b


Documents

Spi Trade Cics Course Ware (Adv Cics)