Defining the storage key for applications

CICS® enables you to choose between user-key storage and CICS-key storage for a number of CICS data areas and application program data areas that your applications can use. Depending on the data area, you select the storage key by:

Defining the storage key for storage areas that your applications need to access is described in the following sections.

System-wide storage areas

For each CICS region, your installation can choose between user-key and CICS-key storage for the common work area (CWA) and for the terminal control table user areas (TCTUAs). If these areas are in user-key storage, all programs have read-write access to them; if they are in CICS-key storage, user-key application programs are restricted to read-only access. The storage keys for the CWA and the TCTUAs are set by the system initialization parameters CWAKEY and TCTUAKEY, respectively. In both cases the default option is that CICS obtains user-key storage.

See the CICS System Definition Guide for information about how to specify these and other storage-protection-related system initialization parameters.

Task lifetime storage

You can also specify whether user-key or CICS-key storage is used for the storage that CICS acquires at transaction attach time, and for those elements of storage directly related to the individual application programs in a transaction. You do this by means of the TASKDATAKEY option on the transaction resource definition. This governs the type of storage allocated for the following storage areas:

For information about how to specify the TASKDATAKEY parameter, see the CICS Resource Definition Guide.

Figure 130 shows what TASKDATAKEY controls for both task lifetime storage and program working storage.

See the CICS Application Programming Reference manual for programming information about EXEC CICS commands; see the CICS Resource Definition Guide for information about specifying the TASKDATAKEY option on the transaction resource definition.

Program working storage specifically for exit and PLT programs

CICS uses the TASKDATAKEY option of the calling transaction to determine the storage key for the storage acquired for global user exits, task-related user exits, user-replaceable modules, and PLT programs. For programming information about storage key, including details of how this affects the different types of program, see the CICS Customization Guide.

Passing data by a COMMAREA

In a pseudoconversational application, CICS ensures that a COMMAREA you specify on a RETURN command is always accessible in read-write mode to the next program in the conversation. The same is true when passing a COMMAREA within a transaction that comprises more than one program (using a LINK or XCTL command). CICS ensures that the target program has read-write access to the COMMAREA.

The GETMAIN command

The GETMAIN command provides USERDATAKEY and CICSDATAKEY options to enable the application program to explicitly request user-key or CICS-key storage, regardless of the TASKDATAKEY option specified on the associated transaction resource definition. For example, this option allows application programs, which are executing with TASKDATAKEY(CICS) specified, to obtain user-key storage for passing to, or returning to, a program executing in user key.

CICS-key storage obtained by GETMAIN commands issued in a program defined with EXECKEY(CICS) can be freed explicitly only if the FREEMAIN command is issued by a program defined with EXECKEY(CICS). If an application program defined with EXECKEY(USER) attempts to free CICS-key storage using FREEMAIN commands, CICS returns the INVREQ condition. However, an application can free user-key storage with FREEMAIN commands regardless of the EXECKEY option.

All task lifetime storage acquired by an application, whether in CICS key or user key, is freed by CICS at task termination. You can also specify STORAGECLEAR(YES) on this option of the associated transaction resource definition. This clears the storage and so prevents another task accidentally viewing sensitive data.

For programming information about commands, see the CICS Application Programming Reference manual ; for information about defining resources, see the CICS Resource Definition Guide.

Figure 130. Illustration of the use of the TASKDATAKEY and EXECKEY options
 This example shows transaction A123 defined with TASKDATAKEY(USER) and PROGRAM(PROGRAM1). PROGRAM1 is defined with EXECKEY(USER) and PROGRAM2 is defined with EXECKEY(CICS). PROGRAM1 LINKs to PROGRAM2 which uses GETMAIN to obtain CICS-key storage. The following notes give further explanation.

Notes:
  1. The TASKDATAKEY option ensures the TWA and EIB are allocated from user-key storage, required for PROGRAM1, which executes in user key--specified by EXECKEY(USER).
  2. PROGRAM1 executes in user key (controlled by EXECKEY), and has its working storage obtained in user-key storage (controlled by the TASKDATAKEY option). Any other storage the program obtains by means of GETMAIN commands or by using the SET option on a CICS command is also obtained in user-key storage.
  3. PROGRAM2 executes in CICS key (controlled by EXECKEY), but has its working storage obtained in user-key storage, which again is controlled by the TASKDATAKEY option.
  4. PROGRAM2 issues an explicit GETMAIN command using the CICSDATAKEY option and, because it executes in CICS key, can store data into the CICS-key protected storage before returning control to PROGRAM1.
  5. PROGRAM1 cannot write to the CICS-key protected storage that PROGRAM2 acquired, but can read what PROGRAM2 wrote there.

    When deciding whether you need to specify EXECKEY(CICS) and TASKDATAKEY(CICS), you must consider all the reasons that make these options necessary.

Programs that modify their storage protection key should ensure they are running in the correct key when attempting to access storage. CICS can only use the EXECKEY defined in the program definition when invoking a program.

[[ Contents Previous Page | Next Page Index ]]