Writing global user exit programs

A global user exit program must be written in assembler language and must be quasireentrant. However, if your user exit program calls the XPI, it must be fully reentrant. 2 (For details about coding programs using XPI calls, refer to The user exit programming interface (XPI).)

Register conventions

The following register values are provided on entry to an exit program:

No other register values are guaranteed, and they should not be relied on. The exit program should save and restore any registers that it modifies, using the save area addressed by register 13.

31-bit addressing implications

Access register implications

Using CICS services

The rules governing the use of CICS services in exit programs vary, depending on the exit point from which the exit program is being invoked. The following general rules apply:

Important

Using EXEC CICS and XPI calls in the same exit program

There are a number of exits where you can use both EXEC CICS commands and XPI calls, but you should ensure that there is no conflict in the usage of register 13. To avoid such conflict, use the DATAREG option on the DFHEIENT macro (see XPI register usage for information).

For an example of how to use EXEC CICS commands and XPI calls in the same global user exit program, see Appendix F. The example program for the XTSEREQ global user exit, DFH$XTSE

Start of change

Using channels and containers

Global user exit programs cannot access channels and containers created by application programs. They can, however, create their own channels and pass them to programs which they call.

For information about channels and containers, see the CICS Application Programming Guide.

End of changeStart of change

Assembler programs and LEASM

Assembler programs translated with the LEASM option cannot be used as global user exit programs.

LEASM is used to produce Language Environment® conforming main programs in assembler. For information about the LEASM translator option, see the CICS Application Programming Guide.

End of change

Using EDF with global user exits

If you use the Execution Diagnostic Facility (EDF) to debug your applications, you must take care when compiling exit programs that issue EXEC CICS commands.

Normally, if an exit program issues EXEC CICS commands, these are displayed by EDF, if the latter is active. They appear between the "Start of Command" and "End of Command" screens for the command that caused the exit to be driven. If you want to suppress the display of EXEC CICS commands issued by your exit program, you must specify the NOEDF option when you translate the program. You should always specify NOEDF for programs in a production environment.

If an exit program that may be invoked during recovery processing issues EXEC CICS commands, you must translate it with the NOEDF option. Failure to do so may cause EDF to abend.

The global work area

When you enable an exit program, you can ask CICS to provide a global work area for the exit program. An exit program can have its own global work area, or it can share a work area that is owned by another exit program. Note that the work area is associated with the exit program rather than with the exit point. For ease of problem determination, the global work area should be shared only by exit programs that are invoked from the same management module or domain. The address and length of the global work area are addressed by parameters UEPGAA and UEPGAL of the DFHUEPAR parameter list, which is described in DFHUEPAR standard parameters. If a user exit program does not own a global work area, UEPGAA is set to zero.

Application programs can communicate with user exit programs that use or share the same global work area. The application program uses the EXEC CICS EXTRACT EXIT command to obtain the address and length of the global work area.

A work area is freed only when all of the exit programs that use it are disabled. For examples of how to use a global work area, see the sample global user exit programs. They are listed in Sample global user exit programs.

Making trace entries

If tracing is active, an entry in the CICS trace table can be made immediately before and immediately after the execution of an exit program. To specify that these entries are to be made, use the UE option of either:

For global user exits in domains, extra trace calls giving more information are also available if you have set the AP option of EXEC CICS SET TRACETYPE to level 1 or 2. For information about trace entries, refer to the CICS Problem Determination Guide.

In some cases, when tracing is active, you can also make trace entries from within a user exit program, using the XPI DFHTRPTX TRACE_PUT macro described in The user exit programming interface (XPI). The individual descriptions of the global user exit points show whether the XPI DFHTRPTX macro can be used at each point.

Parameters passed to the global user exit program

The address of a parameter list is passed to the user exit program in register 1. The list contains some standard parameters that are passed to all global user exit programs, and may also contain some exit-specific parameters that are unique to the exit point from which the exit program is being invoked. Not all of the exit points have these extra parameters.

