Demystifying COMMAREA

Well COMMAREA its not a mystery anymore, it’s a very simple, convenient method to transfer data in CICS environment. You can use COMMAREA in a RETUN, XCTL or LINK. Called program can alter the data in the passed COMMAREA, then it will be passed to caller when called program issue a RETURN.

How to use  COMMAREA in CICS Program.

We must declare the commarea structure in the working storage section of the program which we are planning to use commarea. Then the same must be declared under DFHCOMMAREA group element in Linkage section of the program.  In the called Program the commarea must be defined as the first item in the Linkage section.

e.g.

Working-storage section.                                                         
01  WS-COMMAREA.                                                        
    03  WS-TRANSID              PIC X(4).

………

Linkage section.                                                        
01 dfhcommarea.                                                         
    03  ls-commarea             pic x(4).

When we use the commarea in a XCTL or a LINK the length of COMMAREA is mandatory. the length data name should be defined as half word binary “ S9(4) comp.  When we use COMMAREA in a CICS program, we can track the length of the COMMAREA by using EIBCALEN. This technique is widely used for PSUDO-CONVERSATIONAL programing (I’ll be blogging about PSEUDO-CONVERSATIONAL programming in coming days-please do-visit again).

LIMITATION and ALTERNATIVE TECHNOLOGIES

COMMAREA is as old as CICS so obviously it may-not be a wise choice for todays-programming. By the word todays-programs I’m referring to web-Mainframe-XML programs, because I have seen a lot of applications which gets hell lot of data as XML from java/WEB applications.

Maximum amount of data that a COMMAREA can hold is 32 Kilobytes. I you want to use more than this you can go ahead with using a data set ( Obviously it was an old alter native) or you can use CHANNELS and containers where the limit is the systems limit. ‘ll be blogging about channels and containers in the coming days.

sample program

This is a sample PSEUDO-CONVERSATIONAL CICS program, which is utilizing COMMAREA. Note the lines which in Blue color and BOLD- these are the key-part of our program.

Identification division. program-id.    pseu01. data division. working-storage section. 01  ws-commarea                pic x(4). 01  ws-msg-o.      05  msg-o-data             pic x(35). 77  msg-len                    pic s9(4) comp. 01  ws-msg-2.      05  msg-1                  pic x(6).      05  name                   pic x(5).      05  msg-2                  pic x(17). linkage section. 01  dfhcommarea.      05  ls-trnid               pic x(4). procedure division.      exec cics handle condition        lengerr(TSK-ERR-RTN)      end-exec.      if eibcalen = 0 then        go to TSK1-RTN.      if ls-trnid = 'TSK2' then        go to TSK2-RTN      end-if. TSK1-RTN.      move 'Enter Your name:' to msg-o-data.      move 16 to msg-len.      exec cics send        from(msg-o-data)        length(msg-len)        erase      end-exec.      Move 'TSK2' to ws-commarea.      exec cics return        transid('TSK1')        commarea(ws-commarea)       length(4)     end-exec. TSK2-RTN.     exec cics receive       into(name)       length(msg-len)     end-exec.     move 'Hello,' to msg-1.     move ' welcome to CICS.' to msg-2     move 28 to msg-len.     exec cics send       from(ws-msg-2)       length(msg-len)       erase     end-exec.     exec cics return     end-exec. TSK-ERR-RTN.     move low-values to msg-o-data.     move 'something goes wrong with leng.' to msg-o-data.     move 32 to msg-len.     exec cics send       from(msg-o-data)       length(msg-len)       erase     end-exec.     exec cics return     end-exec.