Passing Data and Control Introduction 85 Logical Program Levels 86 Passing Control 87 - LINK 87 - XCTL 87 - RETURN 88 Passing Data 90 Temporary Storage 96 Transient Data 100

Passing Data and Control

Introduction This section deals with the means by which CICS programs intercommunicate. First we cover the commands which transfer control between programs. Then we discuss the various means by which data may be passed from one program to another.

Logical Program Levels

When a program passes control to another program, and expects control to be returned to the point of transfer, then that program is considered to be at a higher level than the called program. The command which produces such a transfer of control is LINK.

Where CICS differs from the batch environment is that the XCTL command can transfer control to another program with no anticipated return to the program issuing the XCTL. Both programs are considered to be at the same logical level.

CXP-05

CICS

OAK1 OAK2 OAK3

OAK4

OAK5

OAK6

TaskControl

Logical program levels

XCTL XCTL LINK

LINK

RETURN

RETURN

RETURN

XCTL

In the case of LINK, both programs are retained in storage, and the lower level module is deleted when control is returned to the higher level program. Notice that when OAK6 issues a return, control goes back to OAK3 - even though there have been several programs intervening and OAK3 originally LINKed to OAK4. Each program has its own independent set of HANDLE AID and HANDLE CONDITION commands. Their effect is not transferred from the higher program to the lower one or vice versa. The same is true of IGNORE CONDITION.

(CXP1/6;2005.05) © Oakwood Computing Ltd Page 85 North American Distribution Rights – Computer Education Techniques, Inc.

Passing Data and Control

LINK The LINK command transfers control to another program and anticipates a return to the calling program. The resources of the calling program are retained, and this is the main disadvantage of LINK. The general format is: +------------------------------------------------------------------------+ | >>--LINK--PROGRAM(name)--+----------------------------------+--------> | | +-COMMAREA(data-area)--| lengths |-+ | | | | >--+------------------------------------------------------------+--->< | | |-INPUTMSG(data-area)--+-------------------------+-----------| | | | +-INPUTMSGLEN(data-value)-+ | | | +-+-------------------+--+--------------+--+---------------+-+ | | +-SYSID(systemname)-+ +-SYNCONRETURN-+ +-TRANSID(name)-+ | | | | lengths: | | |--+--------------------+--+------------------------+----------------| | | +-LENGTH(data-value)-+ +-DATALENGTH(data-value)-+ | +------------------------------------------------------------------------+

INVREQ, LENGERR, NOTAUTH, PGMIDERR, ROLLEDBACK, SYSIDERR, TERMERR Both COMMAREA and LENGTH are optional; you do not have to pass one. Typically, you might see:

EXEC CICS LINK PROGRAM ('PPMS') END-EXEC

or EXEC CICS LINK PROGRAM ('KK99')

COMMAREA (WS-COMMAREA) LENGTH (16) END-EXEC

When a lower level program issues a RETURN, control passes to the next instruction after the LINK in the calling program. If a COMMAREA had been passed, it may have been modified by the lower level program. The calling program will be able to process the updated values. F2-READ-COMPANY SECTION. MOVE 'CALLING LDYUT09 ' TO FZ-MESSAGES MOVE CONTROL-RECORD TO CONTROL-RECORD2 MOVE ZEROS TO TWA-LDYU-RET MOVE 'ENQ' TO TWA-LDYU-ACTION MOVE PCI-CO-KEY TO TWA-LDYU-KEY EXEC CICS LINK PROGRAM ('LDYUT09') END-EXEC.

(CXP1/6;2005.05) © Oakwood Computing Ltd Page 86 North American Distribution Rights – Computer Education Techniques, Inc.

Passing Data and Control

XCTL The XCTL command transfers control without expecting a RETURN. This has efficiency advantages because the program which issued it relinquishes claim to CICS resources and may be deleted from storage. +------------------------------------------------------------------------+ | >>--XCTL--PROGRAM(name)----------------------------------------------> | | | | >--+---------------------------------------------+-------------------> | | +-COMMAREA(data-area)--+--------------------+-+ | | +-LENGTH(data-value)-+ | | | | >--+--------------------------------------------------+-->< | | +-INPUTMSG(data-area)--+-------------------------+-+ | | +-INPUTMSGLEN(data-value)-+ | | Conditions: INVREQ, LENGERR, NOTAUTH, PGMIDERR | +------------------------------------------------------------------------+