The exit-specific parameters are described with the individual exits in the section List of global user exit points. The standard parameter list is described in the following section.

You can map the parameter list using the DSECT DFHUEPAR, which is generated by the macro instruction

DFHUEXIT TYPE=EP,ID=exit_point_identifier

The ID parameter provides the extra data definitions that you need to map any exit-specific parameters. For example, the macro instruction

DFHUEXIT TYPE=EP,ID=XTDIN

generates the DSECT to map the standard parameters followed by the parameters that are specific to exit point XTDIN in the transient data program. If your exit program is to be invoked at more than one exit point, you can code up to 256 characters of relevant exit identifiers on a single DFHUEXIT macro instruction. For example:

DFHUEXIT TYPE=EP,ID=(XMNOUT,XSTOUT,XTDIN)

If your exit program is to be invoked at every global user exit point, you can code:

DFHUEXIT TYPE=EP,ID=ALL

If your user exit program is to be used both as a global user exit program and as a task-related user exit program, you must code both:

DFHUEXIT TYPE=EP,ID=exit_point_identifier

and:

DFHUEXIT TYPE=RM

(in this order) to generate the DSECTs appropriate to both types of user exit.

If a global user exit program needs to use the DFHRMCAL macro to invoke an external RMI, the DFHRMCAL macro instruction must follow the DFHUEXIT macro.

DFHUEPAR standard parameters

 
DFHUEPAR DSECT
*  STANDARD PARAMETERS
UEPEXN   DS    A      ADDRESS OF EXIT NUMBER
UEPGAA   DS    A      ADDRESS OF GLOBAL WORK AREA
*                      (ZERO = NO WORK AREA)
UEPGAL   DS    A      ADDRESS OF GLOBAL WORK AREA LENGTH
UEPCRCA  DS    A      ADDRESS OF CURRENT RETURN-CODE
UEPTCA   DS    A      RESERVED
UEPCSA   DS    A      RESERVED
UEPEPSA  DS    A      ADDRESS OF REGISTER SAVE AREA
*                      FOR USE BY EXIT PROGRAM
UEPHMSA  DS    A      ADDRESS OF SAVE AREA USED FOR
*                      HOST MODULE'S REGISTERS
UEPGIND  DS    A      ADDRESS OF CALLER'S TASK INDICATORS
UEPSTACK DS    A      ADDRESS OF KERNEL STACK ENTRY
UEPXSTOR DS    A      ADDRESS OF STORAGE FOR XPI PARAMETERS
UEPTRACE DS    A      ADDRESS OF TRACE FLAG

 

UEPEXN
points to a 1-byte binary field whose contents identify the global user exit point from which the exit program is being invoked. You need this information if your exit program can be invoked from more than one exit point.

DFHUEXIT TYPE=EP generates a list of equated values that relate the exit names (exitids) to the exit numbers used internally by CICS to identify the exits. You should always use the exitids, because the exit numbers may change in any future releases of CICS.

UEPGAA
points to the global work area that was provided for the exit program when it was enabled. This is set to zero if no global work area is provided.
UEPGAL
points to a halfword that contains the length of the global work area.
UEPCRCA
points to a halfword that is to contain the return code value from the exit program. When more than one program is called at a user exit, this field contains (on entry to the second and subsequent programs) the return code that was set by the previously invoked program.

Start of changeFor an example of how an exit program can set a different return code from that returned by a previous exit program at the same exit point, see the code snippet in Invoking more than one exit program at a single exit.End of change

UEPTCA
points to fetch-protect storage. Use of this field results in an abend ASRD at execution time.
UEPCSA
points to fetch-protect storage. Use of this field results in an abend ASRD at execution time.
UEPEPSA
points to a save area in which the exit program should store its own registers on entry. When the exit program is entered, register 13 is also pointing to this area. The convention is to save registers 14, 15, 0-12 at offset 12 (decimal) onward.
UEPHMSA
points to the save area containing the registers of the calling module. Values for registers 14, 15, 0-13 are stored in this order from offset 12 (decimal) in this area.

