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.

2 thoughts on “Demystifying COMMAREA

  1. “We must declare the commarea structure in the working storage section of the program…”
    This is incorrect. The following code, just after PROCEDURE DIVISION, is much better and eliminates the “need” for any Commarea in Working Storage:
    IF EIBCALEN = 0,
    EXEC CICS GETMAIN SET (ADDRESS OF DFHCOMMAREA)
    LENGTH (LENGTH OF DFHCOMMAREA) END-EXEC
    END-IF

    Now there is only ONE copy of the Commarea – much easier to keep track of!

Leave a Reply

Your email address will not be published. Required fields are marked *

9 − seven =