As with LINK, the COMMAREA and LENGTH parameters are optional.

EXEC CICS XCTL PROGRAM ('RAD1') END-EXEC

EXEC CICS XCTL PROGRAM ('VV04') COMMAREA (WS-REPA) LENGTH (40) END-EXEC

(CXP1/6;2005.05) © Oakwood Computing Ltd Page 87

XCTL-JOBS SECTION. MOVE DFHENTER TO EIBAID MOVE 'XCTLING TO JOBS ' TO FZ-MESSAGES

(LENGTH OF WS-REPA) would be better

EXEC CICS XCTL PROGRAM('LSTJP01') END-EXEC. XCTL-ZZZZ SECTION. MOVE 'XCTLING TO ZZZZ ' TO FZ-MESSAGES EXEC CICS XCTL PROGRAM('ZZZZP01') END-EXEC. XCTL-EVNT SECTION. MOVE 'XCTLING TO EVNT ' TO FZ-MESSAGES EXEC CICS XCTL PROGRAM('EVNTP01') END-EXEC.

North American Distribution Rights – Computer Education Techniques, Inc.

Passing Data and Control

RETURN The RETURN command passes control back either to the program at the next higher level or to CICS. It takes the form: +------------------------------------------------------------------------+ | | | >>--RETURN--+------------------------------------------------+-------> | | +-TRANSID(name)--+--------------+--+-----------+-+ | | +-| commarea |-+ +-IMMEDIATE-+ | | | | >--+--------------------------------------------------+--------------> | | +-INPUTMSG(data-area)--+-------------------------+-+ | | +-INPUTMSGLEN(data-value)-+ | | | | >--+-------------+-->< | | +-ENDACTIVITY-+ | | | | commarea: | | |--COMMAREA(data-area)--+--------------------+--| | | +-LENGTH(data-value)-+ | | Conditions: INVREQ, LENGERR | +------------------------------------------------------------------------+

1. Return to CICS, saving COMMAREA

COA-226

TS queue

TD queue

COMMAREA

EXEC CICS RETURN Return to CICS and pass the specified COMMAREA to TRANSID (name) the next initiated program COMMAREA (data-area) LENGTH (data-value) END-EXEC

(CXP1/6;2005.05) © Oakwood Computing Ltd Page 88 North American Distribution Rights – Computer Education Techniques, Inc.

Passing Data and Control

EXEC CICS RETURN transfer control back to a program at the next higher END-EXEC level. If a COMMAREA had been passed, the calling program still has it, including any alterations made.

If the next higher level is CICS, no new COMMAREA is saved.

EXEC CICS RETURN transfer control back to CICS specifying the transid TRANSID (name) of the program to be initiated when END-EXEC the operator responds (pseudo-conversation)

EXEC CICS RETURN TRANSID ('PPA4') COMMAREA (WS-RECB) LENGTH (LENGTH OF WS-RECB) IMMEDIATE END-EXEC RETURN IMMEDIATE starts next transaction

COA-215

TS queue

TD queue

COMMAREA

With RETURN IMMEDIATE, the keyboard remains locked and CICS starts the next transaction as though the operator had requested it. You can supply ‘terminal input’ by adding the INPUTMSG and INPUTMSGLEN parameters to the RETURN command.

(CXP1/6;2005.05) © Oakwood Computing Ltd Page 89 North American Distribution Rights – Computer Education Techniques, Inc.

Passing Data and Control

Passing Data There are several methods of transferring data between programs:

• DFHCOMMAREA

• on the screen (dark protected, perhaps)

• TEMPORARY STORAGE

• TRANSIENT DATA

• Other CICS storage areas

• Containers and channels (with CICS TS 3.1)

Passing data between programs

COA-220

TS queue

TD queue

COMMAREA

(CXP1/6;2005.05) © Oakwood Computing Ltd Page 90 North American Distribution Rights – Computer Education Techniques, Inc.

Passing Data and Control