Apart from register 15, which contains the return code value from the exit program, the values in this save area are used by CICS to reload the registers when returning to the calling CICS module. They should not be corrupted.

This address is not passed to global user exit programs invoked from exit points in CICS domains.

UEPGIND
points to a 3-byte field containing indicators for use in AP domain user exits. For non-AP domain user exits, the indicators are always zero.

The first indicator byte can take one of two symbolic values, UEPGANY and UEPGCICS, which you can test to determine whether data locations can be above or below 16MB, and whether the application’s storage is in CICS-key or user-key storage:

UEPGANY
The application can accept addresses above 16MB. If the symbolic value is not UEPGANY, the application must be returned an address below 16MB.
UEPGCICS
The application’s working storage and the task’s life-time storage are in CICS-key storage (TASKDATAKEY=CICS). If the symbolic value is not UEPGCICS, the application’s working storage and the task’s life-time storage are in user-key storage (TASKDATAKEY=USER).

The second and third bytes contain a value indicating the TCB mode of the global user exit program's caller. This is represented in DFHUEPAR as both a two-character code and a symbolic value, as follows:

Table 1. TCB indicators in DFHUEPAR Description
Symbolic value 2-byte code Description
UEPTQR QR The quasi-reentrant mode TCB
UEPTRO RO The resource-owning mode TCB
UEPTCO CO The concurrent mode TCB
UEPTSZ SZ The FEPI mode TCB
UEPTRP RP The ONC/RPC mode TCB
UEPTFO FO The file-owning mode TCB
UEPTSL SL The sockets listener mode TCB
UEPTSO SO The sockets mode TCB
UEPTS8 S8 The secure sockets layer mode TCB
UEPTD2 D2 The CICS-DB2 housekeeping mode TCB
UEPTJ8 J8 The J8 open TCB, used for JVMs that are in CICS key
UEPTJ9 J9 The J9 open TCB, used for JVMs that are in user key
UEPTJM JM The JM open TCB, used for the master JVM that initializes the shared class cache
UEPTL8 L8 Start of changeAn L8 open TCB, used for OPENAPI TRUEs, or OPENAPI programs that are in CICS keyEnd of change
Start of changeUEPTL9End of change Start of changeL9End of change Start of changeAn L9 open TCB, used for OPENAPI programs that are in user keyEnd of change
Start of changeUEPTX8End of change Start of changeX8End of change Start of changeAn X8 open TCB, used for C and C++ programs, compiled with the XPLINK option, that are in CICS keyEnd of change
Start of changeUEPTX9End of change Start of changeX9End of change Start of changeAn X9 open TCB, used for C and C++ programs, compiled with the XPLINK option, that are in user keyEnd of change
UEPSTACK
points to the kernel stack entry. This value must be moved to the exit program’s register 13 before invoking the XPI. For more information, refer to The user exit programming interface (XPI). The storage addressed by this field must not be altered. If it is corrupted, your exit program will have unpredictable effects on your CICS system.
UEPXSTOR
points to a 320-byte area of DFHUEH-owned LIFO storage that the exit program should use when invoking the XPI. For more information, refer to The user exit programming interface (XPI).
UEPTRACE
points to the trace flag, which indicates whether tracing is on in the calling management module or domain. This enables you to control your use of the XPI TRACE_PUT macro in line with the tracing in the CICS module or domain. The XPI TRACE_PUT function should be used only when tracing is on. The trace flag is a single byte, whose top bit is set on when tracing is switched on. You test this setting using the symbolic value UEPTRON. The rest of the byte addressed by UEPTRACE is reserved, and its contents should not be corrupted.

Returning values to CICS

