Program control program exits XPCREQ, XPCERES, XPCREQC, XPCFTCH, XPCHAIR, XPCTA, and XPCABND

XPCREQ, XPCERES, and XPCREQC

XPCREQ
XPCREQ is invoked by the EXEC interface program before a link request is processed. If the request is a distributed program link, the XPCREQ exit is driven on both sides of the link; that is, in both the client and the server regions. The exit program is passed the address of the application’s parameter list (in UEPCLPS), and can modify this as required. For example, you can use this exit to modify the SYSID at the time of a distributed program link request. One way you can achieve this is to write an application program to manage a list of SYSIDs in a global work area (GWA). The global user exit program can obtain access to the GWA, and use the information stored there to redirect DPL requests.
Notes:
  1. The attributes of the local PROGRAM definition are not passed to the exit program. If the exit program needs to know, for example, the value of the REMOTESYSTEM attribute, it can issue an EXEC CICS INQUIRE PROGRAM command.
  2. If you use XPCREQ to change the target SYSID, remember that:
    1. If SYSID specifies a remote region, no reference is made to the local PROGRAM resource definition. Thus, for example, in the remote region the program runs under the transid of the transaction in the client region, not under the TRANSID specified on the PROGRAM definition in the client region.
    2. If SYSID specifies the local region, CICS treats the link request as if SYSID was not specified. The local PROGRAM definition is honored.
    3. The XPCREQ exit is invoked by internal requests made by CICS code, as well as by requests made by applications.
XPCERES
XPCERES is invoked by the EXEC interface program before CICS processes either of the following kinds of dynamically-routed link request:

Note that XPCERES is invoked:

The XPCERES exit is not invoked:

You can use XPCERES to check that all resources required by the linked-to program are available on the target region. If, for example, the program is disabled, or a required file is missing, your exit program can give the dynamic routing program the opportunity to route the request to a different region. To do this, set a return code of UERCRESU. This causes CICS to:

  1. Set the DYRERROR field of the routing program’s communications area to 'F'--resource unavailable.
  2. Reinvoke the routing program, on the routing region, for route selection failure.
  3. Return a RESUNAVAIL condition on the EXEC CICS LINK command executed by the mirror on the target region. (This condition is not returned to the application program.)

CICS ignores any changes made by the exit program to the values of any of the exit parameters. Your exit program can set a return code, but not change any parameters.

For guidance information about dynamically routing DPL requests, see the CICS® Intercommunication Guide. For guidance information about dynamically routing Link3270 bridge requests, see the CICS External Interfaces Guide. For programming information about writing a dynamic routing program to route DPL requests, see Routing DPL requests dynamically. For programming information about writing a dynamic routing program to route Link3270 bridge requests, see Routing bridge requests dynamically.

XPCREQC
XPCREQC is invoked after a link request has completed. You can use this exit to pass back a response to the application via the EIBRESP or EIBRESP2 fields. Such responses could be used to keep status information about a link request up-to-date. For example, if a link request fails because a connection is unavailable, XPCREQC could set EIBRESP=500 (a response code not used by CICS) to indicate the failure, enabling the application, in conjunction with the other exit, XPCREQ, to determine a suitable course of action.
Note:
The XPCREQC exit is invoked by internal requests made by CICS code, as well as by requests made by applications.

Exit XPCREQ

When invoked
By the EXEC interface program before a link request is processed.
Exit-specific parameters
UEPCLPS
Address of the command parameter list.
UEPPCTOK
Address of a 4-byte token to be passed to XPCREQC. This allows you, for example, to pass a work area to exit XPCREQC.
UEPRCODE
Address of a 6-byte hexadecimal copy of EIBRCODE.
UEPRECUR
Address of a halfword recursion counter. The counter is set to 0 when the exit is first invoked, and is incremented for each recursive call.
UEPRESP
Address of a 4-byte copy of EIBRESP.
UEPRESP2
Address of a 4-byte copy of EIBRESP2.
UEPTSTOK
Address of a 4-byte token that is valid throughout the life of a task. See Using the task token UEPTSTOK.
UEPRSRCE
Address of an 8-character copy of the EIB resource value, EIBRSRCE.
Return codes
UERCBYP
Program control is to ignore the request.
UERCNORM
Continue processing.
UERCPURG
Task purged during XPI call.
XPI calls
All can be used.