Using a COMMAREA The EIB field EIBCALEN gives the length of the data which has been passed. It is common to check this for zero to establish whether this is the first initiation of the program in the dialogue. i.e. is it first-time-in?

Does the COMMAREA exist?

COA-225

TS queue

TD queue

COMMAREA

Creating a COMMAREA

1. Return to CICS, saving COMMAREA

COA-226

TS queue

TD queue

COMMAREA

(CXP1/6;2005.05) © Oakwood Computing Ltd Page 91 North American Distribution Rights – Computer Education Techniques, Inc.

Passing Data and Control

The first program terminates and its data areas are deleted. However, the COMMAREA is preserved by CICS and is associated with the user’s terminal.

2. Program areas deleted, COMMAREA in CICS

COA-227

TS queue

TD queue

COMMAREA

When the user’s work resumes with the next task, the program checks EIBCALEN and uses its LINKAGE SECTION to access the COMMAREA contents.

3. New program uses LINKAGE to access COMMAREA

COA-228

TS queue

TD queue

COMMAREA

(CXP1/6;2005.05) © Oakwood Computing Ltd Page 92

North American Distribution Rights – Computer Education Techniques, Inc.

Passing Data and Control

The program can copy the contents of the COMMAREA to working storage if required, and it can pass the COMMAREA contents to subsequent programs. Ideally, if you have a set of programs which communicate with each other, the COMMAREA should be a standard size and layout for each program.

4. Optional: copy COMMAREA to W-S

COA-229

TS queue

TD queue

COMMAREA

The theoretical maximum size of a COMMAREA is 32k (VTAM restriction), but to be on the safe side, keep it less than 2048 bytes. The COMMAREA is a flexible method of passing data between transactions in multiple CICS regions and CICSplexes. In the latter case, the contents must not include storage addresses. This avoids inter-transaction affinities which force two transactions to run in the same CICS region, thus limiting the scope for balancing the workload across regions.

(CXP1/6;2005.05) © Oakwood Computing Ltd Page 93 North American Distribution Rights – Computer Education Techniques, Inc.

Passing Data and Control

The second method of passing data between programs is not recommended except where the volume of data is very small (and the network is local). IBM does not recommend this method. It precludes the use of CLEAR; data disappears! Only character data should be used since hex data causes unpredictable results on 3270s. MDTs must be left on (Modified Data Tags) since unchanged data would not otherwise be sent back to the program.

Passing data between programs

COA-220

TS queue

TD queue

COMMAREA

The next two methods use special CICS facilities: TEMPORARY STORAGE and TRANSIENT DATA. These scratchpad facilities can also be used within a program for other purposes e.g. as workfiles. We will examine TS and TD queues in more detail later in this section.

(CXP1/6;2005.05) © Oakwood Computing Ltd Page 94 North American Distribution Rights – Computer Education Techniques, Inc.

Passing Data and Control

The final method of passing data uses CICS areas. They offer several possibilities, all of which have limitations and drawbacks. These were used frequently in old CICS programs, but are not now generally recommended.

ADDRESS enables a program toaccess external storage areas

CXC-20

EIB

CWA

TCTUA

TWA

program

CECI ADDRESS STATUS: COMMAND EXECUTION COMPLETE NAME= EXEC CICS ADdress < Acee( X'FF000000' ) > < COmmarea( X'0BD001A8' ) > < CWa( X'000C1000' ) > < Eib( X'001400D0' ) > < TCtua( X'FF000000' ) > < TWa( X'FF000000' ) > Programs which use the addresses of these control blocks cause transaction affinities if they pass the addresses to other programs. This affects flexibility in a CICSplex.

(CXP1/6;2005.05) © Oakwood Computing Ltd Page 95 North American Distribution Rights – Computer Education Techniques, Inc.

Passing Data and Control

Temporary Storage This CICS facility allows the program to store data in a queue either in main storage or on auxiliary (disk) storage. Exactly where and how this is achieved is controlled by CICS.

TS queues are disk or main storage

CXP-10

TS queue

TD queue

Access to this data is normally sequential, but it can be made random by specifying an ITEM number in the relevant command. There are commands for writing, reading, and updating items, and a queue can also be deleted if it is no longer required.