At some exit points, you can influence what CICS does on return from an exit program by supplying a return code value. The return code value must be set in register 15 before leaving the exit program. Character strings equating to valid return code values are provided with the parameter list appropriate for each exit point. Always use the equated values rather than using hard-coded values. For example, at exit XMNOUT in the monitor domain, you are presented with the address of a monitoring record. If you decide in your exit program that this record should not be written to SMF, you can set the return code value UERCBYP (meaning "bypass this record") before returning to CICS, and CICS suppresses the record.

You cannot influence CICS actions in this way at all exit points. If you supply a return code value that is not expected at a particular exit point, the default return code indicating a normal response (usually UERCNORM) is assumed, unless the return code UERCPURG is set (see note below about UERCPURG). You are strongly advised not to let the return code default to the normal response as the result can be unpredictable. The normal response tells CICS to continue processing as if the exit program had not been invoked, and it is a valid option at most global user exit points. The exceptions are shown in the list of return codes provided with each exit description.

The return code currently established for an exit is addressed by parameter UEPCRCA of DFHUEPAR, and it is needed when two or more exit programs are used at one exit. For more information, see Invoking more than one exit program at a single exit.

The return codes that are valid at each of the global user exit points are described in List of global user exit points.

Important

Restrictions on the use of fields as programming interfaces

The CICS Data Areas manual contains definitions of the control block fields that form part of the Product-sensitive and General-use programming interfaces of CICS. Fields that are not defined in the CICS Data Areas manual as either Product-sensitive programming interface or General-use programming interface fields are not intended for your use as part of a CICS programming interface.

Exit programs and the CICS storage protection facility

When you are running CICS with the storage protection facility, there are two points you need to consider for global user exits:

  1. The execution key in which your user exit programs run
  2. The storage key of data storage obtained for your exit programs.

Execution key for global user exit programs

When you are running with storage protection active, CICS always invokes global user exit programs in CICS key. Even if you specify EXECKEY(USER) on the program resource definition, CICS forces CICS key when it passes control to the exit program. However, if a global user exit program itself passes control to another program (via a link or transfer-control command), the program thus invoked is executed according to the execution key (EXECKEY) defined in its program resource definition.

Important

You are strongly recommended to specify EXECKEY(CICS) when defining both global user exit programs and programs to which an exit program passes control.

Data storage key for global user exit programs

The storage key of storage used by global user exit programs depends on how the storage is obtained:

Exit programs and transaction isolation

Start of change

If you are running CICS with the transaction isolation facility (TRANISO=YES), the exit program will inherit the subspace of the application that caused the exit to be called.

End of change

Errors in user exit programs

Because global user exit programs are an extension to CICS code, they are subject to the environment that CICS is running in when they are called. If an error is detected at an exit point, CICS issues messages indicating which exit program was in error, the place in the program at which the error occurred, and the name of the associated exit point. The detection of an error is not guaranteed, because it depends on the CICS environment at the time of error, and on the nature of the error. For example, CICS might not recognize a looping user exit program, since the detection mechanism may have been turned off. Also, an abend in one of the exits XPCABND, XPCTA, or XSRAB may cause CICS to terminate abnormally, because an abend during abend processing causes CICS to terminate.

Exit programs invoked at some exit points (for example, XTSEREQ, XTSEREQC, XICEREQ, XICEREQC, XTDEREQ, or XTDEREQC) can enter a loop by issuing a recursive command (such as a TS command at exit point XTSEREQ). The exits most likely to be affected provide a recursion count parameter, UEPRECUR, that you can use to prevent such loops.

Important

When coding user exit programs, you should bear in mind that the code is executed as an extension of CICS code, rather than as a transaction, and any errors could have disastrous results.

Defining, enabling, and disabling an exit program

When you have written an exit program, you must define it to CICS using the CEDA DEFINE PROGRAM command. (Note that you must specify RELOAD(NO).)

Having defined the exit program, you must also enable it. You do this using the EXEC CICS ENABLE command.3 When you have finished using the exit program, you should disable it, using the EXEC CICS DISABLE command.