Although the exit permits the use of XPI GETMAIN and FREEMAIN calls, we recommend that you use the EXEC CICS GETMAIN and FREEMAIN commands instead.

API and SPI calls
All can be used, except for:

Exit XPCERES

When invoked
By the EXEC interface program, before processing of a program link or Link3270 bridge request that has been dynamically routed to this region, where the routing region supports the "resource unavailable" condition.
Exit-specific parameters
Important

CICS ignores any changes made by the exit program to the values of any of the exit parameters. Your exit program can set a return code, but not change any parameters.

UEPCLPS
Address of the command parameter list.
UEPPCTOK
Address of a 4-byte token to be passed to XPCREQC.
UEPRCODE
Address of a 6-byte hexadecimal copy of EIBRCODE.
UEPRECUR
Address of a halfword recursion counter. Because the XPCERES exit can never be called recursively in the same transaction, the value of this field is always 0.
UEPRESP
Address of a 4-byte copy of EIBRESP.
UEPRESP2
Address of a 4-byte copy of EIBRESP2.
UEPTSTOK
Address of a 4-byte token that is valid throughout the life of a task. See Using the task token UEPTSTOK.
UEPRSRCE
Address of an 8-character copy of the EIB resource value, EIBRSRCE.
Return codes
UERCNORM
Continue processing.
UERCPURG
Task purged during XPI call.
UERCRESU
A required resource is unavailable. Setting this value causes CICS to reject the routed request, and to return a value of 'F' (resource unavailable) in the DYRERROR field of the routing program's communications area.
XPI calls
All can be used.

Although the exit permits the use of XPI GETMAIN and FREEMAIN calls, we recommend that you use the EXEC CICS GETMAIN and FREEMAIN commands instead.

API and SPI calls
All except EXEC CICS SHUTDOWN and EXEC CICS XCTL can be used.

Exit XPCREQC

When invoked
On completion of a program control link request.
Exit-specific parameters
UEPCLPS
Address of the command parameter list.
UEPPCTOK
Address of a 4-byte token passed from XPCREQ. This allows XPCREQ to, for example, pass a work area to XPCREQC.
UEPRCODE
Address of a 6-byte hexadecimal copy of EIBRCODE.
UEPRECUR
Address of a halfword recursion counter. The counter is set to 0 when the exit is first invoked, and is incremented for each recursive call.
UEPRESP
Address of a 4-byte copy of EIBRESP.
UEPRESP2
Address of a 4-byte copy of EIBRESP2.
UEPTSTOK
Address of a 4-byte token that is valid throughout the life of a task. See Using the task token UEPTSTOK.
UEPRSRCE
Address of an 8-character copy of the EIB resource value, EIBRSRCE.
Start of changeUEP_PC_REMOTE_SYSTEMEnd of change
Start of changeIf the request is to be sent to a remote region, is the address of an area containing the 4-byte name of the remote region. (The remote region may have been specified by, for example, the SYSID option of the EXEC CICS LINK command, function shipping, work-load management, or the REMOTESYSTEM option of the PROGRAM definition.)

If the request is to be executed on the local region, this parameter is the address of a 4-byte area containing blanks.

End of change
Start of changeUEP_PC_REMOTE_NAMEEnd of change
Start of changeIf the program is to be executed in a remote system, is the address of an area containing the name of the program, as it is known in the remote system.End of change
Return codes
UERCNORM
Continue processing.
UERCPURG
Task purged during XPI call.
XPI calls
All can be used.

Although the exit permits the use of XPI GETMAIN and FREEMAIN calls, we recommend that you use the EXEC CICS GETMAIN and FREEMAIN commands instead.

API and SPI calls
All can be used, except for:
Note:
Take care when issuing recursive commands not to cause a loop. For example, it is your responsibility to avoid entering a loop when a program control request is issued from the XPCREQ or XPCREQC exits.

Use of the recursion counter UEPRECUR is recommended.

The command parameter structure

The command parameter structure consists of a series of addresses. The first address points to the EXEC interface descriptor (EID), which consists of a bit string that describes the type of request and identifies each keyword specified with the request. The remaining addresses point to pieces of data associated with the request; for instance, the second address always points to the program name. You can examine the parameters in the list to determine the values of the keywords. You can also modify values of parameters specified on the request. For example, you could change the name of the program involved in the request, or add the SYSID to route the link request to a remote system.