Temporary storage queues are set up dynamically when the first WRITE operation is performed. They are explicitly deleted under program control. Do this as soon as possible for efficiency. It is common to encounter WRITE errors as a result of failing to delete a queue at the appropriate point.

A queue is identified by an eight character name [16 characters from CICS TS 1.3], and may be accessed by any task which knows that name. For this reason (and because CICS programs are re-entrant and shareable) it is usually necessary to construct a unique queue name for each task or dialogue. This is frequently done by extracting unique information from the EIB such as task number, terminal id, and operator id.

TS queues can be browsed using the CEBR transaction. You can also use Xpediter to view their contents.

(CXP1/6;2005.05) © Oakwood Computing Ltd Page 96 North American Distribution Rights – Computer Education Techniques, Inc.

Passing Data and Control

(CXP1/6;2005.05) © Oakwood Computing Ltd Page 97

Writing to a TS Queue +------------------------------------------------------------------------+ | |

QUEUE(8-char-name) QNAME(16-char-name)

| >>--WRITEQ TS--+-QUEUE(name)-+--FROM(data-area)----------------------> | | +-QNAME(name)-+ | | | | >--+--------------------+--+------------------------------+----------> | | +-LENGTH(data-value)-+ |-NUMITEMS(data-area)----------| | | +-ITEM(data-area)--+---------+-+ | | +-REWRITE-+ | | | | +-AUXILIARY-+ | | >--+-------------------+--+-----------+---+-----------+--->< | | +-SYSID(systemname)-+ +-MAIN------+ +-NOSUSPEND-+ | | Conditions: INVREQ, IOERR, ISCINVREQ, ITEMERR, LENGERR, LOCKED, | | NOSPACE, NOTAUTH, QIDERR, SYSIDERR | | | +------------------------------------------------------------------------+ Auxiliary storage is the default. WRITEQ will create the queue if it does not already exist.

EXEC CICS WRITEQ TS QUEUE (WS-DDNAME) FROM (A01REC) LENGTH (35) END-EXEC

Random WRITE of an item

Use the ITEM parameter (PIC S9(4) COMP). As before, the queue will be created if it does not already exist.

EXEC CICS WRITEQ TS QUEUE (WS-Q3) FROM (FLD-X) LENGTH(23) ITEM (WS-ITM) END-EXEC

Update an item

EXEC CICS WRITEQ TS QUEUE (WS-MYQ1) FROM (AAREC01) LENGTH (45) ITEM (IT-COUNT) REWRITE END-EXEC

North American Distribution Rights – Computer Education Techniques, Inc.

Passing Data and Control

Reading a TS queue +------------------------------------------------------------------------+ | >>--READQ TS--+-QUEUE(name)-+--+-INTO(data-area)-+-------------------> | | +-QNAME(name)-+ +-SET(ptr-ref)----+ | | | | >--+-------------------+--+---------------------+--------------------> | | +-LENGTH(data-area)-+ +-NUMITEMS(data-area)-+ | | | | +-NEXT-------------+ | | >--+------------------+--+-------------------+-->< | | +-ITEM(data-value)-+ +-SYSID(systemname)-+ | | Conditions: INVREQ, IOERR, ISCINVREQ, ITEMERR, LENGERR, NOTAUTH, | | QIDERR, SYSIDERR | +------------------------------------------------------------------------+

NOTE: the LENGTH argument differs between READQ and WRITEQ Sequential READ Use an ITEM value of +1 to start at the beginning of the queue.

EXEC CICS READQ TS QUEUE (TSTTQ1) INTO (MY-REC) ITEM (+1) LENGTH (WS-LEN) END-EXEC

Subsequent records can be read using:

EXEC CICS READQ TS QUEUE (TSTTQ1) INTO (MY-REC) LENGTH (WS-LEN) END-EXEC

Random READ Always use the ITEM parameter:

EXEC CICS READQ TS QUEUE (TEMPN3) INTO (AREA-N14) LENGTH (TLENGTH) ITEM (CC01) END-EXEC

(CXP1/6;2005.05) © Oakwood Computing Ltd Page 98 North American Distribution Rights – Computer Education Techniques, Inc.

Passing Data and Control

DELETING a queue You cannot delete a single record from a TS Queue; DELETEQ will delete the whole queue.

