Read Passing Data and Control text version

Passing Data and Control

Introduction Logical Program Levels Passing Control - LINK - XCTL - RETURN Passing Data Temporary Storage Transient Data 85 86 87 87 87 88 90 96 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.

Task Control OAK1 XCTL

CICS

OAK2 XCTL OAK4

OAK3 LINK

RETURN

Logical program levels

OAK6

RETURN

LINK XCTL OAK5

RETURN

CXP-05

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

North American Distribution Rights ­ Computer Education Techniques, Inc.

Page 85

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 MOVE CONTROL-RECORD MOVE ZEROS MOVE 'ENQ' MOVE PCI-CO-KEY TO TO TO TO ' TO FZ-MESSAGES CONTROL-RECORD2 TWA-LDYU-RET TWA-LDYU-ACTION TWA-LDYU-KEY

EXEC CICS LINK PROGRAM ('LDYUT09') END-EXEC. (CXP1/6;2005.05)

© Oakwood Computing Ltd

North American Distribution Rights ­ Computer Education Techniques, Inc.

Page 86

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 (LENGTH OF WS-REPA) XCTL-JOBS SECTION. would be better

MOVE DFHENTER TO EIBAID MOVE 'XCTLING TO JOBS ' TO FZ-MESSAGES 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. (CXP1/6;2005.05)

© Oakwood Computing Ltd

North American Distribution Rights ­ Computer Education Techniques, Inc.

Page 87

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

TS queue

TD queue

COMMAREA

COA-226

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

North American Distribution Rights ­ Computer Education Techniques, Inc.

Page 88

Passing Data and Control EXEC CICS RETURN END-EXEC transfer control back to a program at the next higher 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. transfer control back to CICS specifying the transid of the program to be initiated when the operator responds (pseudo-conversation)

EXEC CICS RETURN TRANSID (name) END-EXEC

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

RETURN IMMEDIATE starts next transaction

TS queue

TD queue

COMMAREA

COA-215

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

North American Distribution Rights ­ Computer Education Techniques, Inc.

Page 89

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

TS queue

TD queue

COMMAREA

COA-220

(CXP1/6;2005.05)

© Oakwood Computing Ltd

North American Distribution Rights ­ Computer Education Techniques, Inc.

Page 90

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?

TS queue

TD queue

COMMAREA

COA-225

Creating a COMMAREA 1. Return to CICS, saving COMMAREA

TS queue

TD queue

COMMAREA

COA-226

(CXP1/6;2005.05)

© Oakwood Computing Ltd

North American Distribution Rights ­ Computer Education Techniques, Inc.

Page 91

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

TS queue

TD queue

COMMAREA

COA-227

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

TS queue

TD queue

COMMAREA

COA-228

(CXP1/6;2005.05)

© Oakwood Computing Ltd

North American Distribution Rights ­ Computer Education Techniques, Inc.

Page 92

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

TS queue

TD queue

COMMAREA

COA-229

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

North American Distribution Rights ­ Computer Education Techniques, Inc.

Page 93

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

TS queue

TD queue

COMMAREA

COA-220

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

North American Distribution Rights ­ Computer Education Techniques, Inc.

Page 94

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.

program

CWA TCTUA EIB

TWA

ADDRESS enables a program to access external storage areas

CECI ADDRESS STATUS: COMMAND EXECUTION COMPLETE EXEC CICS ADdress < Acee( X'FF000000' ) > < COmmarea( X'0BD001A8' ) > < CWa( X'000C1000' ) > < Eib( X'001400D0' ) > < TCtua( X'FF000000' ) > < TWa( X'FF000000' ) >

CXC-20

NAME=

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

North American Distribution Rights ­ Computer Education Techniques, Inc.

Page 95

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

TS queue

TD queue

CXP-10

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

North American Distribution Rights ­ Computer Education Techniques, Inc.

Page 96

Passing Data and Control

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

© Oakwood Computing Ltd

North American Distribution Rights ­ Computer Education Techniques, Inc.

(CXP1/6;2005.05)