End of parameter list indicator

The high-order bit is set on in the last address set in the parameter list to indicate that it is the last one in the list. On return from your user exit program, CICS scans the parameter list for the high-order bit to find the last parameter. Therefore, if you modify the length of the parameter list, you must also reset the high-order bit to indicate which is the new last address.

For example, if the parameter list specifies only the first two addresses (PC_ADDR0, the address of the EID, and PC_ADDR1, the address of the name of the program named in the link request), the high-order bit is set on in PC_ADDR1. If you extend the parameter list by setting the address of a SYSID in PC_ADDR7, you must unset the high-order bit in PC_ADDR1 and set it on in PC_ADDR7 instead.

The original parameter list, as it was before XPCREQ was invoked, is restored after the completion of XPCREQC. It follows that EDF will display the original command before and after execution: EDF will not display any changes made by the exit.

The UEPCLPS exit-specific parameter

The UEPCLPS exit-specific parameter is included in both exit XPCREQ and exit XPCREQC. It is the address of the command-level parameter structure. Start of changeThe command-level parameter structure contains 11 addresses, PC_ADDR0 through PC_ADDRAEnd of change. It is defined in the DSECT PC_ADDR_LIST, which you should copy into your exit program by including the statement COPY DFHPCEDS.

The command-level parameter list is made up as follows:

PC_ADDR0
is the address of a 7-byte area called the EXEC interface descriptor (EID), which is made up as follows:
PC_GROUP
Always X'0E', indicating that this is a program control request.
PC_FUNCT
One byte which defines the type of request, which for XPCREQ and XPCREQC is always X'02', indicating a LINK request.
PC_BITS1
Existence bits that define which keywords that contain values were specified. To obtain the value associated with a keyword, you need to use the appropriate address from the command-level parameter list. Before using this address you must check the associated existence bit to ensure that the address is valid. If the existence bit is set off, the keyword was not specified in the request and the address should not be used. The symbolic and hexadecimal values of the existence bits are as follows:
PC_EXIST1 (X'80 ')
Set if the request contains the keyword PROGRAM. If set, PC_ADDR1 is meaningful. (This bit should always be set for a LINK request.)
PC_EXIST2 (X'40 ')
Set if the request specifies the COMMAREA parameter. If set, PC_ADDR2 is meaningful.
PC_EXIST3 (X'20 ')
Set if the request specifies the LENGTH parameter. If set, PC_ADDR3 is meaningful.
PC_EXIST4 (X'10 ')
Set if the request specifies the INPUTMSG parameter. If set, PC_ADDR4 is meaningful.
PC_EXIST5 (X'08 ')
Set if the request specifies the INPUTMSGLEN parameter. If set, PC_ADDR5 is meaningful.
PC_EXIST6 (X'04 ')
Set if the request specifies the DATALENGTH parameter. If set, PC_ADDR6 is meaningful.
PC_EXIST7 (X'02 ')
Set if the request specifies the SYSID parameter. If set, PC_ADDR7 is meaningful.
PC_EXIST8 (X'01 ')
Set if the request specifies the TRANSID parameter. If set, PC_ADDR8 is meaningful.
Start of changePC_BITS2End of change
Start of changeStart of changeOne byte containing one of the following values:
PC_EXIST9 (X'80')
Not used.
PC_EXISTA (X'40')
Set if the request specifies the CHANNEL parameter. If set, PC_ADDRA is meaningful.
End of changeEnd of change
Start of changePC_EIDOPT4End of change
Start of changeNot used by program control.End of change
PC_EIDOPT5
Not used by program control.
PC_EIDOPT6
Indicates whether the request specifies the SYNCONRETURN option. If it does, X'80' is set.
PC_ADDR1
is the address of an 8-byte area containing the program name from the PROGRAM parameter.
PC_ADDR2
is the address of the COMMAREA data.
PC_ADDR3
is the address of a 2-byte area containing the length of the COMMAREA, as a half-word binary value.
PC_ADDR4
is the address of the INPUTMSG data.
PC_ADDR5
is the address of a 2-byte area containing the length of the INPUTMSG, as a half-word binary value.
PC_ADDR6
is the address of a 2-byte area containing the length specified on the DATALENGTH parameter, defining how much data is to be sent from the COMMAREA. The length is held as a half-word binary value.
PC_ADDR7
is the address of the 4-byte name of the remote system the LINK request is to be shipped to, as specified on the SYSID parameter.
PC_ADDR8
is the address of the 4-byte name of the mirror transaction to be attached in the remote system, as specified on the TRANSID parameter.
Start of changePC_ADDR9End of change
Start of changeis not used.End of change
Start of changePC_ADDRAEnd of change
Start of changeis the address of the 16-byte channel name, as specified on the CHANNEL parameter.End of change