EXEC CICS DELETEQ TS QUEUE (name) END-EXEC

INVREQ, ISCINVREQ, NOTAUTH, QIDERR, SYSIDERR

EXEC CICS DELETEQ TS QUEUE (TEMQQ1) END-EXEC

Use HANDLE CONDITION or RESP to avoid unexpected abends. Typical errors include:

• failing to find items on read, write • wrong length on rewrite • deleting queues more than once

It is often a good idea to make sure that the queue doesn't already exist before initially writing to it. Issue a DELETE request before to the CREATE request. Make sure that the DELETE handles QIDERR. This means that if the queue (which is identified in the DELETE) is not found, your program will not abend. F2-CHECK-TS SECTION. 00003290 MOVE 'READING TS TO SEE IF EXISTS' TO FZ-MESSAGES 00003310 EXEC CICS 00003330 HANDLE CONDITION 00003340 QIDERR (F2-NO-DELETE-TS) 00003350 END-EXEC 00003360 EXEC CICS 00003370 READQ TS 00003380 QUEUE (TS-QUEUE-BSEQ) 00003390 INTO (BSEQM01) 00003400 LENGTH (TS-LENG1541) 00003410 ITEM (ITEM-01) 00003420 END-EXEC 00003430 MOVE 'DELETEING QUEUE DDDDBSEQ ' TO FZ-MESSAGES 00003470 EXEC CICS 00003480 DELETEQ TS 00003490 QUEUE (TS-QUEUE-BSEQ) 00003500 END-EXEC. 00003510 F2-NO-DELETE-TS SECTION. 00003550 EXEC CICS 00003580 HANDLE CONDITION 00003590 QIDERR (FZ-ERROR-PROCESSING) 00003600 END-EXEC. 00003610

(CXP1/6;2005.05) © Oakwood Computing Ltd Page 99 North American Distribution Rights – Computer Education Techniques, Inc.

Passing Data and Control

Transient Data This CICS scratchpad facility may be used as an alternative to TEMPORARY STORAGE. The main differences are:

• Transient Data queues must be predefined to CICS by the systems programmer in the CSD (CICS System Definition) file

• These queues are strictly sequential, no random access is available. Records may

only be read (from the appropriate type of device) in the same order as they were written (FIFO). Their main use is for exchange of batch data, either between CICS applications, or between the CICS partition and other partitions. The destination device may be disk, tape, or even line printer. Transient data queues are frequently used for printing.

• TD queues are read-destructive. You cannot therefore re-read an item.

• The TD queues have four-character names

TD queues are pre-defined to CICS

CXP-20

TS queue

TD queue

DCT

(CXP1/6;2005.05) © Oakwood Computing Ltd Page 100 North American Distribution Rights – Computer Education Techniques, Inc.

Passing Data and Control

TD queues can be defined to be CICS only, or they may be defined to be written in CICS and read by other regions e.g. batch.

• those within CICS are described as INTRAPARTITION. These are disk only.

• those outside CICS are described as EXTRAPARTITION. They may be on disk or on tape or 'slow' devices.

INTRAPARTITION TD queues may be used to initiate asynchronous tasks. Normally, tasks are initiated and controlled via terminals. However, a TD queue may be defined with a trigger-level: when the number of items on the queue reaches the specified trigger, a separate task is initiated. You should be aware that jobs done by that task need not have anything to do with the data in the queue! I TD STATUS: RESULTS - OVERTYPE TO MODIFY + Tdq(CDB2) Ind Nam(CSSL) Tdq(CDUL) Ind Nam(CSSL) Tdq(CESE) Ext Ena Ope Shr Out Dat(001) Ddn(CEEMSG ) Tdq(CESO) Ext Ena Ope Shr Out Dat(001) Ddn(CEEOUT ) Tdq(CKMQ) Ext Ena Ope Shr Out Dat(001) Ddn(MQMMSG ) Tdq(CKQQ) Int Tri( 00001 ) Ena Use(CICSUSER) Tdq(CMIG) Ind Nam(CSSL) Tdq(CPLD) Ind Nam(CPLI) Tdq(CPLI) Ext Ena Ope Mod Out Dat(001) Ddn(PLIMSG ) Tdq(CRDI) Ind Nam(CSSL) Tdq(CSCC) Ind Nam(CSSL) Tdq(CSCS) Ind Nam(CSSL) + Tdq(CSDL) Ind Nam(CSSL)