Page 97

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

North American Distribution Rights ­ Computer Education Techniques, Inc.

Page 98

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. include: · failing to find items on read, write · wrong length on rewrite · deleting queues more than once Typical errors

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. MOVE 'READING TS TO SEE IF EXISTS' TO FZ-MESSAGES EXEC CICS HANDLE CONDITION QIDERR (F2-NO-DELETE-TS) END-EXEC EXEC CICS READQ TS QUEUE (TS-QUEUE-BSEQ) INTO (BSEQM01) LENGTH (TS-LENG1541) ITEM (ITEM-01) END-EXEC MOVE 'DELETEING QUEUE DDDDBSEQ ' TO FZ-MESSAGES EXEC CICS DELETEQ TS QUEUE (TS-QUEUE-BSEQ) END-EXEC. F2-NO-DELETE-TS SECTION. EXEC CICS HANDLE CONDITION QIDERR (FZ-ERROR-PROCESSING) END-EXEC. (CXP1/6;2005.05) 00003290 00003310 00003330 00003340 00003350 00003360 00003370 00003380 00003390 00003400 00003410 00003420 00003430 00003470 00003480 00003490 00003500 00003510 00003550 00003580 00003590 00003600 00003610

© Oakwood Computing Ltd

North American Distribution Rights ­ Computer Education Techniques, Inc.

Page 99

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

TS queue

TD queue DCT

CXP-20

(CXP1/6;2005.05)

© Oakwood Computing Ltd

North American Distribution Rights ­ Computer Education Techniques, Inc.

Page 100

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 Shr Out Tdq(CESO) Ext Shr Out Tdq(CKMQ) Ext Shr Out Tdq(CKQQ) Int Tri( 00001 ) Use(CICSUSER) Tdq(CMIG) Ind Nam(CSSL) Tdq(CPLD) Ind Nam(CPLI) Tdq(CPLI) Ext Mod Out Tdq(CRDI) Ind Nam(CSSL) Tdq(CSCC) Ind Nam(CSSL) Tdq(CSCS) Ind Nam(CSSL) + Tdq(CSDL) Ind Nam(CSSL)

Ena Ope Dat(001) Ddn(CEEMSG Ena Ope Dat(001) Ddn(CEEOUT Ena Ope Dat(001) Ddn(MQMMSG Ena

) ) )

Ena Ope Dat(001) Ddn(PLIMSG

)

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

North American Distribution Rights ­ Computer Education Techniques, Inc.

Page 101

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. * * * LOG THE RECORD SENT - PROD : WRITE TO A TD WHICH REDIRECTS IT TO THE CICS LOG - ELSE : WRITE TO TSQ RFOLDATA IF TS-COMPANY-PROD-UT-DEV-IND = 'P' EXEC CICS WRITEQ TD QUEUE (WS-RFAT-TSD-NAME) FROM (WS-RFA-RECORD) LENGTH (WS-RFOLDATA-LEN) END-EXEC ELSE EXEC CICS WRITEQ TS QUEUE (WS-RFOLDATA-NAME) FROM (WS-RFA-RECORD) LENGTH (WS-RFOLDATA-LEN) AUXILIARY END-EXEC.

00006880 00006890 00006900 00006910 00006920 00006930 00006940 00006950 00006960 00006970 00006980 00006990 00007000 00007010 00007020 00007030 00007040 00007050 00007060

(CXP1/6;2005.05)

© Oakwood Computing Ltd

North American Distribution Rights ­ Computer Education Techniques, Inc.

Page 102

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

North American Distribution Rights ­ Computer Education Techniques, Inc.

Page 103

Information

Passing Data and Control

20 pages

Report File (DMCA)

Our content is added by our users. We aim to remove reported files within 1 working day. Please use this link to notify us:

Report this file as copyright or inappropriate

25890


You might also be interested in

BETA
ZCICSAPP.TXT - Notepad
zCICS Application Programming Guide
Exploring CICS CHANNELs and CONTAINERs
CICS Application Programming Pr
Passing Data and Control