Modifying fields in the command parameter structure

Some fields that are passed to program control are used as input to the request, some are used as output fields, and some are used for both input and output. The method your user exit program uses to modify a field depends on the usage of the field.

Modifying input fields

The correct method of modifying an input field is to create a new copy of it, and to change the address in the command parameter list to point to your new data.

Note:
You must never modify an input field by altering the data that is pointed to by the command parameter list. To do so would corrupt storage belonging to the application program and could cause a failure when the program attempted to reuse the field.
Modifying output fields

The technique described in Modifying input fields is not suitable for modifying output fields. (The results would be returned to the new area instead of the application’s area, and would be invisible to the application.)

An output field is modified by altering the data that is pointed to by the command-level parameter list. In the case of an output field you can modify the application’s data in place, because the application is expecting the field to be modified anyway.

Modifying the EID

It is not possible to modify the EID to make major changes to requests. It is not possible, for example, to change a LINK request to a different type of Program Control request.

However, you can make minor changes to requests, such as to turn on the existence bit for SYSID so that the request can be changed into one that is shipped to a remote system.

The list that follows shows the bits in the EID that can be modified. Any attempt to modify any other part of the EID is ignored.

PC_BITS1
X'40'
The existence bit for the COMMAREA
X'20'
The existence bit for LENGTH
X'10'
The existence bit for INPUTMSG
X'08'
The existence bit for INPUTMSGLEN
X'04'
The existence bit for DATALENGTH
X'02'
The existence bit for SYSID
X'01'
The existence bit for TRANSID.
Start of changePC_BITS2End of change
Start of change
X'40'
The existence bit for CHANNEL.
End of change
PC_EIDOPT5
Not used for a PC link request.

Bits in the EID should be modified in place. You should not modify the pointer to the EID. (Any attempt to do so is ignored by CICS.)

The EID is reset to its original value before return to the application program. That is, changes made to the EID are retained for the duration of the program control request only.

Your user exit program is prevented from making major changes to the EID.

Using the program control request token, UEPPCTOK

UEPPCTOK provides the address of a 4-byte area that you can use to pass information between the XPCREQ and XPCREQC user exits for the same program control request. For example, the address of a piece of storage obtained by the XPCREQ user exit, which has to be freed by the XPCREQC user exit, can be passed in the UEPPCTOK field.

Using the task token UEPTSTOK

UEPTSTOK provides the address of a 4-byte area that you can use to pass information between successive program control requests in the same task. (By contrast, UEPPCTOK is usable only for the duration of a single program control request, because its contents may be destroyed at the end of the request.) For example, if you need to pass information between successive invocations of the XPCREQ exit, UEPTSTOK provides a means of doing this.

The EIB

Copies of EIBRSRCE, EIBRCODE, EIBRESP, and EIBRESP2 are passed to the exit, so that you can:

You can update the copies of EIBRSRCE, EIBRCODE, EIBRESP and EIBRESP2 that you are given in the parameter list. Program Control copies your values into the real EIB after the completion of XPCREQC; or if you specify a return code of ‘bypass’ in XPCREQ.

You must set valid program control responses. You must set all three of EIBRCODE, EIBRESP and EIBRESP2 to a consistent set of values, such as would be set by Program Control to describe a valid completion. Program Control does not police the consistency of EIBRCODE, EIBRESP, and EIBRESP2. To aid you in setting the values of EIBRCODE, EIBRESP, and EIBRESP2, the values used by Program Control are specified in DFHPCEDS.

Example of how XPCREQ and XPCREQC can be used

XPCREQ and XPCREQC can be used for a variety of purposes. One example of a possible use is given below.