Typical applications might be:

• writing a transaction audit trail (why occupy a terminal?)

• print tasks - invoices etc. A dynamic procedure for allocating a unique name does not apply since TD queues are pre-defined.

If you manually specify the queue length in Working Storage, the variable must be defined as a PIC S9(4) COMP: (e.g. WS-QUEUE-LENGTH PIC S9(4) COMP VALUE +55.)

(CXP1/6;2005.05) © Oakwood Computing Ltd Page 101 North American Distribution Rights – Computer Education Techniques, Inc.

Passing Data and Control

Writing Data +------------------------------------------------------------------------+ | | | | | >>--WRITEQ TD--QUEUE(name)--FROM(data-area)--------------------------> | | | | >--+--------------------+--+-------------------+-->< | | +-LENGTH(data-value)-+ +-SYSID(systemname)-+ | | Conditions: DISABLED, INVREQ, IOERR, ISCINVREQ, LENGERR, LOCKED, | | NOSPACE, NOTAUTH, NOTOPEN, QIDERR, SYSIDERR | | | +------------------------------------------------------------------------+

The LENGTH is optional, depending on how the queue was defined (it may be fixed). Length will always needed for variable length intra partition queues. Example:

EXEC CICS WRITEQ TD QUEUE ('DDQ0') FROM (MY-FLD) LENGTH (65) END-EXEC

2B-1A-START SECTION. 00006880 00006890 * LOG THE RECORD SENT 00006900 * - PROD : WRITE TO A TD WHICH REDIRECTS IT TO THE CICS LOG 00006910 * - ELSE : WRITE TO TSQ RFOLDATA 00006920 00006930 IF TS-COMPANY-PROD-UT-DEV-IND = 'P' 00006940 EXEC CICS WRITEQ TD 00006950 QUEUE (WS-RFAT-TSD-NAME) 00006960 FROM (WS-RFA-RECORD) 00006970 LENGTH (WS-RFOLDATA-LEN) 00006980 END-EXEC 00006990 ELSE 00007000 EXEC CICS WRITEQ TS 00007010 QUEUE (WS-RFOLDATA-NAME) 00007020 FROM (WS-RFA-RECORD) 00007030 LENGTH (WS-RFOLDATA-LEN) 00007040 AUXILIARY 00007050 END-EXEC. 00007060

(CXP1/6;2005.05) © Oakwood Computing Ltd Page 102 North American Distribution Rights – Computer Education Techniques, Inc.

Passing Data and Control

Reading Data +------------------------------------------------------------------------+ | | | >>--READQ TD--QUEUE(name)--+-INTO(data-area)-+-----------------------> | | +-SET(ptr-ref)----+ | | | | >--+-------------------+--+-------------------+---+-----------+--->< | | +-LENGTH(data-area)-+ +-SYSID(systemname)-+ +-NOSUSPEND-+ | | Conditions: DISABLED, INVREQ, IOERR, ISCINVREQ, LENGERR, LOCKED, | | NOTAUTH, NOTOPEN, QBUSY, QIDERR, QZERO, SYSIDERR | | | +------------------------------------------------------------------------+

EXEC CICS READQ TD QUEUE ('PFQ1') INTO (WS-REC) LENGTH (WS-LEN) END-EXEC

Deleting a TD queue It is also possible to delete a transient data queue, although the effect of this is only to delete the records in the queue rather than the queue itself. You can delete records from intrapartition queues (but not extrapartition ones). +------------------------------------------------------------------------+ | | | | | >>--DELETEQ TD--QUEUE(name)--+-------------------+-->< | | +-SYSID(systemname)-+ | | Conditions: DISABLED, INVREQ, ISCINVREQ, LOCKED, NOTAUTH, QIDERR, | | SYSIDERR | | | +------------------------------------------------------------------------+

(CXP1/6;2005.05) © Oakwood Computing Ltd Page 103 North American Distribution Rights – Computer Education Techniques, Inc.