CICS-key applications

Some application programs need to be defined with EXECKEY(CICS) because they need to use certain facilities that are listed later.

Most application programs can be defined with EXECKEY(USER), which is the default value, and this is the option you are recommended to use in most cases. These include programs that use DL/I or DB2® and programs that access vendor products through the resource manager interface (RMI) or a LINK command.

Widespread use of EXECKEY(CICS) diminishes the protection offered by the storage protection facility because there is no protection of CICS code and control blocks from being overwritten by application programs that execute in CICS key. The ISOLATE attribute in the transaction definition does not provide any protection against application programs that execute in CICS key—that is, from programs defined with EXECKEY(CICS). Any application program causing a protection exception when defined with EXECKEY(USER) must be examined to determine why it is attempting to modify storage it is not allowed to modify. You should change a program's definition to EXECKEY(CICS) only if you are satisfied that the application program legitimately uses the facilities described here:
  • The program uses MVS macros or services directly, rather than through the CICS API. The only MVS macros that are supported in user-key programs are SPIE, ESPIE, POST, WAIT, WTO, and WTOR. It is also possible to issue GTF trace requests from an EXECKEY(USER) program. If a program uses any other MVS macro or service, it must be defined with EXECKEY(CICS). Some particular examples are:
    • Use of dynamic allocation (DYNALLOC macro, SVC 99)
    • Use of MVS GETMAIN and FREEMAIN or STORAGE requests
    • Use of MVS OPEN, CLOSE, or other file access requests

    Direct use of some MVS macros and services is undesirable, even in a CICS application defined with EXECKEY(CICS). This is because they can cause MVS to suspend the whole CICS region until the request is satisfied.

    Some COBOL, PL/I, C, and C++ language statements, and compiler options, cause operating system functions to be invoked. See Developing COBOL applications, Programming in C and C++, and Developing PL/I applications for information about which of these should not be used in CICS application programs. It is possible that some of these functions might have worked in previous releases of CICS, or at least might not have caused the application to fail. They do not work when the program is defined with EXECKEY(USER). When the use of prohibited options or statements is the cause of a protection exception, you should remove these from the program rather than redefine the program with EXECKEY(CICS). The use of prohibited statements and options can have other side effects on the overall execution of CICS, and these should be removed.

  • The program needs to modify the CWA, and the CWA is in CICS-key storage (CWAKEY=CICS).

    If you decide to protect the CWA by specifying CWAKEY(CICS), you should restrict the programs that are permitted to modify the CWA to as few as possible, perhaps only one. See Using the common work area (CWA) for information about how you can control access to a protected CWA.

  • The program needs to modify the TCTUA, and the TCTUAs are in CICS-key storage (TCTUAKEY=CICS).

    See Using the TCTTE user area (TCTUA) for information about using TCTUAs in a storage protection environment.

  • The program can be invoked from PLT programs, from transactions defined with TASKDATAKEY(CICS), from task-related or global user exits programs, or from user-replaceable programs.
  • The program modifies CICS control blocks—for example, some vendor products that do need to manipulate CICS control blocks. These must be defined with EXECKEY(CICS).
  • The program provides user extensions to CICS and requires protection and data access like CICS system code. For example, you might consider that such programs are a vital part of your CICS installation, and that their associated storage, like CICS storage, should be protected from ordinary application programs.
  • CICS always gives control in CICS key to the following types of user-written program, regardless of the option specified on their program resource definitions:
    • Global user exits (GLUEs)
    • Task-related user exits (TRUEs)
    • User-replaceable modules (URMs)
    • Program list table (PLT) programs
    • Custom EP adapters handling synchronous events

    CICS ensures that when control is passed to a PLT program, a global or task-related user exit, or a user-replaceable program, the first program so invoked executes in CICS key, regardless of the EXECKEY specified on its program resource definition. However, if this first program LINKs or XCTLs to other programs, these programs execute under the key specified in their program definitions. If these subsequent programs are required to write to CICS-key data areas, as often occurs in this type of situation, they must be defined as EXECKEY(CICS).

    In a CICS region with transaction isolation active, these TRUEs and GLUEs run in either base space or subspace (see MVS subspaces), depending on the current mode when CICS gives control to the exit program. They can also modify any application storage. The URMs and PLT programs execute in base space.

For programming information about the execution of GLUEs, TRUEs, URMs, and PLT programs in a CICS region running with storage protection, see Exit programs and the CICS storage protection facility .

If two transactions have an affinity by virtue of sharing task lifetime storage, the transactions must be defined as ISOLATE(NO), or the programs must be defined as EXECKEY(CICS). You can use the CICS Interdependency Analyzer to check the causes of transaction affinity. See CICS Interdependency Analyzer for more information about this utility. The first of these options is the recommended option, because CICS system code and data is still protected.

Tables

In addition to executable programs, you can define tables, map sets, and partition sets as program resources. EXECKEY has less relevance to these objects, because they are not executed. However, EXECKEY does control where non-executable objects are loaded, and thus affects whether other programs can store into them.

Map sets and partition sets

Map sets are not reentrant (BMS itself updates fields in maps when calculating absolute screen positions). However, map sets should not be modified by application programs; they must be modified only by CICS, which always executes in CICS key. CICS always loads map sets and partition sets into CICS-key storage.

Storage protection exception conditions

If an application program executing in user key attempts to modify CICS-key storage, a protection exception occurs. The protection exception is processed by normal CICS program error handling, and the offending transaction abends with an ASRA abend. The exception condition appears to the transaction as if it had attempted to reference any other protected storage. CICS error handling checks whether the reference is to a CICS-key dynamic storage area (DSA), and sends a message (DFHSR0622) to the console. Otherwise, CICS does not treat the failure any differently from any other ASRA abend. See Dealing with transaction abend codes for more information about the storage protection exception conditions.