Protecting the CWA

The CWAKEY system initialization parameter allows you to specify whether the CWA is to be allocated from CICS-key or user-key storage.

See CWAKEY parameter 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).

Programs that run in CICS key can also write to CICS storage, ensure that such programs are thoroughly tested to make sure that they do not overwrite CICS storage.

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 1 illustrates a particular use of the CWA where the CWA itself is protected from user-key application programs by CWAKEY=CICS.

Figure 1. Example of use of CWA in CICS-key storage. This illustrates how the CWA can be used to reference storage that is obtained in user-key or CICS-key storage for use by application programs, while the CWA itself is protected by being in CICS-key storage.
This diagram shows a CWA that has been initialized by a PLTPI program that obtains storage for application-related tables and stores the addresses of the GETMAINed storage in the CWA. The diagram shows the CWA with pointer ptr_ref1 to a CICS-key application storage area, and pointer ptr_ref2 to a user_key application storage area.

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), ensuring the CWA is protected from overwriting by application programs. In Figure 1, 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 2, 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).

Figure 2. Sample code for loading the CWA
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.