The GETMAIN commands

The GETMAIN and GETMAIN64 commands provide 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, you can use these options for application programs that are executing with TASKDATAKEY(CICS) specified to obtain user-key storage for passing to, or returning to, a program that is executing in user key.

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

CICS frees all task-lifetime storage that is acquired by an application at task termination, whether it in CICS key or user key. You can also specify STORAGECLEAR(YES) on this option of the associated transaction resource definition. This clears the storage so that another task cannot view sensitive data accidentally.

For programming information about commands, see CICS API commands. For information about defining resources, see An overview of resource definition.
Figure 1. Illustration of the use of the TASKDATAKEY and EXECKEY options
The figure is described in the accompanying text.
In this example, transaction A123 is 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 a GETMAIN request to obtain CICS-key storage.
Notes:
  1. The TASKDATAKEY option ensures that the transaction work area (TWA) and EXEC interface block (EIB) are allocated from user-key storage, as 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 using 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.