In this example, XPCREQ and XPCREQC are used to route LINK requests to a number of different CICS regions to provide a simple load balancing mechanism. The example shows only the capabilities of the exits; it is not intended to indicate an ideal way of achieving the load balancing function. For the purpose of this example, it is assumed that a global work area (GWA) already exists, and that it contains a list of available SYSIDs together with a count of the number of LINK requests currently being processed by each SYSID.

In XPCREQ

  1. Scan the global work area (GWA) to locate a suitable CICS region - for example, the region currently processing the least number of LINK requests.
  2. Having decided which system to route the request to, increment the use count for this system.
  3. Obtain a 4-byte area in which to store the SYSID for this request (this can be allocated from the GWA to avoid issuing a GETMAIN). If the area is obtained by issuing a GETMAIN, set UEPPCTOK to the address of the storage obtained.
  4. Set PC_ADDR7 to the address of the 4-byte area.
  5. If setting PC_ADDR7 now makes it the last address, set the high-order bit in the address, and unset the high-order bit in what was previously the last address.
  6. Set the X'02' existence bit on in PC_BITS1 to indicate that a SYSID is specified.
  7. Return to CICS.
In XPCREQC

  1. Scan the global work area (GWA) and locate the entry for the CICS region specified in the SYSID parameter.
  2. Decrement the use count for this system.
  3. If a GETMAIN was issued in XPCREQ to obtain an area to hold the SYSID, issue a FREEMAIN for the address held in UEPPCTOK.
  4. Return to CICS.

Exit XPCFTCH

XPCFTCH is invoked before a PPT-defined program (including internal CICS modules) receives control, which could be because it is the first program in a transaction, or as a result of a LINK, XCTL, or HANDLE ABEND PROGRAM request. You can use this exit to modify the entry address used when linking to the program. If the exit sets a return code of zero, or a modified address of zero, the entry address of the original application program is used.

Start of changeWhen XPCFTCH is invoked for a C or C++ program which was compiled with the XPLINK option, a flag is set to indicate that any modification of the entry point address that might be made by the user exit, is ignored.End of change

The exit is intended to allow you to pass control to an assembler application program or routine before the original program is invoked. This assembler program, after it has finished its processing, should pass control back to the entry point of the original program using a branch instruction. You should not use the exit to cause a program to be invoked instead of the original program. If you do so, the results are unpredictable.

If a modified entry address is supplied, the program that is invoked receives control in the execution key that the original application program would have received control in--that is, as specified on the EXECKEY option of the original program’s resource definition.

When invoked
Before an application program receives control.
Exit-specific parameters
UEPPCDS
Address of a storage area that contains program- and terminal-related information, and that can be mapped using the DSECT DFHPCUE. When XPCFTCH is invoked, the following DFHPCUE fields are significant:
PCUE_CONTROL_BITS
1-byte flag field.
  • A setting of PCUECBTE indicates that the transaction is linked to a terminal.
  • A setting of PCUENOTX (X'40') indicates that the program is not command level.
  • Start of changeA flag, PCUE_NO_MODIFY, in PCUE_CONTROL_BITS indicates that a modified entry address is not supported. When set, any return code of UERCMEA from XPCFTCH is ignored. This flag is set by CICS before invoking XPCFTCH for C and C++ programs compiled with the XPLINK option.End of change
  • Start of changeA setting of PCUE_REAL (X'20') indicates that a real entry point is set in PCUE_REAL_ENTRY.End of change
