Global work area sample exit programs: DFH$PCEX, DFH$PCPI, DFH$PCPL, and DFH$ZCAT

The global work area (GWA) sample exit programs and copy books provide examples of how to work with global work areas and global user exits.

The GWA sample exit programs show you how to:

Enable a global user exit program and allocate a GWA.
Obtain the address of an exit program's GWA.
Access CICS® system information, and make that information available to other global user exit programs.
Share a GWA between global user exit programs, thereby making the information it contains available to more than one program, and overcoming limitations on the size of GWAs.
Access information held in a global user exit program's GWA.

The GWA sample exit programs include:

DFH$PCEX: DFH$PCEX is designed to be invoked at the XPCFTCH exit. CICS also provides copy book DFH$PCGA for use in this sample program.
DFH$PCPI: DFH$PCPI is designed to be invoked during program list table post initialization (PLTPI) processing. DFH$PCPI provides an example of how to work with global work areas.
DFH$PCPL: DFH$PCPL is a dummy program, invoked by DFH$PCPI, that causes the XPCFTCH user exit to be driven.
DFH$ZCAT: This sample exit program is designed to be invoked at the XZCATT exit. CICS also provides copy book DFH$ZCGA for use in this sample program.

DFH$PCPI is explained in details to help you understand the demonstration.

About DFH$PCPI

Consisting of three main sections, DFH$PCPI does the following processing:

Section 1

Obtains and processes any parameters passed to DFH$PCPI on the INITPARMS system initialization parameter.

Section 2

Shows how to use standard CICS facilities to obtain system information, and make that information available to a global user exit program.

Section 2 performs the following processing:

Uses the EXEC CICS ENABLE PROGRAM command to enable the XPCFTCH sample user exit program, DFH$PCEX, and allocate it a global work area.
Uses the EXEC CICS EXTRACT EXIT command to obtain the address of the DFH$PCEX global work area.
Obtains CICS system information, and places it in the DFH$PCEX global work area. The information obtained includes:
- Job name
- APPLID
- Sysid
- CICS release
- Date in various formats, including DATFORM
- Address of the common work area (CWA)
- CICS startup type (COLD, WARM)
Most of the preceding information is obtained using EXEC CICS API commands such as follows:
- INQUIRE SYSTEM
- ASSIGN
- ADDRESS
- ASKTIME
- FORMATTIME
Uses the START option of the EXEC CICS ENABLE PROGRAM command to make DFH$PCEX available for execution. This causes DFH$PCEX to be driven for all LINK and XCTL commands.
Links to the dummy program, DFH$PCPL, in order to drive DFH$PCEX.
Uses the STOP option of the EXEC CICS DISABLE PROGRAM command to make DFH$PCEX unavailable for execution. Note that this leaves the DFH$PCEX global work area still allocated and accessible through the EXEC CICS EXTRACT EXIT command.

Section 3

Shows how to share the system information in an exit program's global work area with other exit programs. In doing so it demonstrates how application programs can access the same information by means of the EXEC CICS EXTRACT EXIT command. This section also shows how to use CICS shared storage to overcome the limitation of 32 KB on the size of a global work area. The program uses GETMAIN to obtain an area of 64 KB in 24-bit storage (below 16 MB) and an area of 128 KB in 31-bit storage (above 16 MB). The use of shared storage enables the second user exit program (DFH$ZCAT) to use a work area of only 12 bytes in 31-bit storage.

Section 3 performs the following processing:

Uses EXEC CICS ENABLE to enable the DFH$ZCAT user exit program and allocate it a global work area.
Uses EXEC CICS EXTRACT EXIT to obtain the address of the DFH$ZCAT global work area.
Stores the address of the DFH$PCEX global work area in the DFH$ZCAT global work area.
Uses GETMAIN to obtain the shared 24-bit and 31-bit storage, and stores the addresses in the DFH$ZCAT global work area.

Setting up the GWA sample exit programs

RDO provides the traditional CICS way of defining resources to CICS systems. In this case, RDO defines the sample programs to the CSD.

Here are some examples of RDO sample program definitions:

DEFINE PROGRAM(DFH$PCEX) GROUP(EXITGRP)
        LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL)
        USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY)
        EXECKEY(CICS)
 
DEFINE PROGRAM(DFH$PCPI) GROUP(EXITGRP)
        LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL)
        USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY)
        EXECKEY(CICS)
 
DEFINE PROGRAM(DFH$PCPL) GROUP(EXITGRP)
        LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL)
        USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY)
        EXECKEY(CICS)
 
DEFINE PROGRAM(DFH$ZCAT) GROUP(EXITGRP)
        LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL)
        USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY)
        EXECKEY(CICS)

Extending DFH$PCPI

DFH$PCPI is designed to be run as a PLT program. If you write a similar program, you must define it in the second part of the PLTPI list (after the PROGRAM=DFHDELIM entry). For instructions, see Entries in program list table: DFHPLT TYPE=ENTRY.