Chapter 2 Getting Ready to Use AI for CICS

Understanding COMMAREAs

This section covers the following topics:

Defining the COMMAREA

Modern CICS programs store presentation logic and business logic in separate programs. When the two programs need to communicate with each other, they must pass data back and forth in a COMMAREA, which is a block of contiguous memory.

Because the CICS programs must agree on the format and use of the data definitions in the COMMAREA, this area is usually mapped by a single COBOL data definition that is included in both participating programs.

The COMMAREA (data definition file) can be stored as follows:

Embedded in CICS program source code
In a copybook member that is copied in at compile time
In a separate file, copied from the source code

See § for more information about how to import the COMMAREA from each of these stored locations.

Files imported into the AI for CICS Component Builder must contain a COMMAREA for the CICS program you want and nothing else , as shown in the following example:

01 DFHCOMMAREA.
     02  CA-RETCODE                  PIC 9(8) COMP.
     02  CA-SWSECI1-COMMAREA.
         05  CA-NUMBER-OF-ROWS       PIC 9(4) COMP.
         05  CA-ERROR-MESSAGE        PIC X(10).
         05  CA-CURRENT-DATE         PIC X(8).
         05  CA-CURRENT-TIME         PIC X(8).
         05  CA-CICS-ABSTIME         PIC S9(15) COMP-3.
         05  CA-ROW-DATA  OCCURS 1  TO 1818 TIMES
                          DEPENDING ON CA-NUMBER-OF-ROWS.
             10  CA-ROW-NUMBER       PIC S9(4) COMP.
             10  CA-ROW-NUM-AS-CHAR  PIC X(6).
             10  CA-DATA             PIC X(10).

When you move a COMMAREA to the workstation, be sure you remove all REDEFINES clauses and field declarations following REDEFINES clauses.

How CICS Programs Use the COMMAREA

To communicate input and output information, the "calling" program typically sets input fields in the COMMAREA and calls another CICS program, passing the COMMAREA to it. The "called" program then puts the results of this operation back into fields in the COMMAREA and returns execution to the calling program. This makes the output for the called program available to the calling program through the COMMAREA.

Figure 2-1 shows this process: PROGA (the presentation logic) invokes PROGB (the business logic) and passes the COMMAREA to it, thus defining the input and output definitions that they will share.

Figure 2-1: CICS programs using the COMMAREA

How AI for CICS Components Map from the COMMAREA

The following figure shows how AI for CICS maps the data definitions from the COMMAREA.

Figure 2-2: How AI for CICS maps from the COMMAREA

Following are the basic steps in this process:

When you build an AI for CICS component, AI for CICS parses the COMMAREA in the copybook and stores the data definitions.
When you generate the component, AI for CICS creates a Jaguar component and maps the COMMAREA for PROGB business logic into structured parameters that the Jaguar component can understand.
When the method in the Jaguar component calls the CICS program, the structured parameters are mapped to the CICS fields, as shown in the invoke call. This presents a "component-like" interface to client applications.

Making the COMMAREA Available to AI for CICS

This section describes how to make data definitions in the COMMAREA available on the workstation so that AI for CICS can use them. Following are descriptions based on how you import the COMMAREA:

From COBOL Source Code

If the COMMAREA is embedded in source code, follow these steps to make it available to AI for CICS:

Cut and paste the source code portions of data definitions into a file.
Use FTP, a screen capture, IND$FILE, or a similar utility to copy the file and move it to the workstation where AI for CICS is installed.
If necessary, be sure that the transferred files receive EBCDIC-to-ASCII translation so they are readable characters on the workstation.
Record the name of the copied file for future reference.

From a Copybook Member

In mainframe applications, many sections of program code are common to multiple programs, such as file layouts, communication area layouts, common data definitions, and file descriptions. Most compilers are able to include code fragments from a library at compile time.

In COBOL, libraries of these code fragments are called copybooks, and the individual members within them are called copybook members.

Follow these steps to make the copybook member available to AI for CICS:

Find the source code of the program you want to make available as a component.
If your site uses code management utilities such as CA-LIBRARIAN or PANVALET, contact your mainframe systems administrator for information on locating copybooks in your environment.
Find the COPY statements that look like this:
```
COPY abcd
```
Locate the relevant members in your copybook library. If you are not sure which copybooks to use, look at the SYSLIB DDNAME in the JCL used to compile the program. One or more of the data sets allocated to this DDNAME will be the copybook for this compilation.
Find the member in the copybooks that describes the COMMAREA for the CICS program you will use to build a component. This is the copybook member you import into AI for CICS.
Using FTP, a screen capture, IND$FILE, or a similar utility, copy the copybook member and move it to the workstation where AI for CICS is installed.
If necessary, be sure that the transferred files receive EBCDIC-to-ASCII translation so they are readable characters on the workstation.
Record the CICS program name, copybook name, and copybook member names for future reference.

If the copybook member contains more than the COMMAREA definitions, edit the downloaded file so that it contains only the COMMAREA.

From a Separate File

Follow these steps to make the COMMAREA available to AI for CICS:

Using FTP, a screen capture, IND$FILE, or a similar utility, copy the file.
If necessary, be sure that the transferred file receives EBCDIC-to-ASCII translation so it is displayed as readable characters on the workstation.
Move it to the workstation where AI for CICS is installed.
Record the filename for future reference.

If the file contains more than the COMMAREA definitions, edit the downloaded file so that it contains only the COMMAREA.