Note:
If a global user exit program is enabled before it has been installed and LPA=YES is specified as a system initialization parameter, CICS scans the LPA for the program. If message DFHLD0107I is issued, it means that CICS was unable to find the program in the LPA and is using the DFHRPL version.

For programming information about the EXEC CICS ENABLE and DISABLE commands, see the CICS System Programming Reference manual. For examples of how to enable and disable global user exit programs, see the sample programs listed in topic Sample global user exit programs.

Invoking more than one exit program at a single exit

There may be times when you want to invoke more than one exit program from a single global user exit point. For example, you might have two or more application packages that supply programs for the same CICS exit. Although such programs may work independently, you should note the following points:

Invoking a single exit program at more than one exit

To invoke a single exit program from more than one exit point, you must issue an ENABLE command for each of the exit points. For programming information about how to issue an ENABLE command, see the CICS System Programming Reference manual. Be careful to specify GALENGTH or GAENTRYNAME on only the first ENABLE command, otherwise ‘INVEXITREQ’ may be returned.

Take into account the restrictions that apply to the use of CICS services, because these are dictated by the exit point itself rather than by the exit program. A command that can be issued from one exit point may cause problems when issued from a different exit point.

The global work area is associated with the exit program, rather than with the exit point: this means that the same global work area is used at each of the exit points at which the exit program is invoked.

Making programs threadsafe

All user programs defined by a program resource definition have a concurrency attribute, which can be either QUASIRENT or THREADSAFE (see the CICS Resource Definition Guide for details). By default, global user programs are defined as quasi-reentrant, which means they are given control on the CICS QR TCB (see the CICS Application Programming Guide). If the task under which the global user exit is invoked is executing on an open TCB, and the exit program is defined as quasi-reentrant, CICS switches back to the QR TCB for the execution of the exit program.

To avoid unnecesary TCB switching, you are strongly recommended to make sure that your global user programs conform to threadsafe programming standards. When you are satisfied that your exit programs are threadsafe, ensure that they are defined as CONCURRENCY(THREADSAFE). This is particularly important for exits that are invoked by tasks that are using the CICS DB2® interface and running under an L8 TCB.

If a CICS DB2 application program has been written and defined as threadsafe to obtain the benefits of the CICS open transaction environment (OTE), the benefit is lost if TCB switching is caused by a non-threadsafe exit program. You should pay particular attention to exit programs used on the mainline CICS-DB2 path: exit programs written for the XRMIIN and XRMIOUT exit points need to be made threadsafe, as well as those invoked frequently, such as XEIIN and XEIOUT, which are invoked for every CICS API request.

For more information, see in the CICS Application Programming Guide.

Sample global user exit programs

CICS provides two sets of sample and example global user exit programs:

  1. A set that shows you how to do basic things, such as:
  2. A set of samples for use at specific global user exit points. There are one or more sample programs for each of the following exit points:

The source of all the sample programs, and any associated copy books, is supplied in the CICSTS31.CICS.SDFHSAMP library. You can use the supplied programs as models on which to base your own versions.

Basic sample and example programs

Global work area (GWA) sample exit programs

This set of sample programs shows you how to:

The GWA sample programs and copy books are:

DFH$PCEX
A sample global user exit program, designed to be invoked at the XPCFTCH exit.

CICS also provides copy book DFH$PCGA for use in this sample program.

DFH$ZCAT
A sample global user exit program, designed to be invoked at the XZCATT exit.

CICS also provides copy book DFH$ZCGA for use in this sample program.

DFH$PCPI and DFH$PCPL
DFH$PCPI is designed to be invoked during program list table post initialization (PLTPI) processing, and is described in The DFH$PCPI program.

DFH$PCPL is a dummy program, invoked by DFH$PCPI, that causes the XPCFTCH user exit to be driven.

The DFH$PCPI program