PCUE_TASK_NUMBER
3-character packed decimal field containing the task number.
PCUE_TRANSACTION_ID
4-character field containing the ID of the original transaction. Note that this may differ from the current transaction ID.
PCUE_TERMINAL_ID
4-character field containing the terminal ID (if any).
PCUE_PROGRAM_NAME
8-character field containing the name of the program that is to receive control.
PCUE_PROGRAM_LANGUAGE
3-character field containing the language of the program that is to receive control.
PCUE_LOAD_POINT
The program’s load point.
PCUE_ENTRY_POINT
The program’s entry point.
PCUE_PROGRAM_SIZE
Fullword containing the size of the program, in bytes.
PCUE_COMMAREA_ADDRESS
Start of changeAddress of the program’s communication area, if the program has one.End of change
PCUE_COMMAREA_SIZE
Start of changeFullword containing the length of the program’s communication area, if the program has one.End of change
PCUE_LOGICAL_LEVEL
Fullword containing the number of chained DFHRSADS blocks (that is, logical level).
PCUE_BRANCH_ADDRESS
Fullword. Use this field to supply an alternative entry address. Set the top bit to specify that the alternative program is to run AMODE (31).
Start of changePCUE_REAL_ENTRYEnd of change
Start of changeFrom z/OS 1.7 onwards, this field provides the real entry point for Language Environment conforming programs. Previously only PCUE_ENTRY_POINT was available to you, but for Language Environment conforming programs this did not contain the entry point that you needed to know about.
Note:
With z/OS 1.7, this field provides a solution to the problem raised by APAR PQ43992.
End of change
Start of changePCUE_CHANNEL_NAMEEnd of change
Start of changeAddress of a 16-byte field containing the name of the channel with which the application program is to be invoked (that is, the program’s current channel). If there is no channel, this field is set to blanks.End of change
Return codes
UERCNORM
Continue processing.
UERCPURG
Task purged during XPI call.
UERCMEA
Entry address has been modified.
XPI calls
All can be used.

The sample XPCFTCH global user exit program, DFH$PCEX

Note that there is a CICS-supplied sample exit program, DFH$PCEX, that is designed to be driven by the XPCFTCH exit. For more information about DFH$PCEX, see Sample global user exit programs.

Exit XPCHAIR

XPCHAIR is invoked before a HANDLE ABEND LABEL routine is given control. Note that this occurs only when a program abend causes a branch to an internal abend routine. (When the HANDLE ABEND request specifies PROGRAM, exit XPCFTCH is invoked, as described above.) You can use this exit to supply an alternative handle-abend address. If the exit sets a return code of zero, or an alternative address of zero, CICS passes control to the application program’s specified internal routine.

If a modified entry address is supplied:

When invoked
Before a HANDLE ABEND routine is given control.
Exit-specific parameters
UEPPCDS
Address of a storage area that contains program- and terminal-related information, and that can be mapped using the DSECT DFHPCUE. When XPCHAIR is invoked, the following DFHPCUE fields are significant:
PCUE_CONTROL_BITS
1-byte flag field. A setting of PCUECBTE indicates that the transaction is linked to a terminal.
PCUE_TASK_NUMBER
3-character packed decimal field containing the task number.
PCUE_TRANSACTION_ID
4-character field containing the transaction ID.
PCUE_TERMINAL_ID
4-character field containing the terminal ID (if any).
PCUE_PROGRAM_NAME
8-character field containing the name of the program that issued the HANDLE ABEND LABEL command.
PCUE_LOGICAL_LEVEL
Fullword containing the number of chained DFHRSADS blocks (that is, logical level).
PCUE_BRANCH_ADDRESS
Fullword. Use this field to supply the address of an alternate abend routine. Set the top bit to specify that the alternate abend routine is to run AMODE (31).
UEPTACB
Address of the transaction abend control block (TACB) for the abend. If the abend occurred because of a program check, the information in the TACB includes:
  • The program status word (PSW)
  • The registers at the time of the abend
  • Details of the subspace and access registers current at the time of the abend.
You can map the TACB using the DFHTACB TYPE=DSECT macro.
Return codes
UERCNORM
Continue processing.
UERCPURG
Task purged during XPI call.
UERCMEA
The address of an alternate abend routine has been supplied.
XPI calls
All can be used.

Exit XPCTA

XPCTA is invoked immediately after a transaction abend, and before any processing that might modify the existing environment so that the task could not be resumed. You can use it to:

If a resume address is passed back, registers 0 through 13 and 15 are restored to their values at the time of the abend. Register 14 is used to branch to the resume address. If the exit sets a return code of zero, or a resume address of zero, CICS processes the abend.

Note:
If the transaction abend occurs as a result of a program check or an operating system abend:
  1. It is possible that the XDUREQ dump domain exit may be invoked before XPCTA. (For details of XDUREQ, see topic Exit XDUREQ.)
  2. If a resume address is passed back, registers 0 through 15 are restored to their value at the time of the abend. The PSW is used to branch to the resume address.

Start of changeA resume address, normally obtained from the return code UERCMEA from XPCTA, is ignored for C and C++ programs compiled with the XPLINK option.End of change

