The common work area (CWA) is a single control block that is allocated at system startup time and exists for the duration of that CICS® session. The size is fixed, as specified in the system initialization parameter, WRKAREA. The CWA has the following characteristics:
You must not exceed the length of the CWA, because this causes a storage violation. Furthermore, you must ensure that the data used in one transaction does not overlay data used in another. One way to protect CWA data is to use the storage protection facility that protects the CWA from being written to by user-key applications. See Protecting the CWA for more information.
The CWAKEY system initialization parameter allows you to specify whether the CWA is to be allocated from CICS-key or user-key storage. See the CICS System Definition Guide for details about the CWAKEY parameter.
If you want to restrict write access to the CWA, you can specify CWAKEY=CICS. This means that CICS allocates the CWA from CICS-key storage, restricting application programs defined with EXECKEY(USER) to read-only access to the CWA. The only programs allowed to write to a CWA allocated from CICS-key storage are those you define with EXECKEY(CICS).
Because any program that executes in CICS key can also write to CICS storage, you should ensure that such programs are thoroughly tested to make sure that they do not overwrite CICS storage.
If you want to give preference to protecting CICS rather than the CWA, specify CWAKEY=USER for the CWA, and EXECKEY(USER) for all programs that write to the CWA. This ensures that if a program exceeds the length of the CWA it does not overwrite CICS storage. For more information about storage protection, see Storage control.
Figure 39 illustrates a particular use of the CWA where the CWA itself is protected from user-key application programs by CWAKEY=CICS.
In this illustration, the CWA is not used directly to store application data and constants. The CWA contains pairs of application identifiers and associated addresses, with the address fields containing the addresses of data areas that hold the application-related data. For protection, the CWA is defined with CWAKEY=CICS, therefore the program which in this illustration is a program defined in the program list table post initialization (PLTPI) list, and that loads the CWA with addresses and application identifiers must be defined with EXECKEY(CICS). Any application programs requiring access to the CWA should be defined with EXECKEY(USER), thereby ensuring the CWA is protected from overwriting by application programs. In Figure 39, one of the data areas is obtained from CICS-key storage, while the other is obtained from user-key storage.
In the sample code shown in Figure 40, the program list table post-initialization (PLTPI) program is setting up the application data areas, with pointers to the data stored in the CWA.
This example illustrates how to create global data for use by application programs, with addresses of the data stored in the CWA--for example, by a PLTPI program. The first data area is obtained from CICS-key storage, which is the default on a GETMAIN command issued by a PLTPI program, the second from user-key storage by specifying the USERDATAKEY option. The CWA itself is in CICS-key storage, and PLTPROG is defined with EXECKEY(CICS).
ID DIVISION.
PROGRAM-ID. PLTPROG.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
77 APPLID PIC X(8) VALUE SPACES.
77 SYSID PIC X(4) VALUE SPACES.
01 COMM-DATA.
03 AREA-PTR USAGE IS POINTER.
03 AREA-LENGTH PIC S9(8) COMP.
LINKAGE SECTION.
01 COMMON-WORK-AREA.
03 APPL-1-ID PIC X(4).
03 APPL-1-PTR USAGE IS POINTER.
03 APPL-2-ID PIC X(4).
03 APPL-2-PTR USAGE IS POINTER.
PROCEDURE DIVISION.
MAIN-PROCESSING SECTION.
* Obtain APPLID and SYSID values
EXEC CICS ASSIGN APPLID(APPLID)
SYSID(SYSID)
END-EXEC.
* Set up addressability to the CWA
EXEC CICS ADDRESS
CWA(ADDRESS OF COMMON-WORK-AREA)
END-EXEC.
* Get 12KB of CICS-key storage for the first application ('APP1')
MOVE 12288 TO AREA-LENGTH.
EXEC CICS GETMAIN SET(AREA-PTR)
FLENGTH(AREA-LENGTH)
SHARED
END-EXEC.
* Initialize CWA fields and link to load program
* for storage area 1.
MOVE 'APP1' TO APPL-1-ID.
SET APPL-1-PTR TO AREA-PTR.
EXEC CICS LINK PROGRAM('LOADTAB1')
COMMAREA(COMM-DATA)
END-EXEC.
* Get 2KB of user-key storage for the second application ('APP2')
MOVE 2048 TO AREA-LENGTH.
EXEC CICS GETMAIN SET(AREA-PTR)
FLENGTH(AREA-LENGTH)
SHARED
USERDATAKEY
END-EXEC.
* Initialize CWA fields and link to load program
* for storage area 2.
MOVE 'APP2' TO APPL-2-ID.
SET APPL-2-PTR TO AREA-PTR.
EXEC CICS LINK PROGRAM('LOADTAB2')
COMMAREA(COMM-DATA)
END-EXEC.
EXEC CICS RETURN
END-EXEC.
MAIN-PROCESSING-EXIT.
GOBACK.