DFH$PCPI consists of three main sections:

  1. Section 1 obtains and processes any parameters passed to DFH$PCPI on the INITPARMS system initialization parameter.
  2. Section 2 shows how to use standard CICS facilities to obtain system information, and make that information available to a global user exit program. It performs the following processing:
  3. Section 3 of DFH$PCPI 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.) It also shows how to use CICS shared storage to overcome the limitation of 32KB on the size of a GWA. The program obtains an area of 64KB below 16MB and an area of 128KB above 16MB (using GETMAIN). The use of shared storage enables the second user exit program (DFH$ZCAT) to use a work area of only 12 bytes below 16MB.

    The section performs the following processing:

Sample program definitions

The following are examples of the RDO definitions required to define the sample programs to the CSD:

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)

DFH$PCPI is designed to be run as a PLT program. If you write a similar program, you should define it in the second part of the PLTPI list (after the PROGRAM=DFHDELIM entry). Information about how to do this is in the CICS Resource Definition Guide.

Example program

As well as the sample programs supplied in source code, there is an example listing, DFH$XTSE, that shows you how to:

DFH$XTSE is listed in topic Appendix F. The example program for the XTSEREQ global user exit, DFH$XTSE.

Sample programs for specific exits

The Basic Mapping Support sample exit program

CICS supplies a sample global user exit program for the Basic Mapping support exits:

DFH$BMXT
A sample global user exit program, designed to be invoked at the XBMIN and XBMOUT exits. The program shows how you can use the exits to modify mapped input and output data.
The data tables sample exit programs

CICS supplies one sample global user exit program for each of the data tables exit points. These are:

DFH$DTAD
A sample global user exit program, designed to be invoked at the XDTAD exit.
DFH$DTLC
A sample global user exit program, designed to be invoked at the XDTLC exit.
DFH$DTRD
A sample global user exit program, designed to be invoked at the XDTRD exit.

DFH$DTAD, DFH$DTLC, and DFH$DTRD are listed in the CICS Shared Data Tables Guide.

The dump domain sample exit program

There is one dump domain sample global user exit program:

DFH$XDRQ
A sample global user exit program, designed to be invoked at the XDUREQ exit.
The enqueue EXEC interface sample exit program

There is one sample global user exit program for the enqueue EXEC interface.

DFH$XNQE
A sample global user exit program, designed to be invoked at the XNQEREQ and XNQEREQC exits. The program demonstrates three ways of adding a SCOPE value to EXEC CICS ENQ and DEQ requests, to make the requests apply to multiple regions within the sysplex.

The file control state program sample exit program

There is one sample global user exit program for the file control state program.

DFH$REQC
A sample user exit program, designed to be invoked at the XFCSREQC exit. It allows you to check VSAM error flags after file requests have been acted upon and, optionally, to write messages and data areas to a system console or a transient data queue. See The DFH$REQC sample global user exit program.
The file control recovery program sample exit programs

CICS provides three sample file control global user exit programs:

DFH$FCBF
A sample exit program designed to be invoked at the XFCBAIL exit for handling backout failures. See DFH$FCBF sample global user exit program.
DFH$FCBV
A sample exit program designed to be invoked at the XFCBOVER exit; it allows you to decide whether to allow an update to be backed out, following a batch update run that has overridden retained locks. See DFH$FCBV sample global user exit program.
DFH$FCLD
A sample exit program designed to be invoked at the XFCLDEL exit, which allows you to perform logical deletion of records from a VSAM ESDS data set or a BDAM data set, during backout. See DFH$FCLD sample global user exit program.

You can define these programs by including the supplied resource group, DFH$FCB, in your startup grouplist, or by using CEDA to install DFH$FCB.

The function-shipping and DPL queue control sample exit program

You can use the XISCONA sample global user exit program to control the queueing of function-shipping and DPL requests:

DFHXIS
A sample global user exit program, designed to be invoked at the XISCONA exit.
The interval control EXEC interface sample exit program