When invoked
After an abend and before the environment is modified.
Exit-specific parameters
UEPPCDS
Address of a storage area that contains program- and terminal-related information, and that can be mapped using the DSECT DFHPCUE. When XPCTA is invoked, the following DFHPCUE fields are significant:
PCUE_CONTROL_BITS
1-byte flag field. A setting of PCUECBTE indicates that the transaction is linked to a terminal.

Start of changeA flag, PCUE_NO_RESUME, in PCUE_CONTROL_BITS indicates that a resume address is not supported. When set, any return code of UERCMEA from XPCTA is ignored. This flag is set by CICS before invoking XPCTA for C and C++ programs compiled with the XPLINK option.End of change

PCUE_TASK_NUMBER
3-character packed decimal field containing the task number.
PCUE_TRANSACTION_ID
4-character field containing the transaction ID.
PCUE_TERMINAL_ID
4-character field containing the terminal ID (if any).
PCUE_PROGRAM_NAME
8-character field containing the name of the failing program.
PCUE_LOGICAL_LEVEL
Fullword containing the number of chained DFHRSADS blocks (that is, logical level).
PCUE_BRANCH_ADDRESS
Fullword. You can use this field to supply a resume address. Set the top bit to specify that the resumed task is to run AMODE (31).
PCUE_BRANCH_EXECKEY
If storage protection is active, you can use this 1-byte field to specify the execution key of the resumed task. The possible values are:
PCUE_BRANCH_USER
User key
PCUE_BRANCH_CICS
CICS key.

If storage protection is active, and you do not specify a value, the resumed task executes in User key.

If storage protection is not active, the resumed task executes in CICS key.

UEPTACB
Address of the transaction abend control block (TACB) for the abend. If the abend occurred because of a program check, the information in the TACB includes:
  • The program status word (PSW)
  • The registers at the time of the abend
  • The execution key at the time of the abend
  • Details of the subspace and access registers current at the time of the abend.
You can map the TACB using the DFHTACB TYPE=DSECT macro.
Return codes
UERCNORM
Continue processing.
UERCPURG
Task purged during XPI call.
UERCMEA
A resume address has been supplied.
XPI calls
All can be used.

The sample XPCTA global user exit program, DFH$PCTA

The sample program tests whether the abend was caused by the application program trying to overwrite CICS-key storage in the CDSA or ECDSA, while running in user key. If this was the case, the sample changes the execution key to CICS, and retries the failing instruction.

You can use the sample program to identify, without abending, those programs that need to be defined with EXECKEY(CICS), because they intentionally modify a CICS-key DSA. For details of how to do this, see the prolog of DFH$PCTA.

DFH$PCTA can be extended for transaction isolation.

Exit XPCABND

Start of changeXPCABND is invoked after a transaction abend and before a transaction dump call: you can use it to suppress the dump. End of change

Start of changeWhen invokedEnd of change
Start of changeAfter a transaction abend and before a transaction dump call is made.End of change
Exit-specific parameters
UEPPCDS
Address of a storage area that contains program-related and terminal-related information. The storage area is mapped by the DSECT DFHPCUE.

When XPCABND is invoked, the following DFHPCUE fields are significant:

PCUE_CONTROL_BITS
A 1-byte flag field. A setting of PCUECBTE indicates that the transaction is linked to a terminal.
PCUE_TASK_NUMBER
A 3-character packed decimal field containing the task number.
PCUE_TRANSACTION_ID
A 4-character field containing the transaction ID.
PCUE_TERMINAL_ID
A 4-character field containing the terminal ID (if any).
PCUE_PROGRAM_NAME
An 8-character field containing the name of the program that is abending.
PCUE_LOGICAL_LEVEL
A fullword containing the number of chained DFHRSADS blocks (that is, the logical level).
UEPTACB
Address of the transaction abend control block (TACB) for the abend. If the abend occurred because of a program check, the information in the TACB includes:
  • The program status word (PSW)
  • The registers at the time of the abend.
  • Details of the subspace and access registers current at the time of the abend.

You can map the TACB using the DFHTACB TYPE=DSECT macro.

Return codes
UERCNORM
Continue processing - make the dump call.
UERCBYP
Suppress the dump call.
UERCPURG
Task purged during XPI call.
XPI calls
All can be used.

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
Writing global user exit programs
Making an XPI call
Related reference
List of global user exit points
The XPI functions
[[ Contents Previous Page | Next Page Index ]]