DFH$ICCN
A sample global user exit program, designed to be invoked at the XICEREQ exit. DFH$ICCN is for use in a distributed routing environment, where you want to cancel a previously-issued interval control request but have no way of knowing to which region to direct the CANCEL. For examples of situations which DFH$ICCN is designed to cope with, see the CICS Intercommunication Guide.
The ISC session queue management sample exit program

This sample program implements the same basic function provided by the QUEUELIMIT and MAXQTIME parameters on a connection resource definition. These parameters are passed to the XZIQUE global user program, which can change the way in which these parameters are used:

DFH$XZIQ
A sample global user exit program, designed to be invoked at the XZIQUE exit, which is described in topic XZIQUE exit for managing intersystem queues.

See Sample exit program design for more details.

The log manager domain sample exit program

There is one sample global user exit program for the XLGSTRM exit point:

DFH$LGLS
The sample program shows you how to change some of the parameters--for example, the model log stream name--used by the MVS system logger when it creates a new log stream dynamically. The sample is described in topic The sample program for the XLGSTRM exit, DFH$LGLS.

The message domain sample exit programs

These sample programs show you how to write a program to be invoked at the XMEOUT exit, to do a specific task. For example, the DFH$SXP4 sample program shows you how to use the XMEOUT exit to reroute a console message to a transient data queue.

DFH$SXPn
A set of sample global user exit programs designed to be invoked at the XMEOUT exit (where ‘n’ is 1 through 6).
The terminal-not-known sample exit program

You can use this sample global user exit program to handle terminal-not-known conditions arising from START and ATI requests:

DFHXTENF
A sample global user exit program, designed to be invoked at the XALTENF or XICTENF exit. The sample source code is shown in topic The sample program for the XALTENF and XICTENF exits, DFHXTENF.
The transaction-abend sample exit program

There is one sample global user exit program for the XPCTA exit point:

DFH$PCTA
This sample global user exit program is designed to be invoked at the XPCTA exit, to test whether the abend was caused by a storage protection exception condition. It is described in topic The sample XPCTA global user exit program, DFH$PCTA.

Start of change
The HTTP client open exit programs

These sample programs are for use at the Web domain exit, XWBOPEN. The XWBOPEN exit is invoked during processing of EXEC CICS WEB OPEN and EXEC CICS INVOKE WEBSERVICE commands. It is used in making HTTP client requests from CICS as an HTTP client, which is a facility provided by CICS Web support.

The sample programs show you how to set up proxy server information or a security policy in a global work area. For example, if all the requests from your CICS system should use a single proxy server, you can specify the proxy server name as an initialization parameter. If you use a number of proxy servers or want to apply a security policy to different host names, you could load or build a table that matches host names to appropriate proxy servers or marks them as barred, which could then be used as a look-up table during processing of the EXEC CICS WEB OPEN command.

DFH$WBPI
This sample global user exit program is designed to be specified in the PLTPI and invoked during CICS initialization. It initializes the global work area with a proxy server name supplied by the INITPARM system initialization parameter, and enables program DFH$WBEX at exit XWBOPEN.
DFH$WBEX
This sample global user exit program is designed to check the host name specified on the EXEC CICS WEB OPEN command, and make any host name starting with www use a proxy server if a proxy server name is specified in the global work area.
DFH$WBGA
This is a copybook to map the global work area used by the DFH$WBPI and DFH$WBEX samples.

End of change

Related concepts
Overview -- what is a global user exit?
Overview of the XPI
Global user exit XPI examples, showing the use of storage
Related tasks
Making an XPI call
Related reference
List of global user exit points
The XPI functions

2.
A "reentrant" program is coded to allow one copy of itself to be used concurrently by several tasks; it does not modify itself while running. A "quasireentrant" program is serially reusable by different tasks. When it receives control it must be in the same state as when it relinquished control. Such a program can modify itself while running, and is therefore not fully reentrant.
3.
Exit programs for exits in the user log record recovery program and the file control recovery control program can also be enabled using the TBEXITS system initialization parameter.

[[ Contents Previous Page | Next Page Index ]]