- 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:
- 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.
- If you use XPCREQ to change the target SYSID,
remember that:
- 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.
- If SYSID specifies the local region, CICS treats the link request as if
SYSID was not specified. The local PROGRAM definition is honored.
- 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:
- A distributed program link (DPL) call
- A Link3270 bridge request
Note that XPCERES is invoked:
- After exit XPCREQ and before XPCREQC (if these exits are enabled). This
means that:
- If an XPCREQ exit program chooses to bypass the request, XPCERES is not
invoked, even if it is enabled.
- If an XPCREQ exit program modifies the command parameter list, XPCERES
must deal with the modified request.
- On the target region--that is, the region
to which the request has been routed.
- Only if the routing region--the region on which the routing program
runs--supports the "resource unavailable" condition (RESUNAVAIL).
To support the "resource unavailable" condition, the routing region
must be one of the following:
- CICS TS OS/390, Version 1 Release 3, with APAR PQ73107 applied
- CICS TS for z/OS, Version 2.2, with APAR PQ74920 applied
- CICS TS for z/OS, Version 2.3 or later
- Only if it is enabled. It is strongly recommended that you enable this
exit only in application-owning regions to which the above kinds of request
may be dynamically routed.
- By internal requests made by CICS code, as well as by requests made by
applications.
The XPCERES exit is not invoked:
- For statically-routed requests.
- If it is disabled.
- If an XPCREQ exit program chooses to bypass the request.
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:
- Set the DYRERROR field of the routing program’s communications area
to 'F'--resource unavailable.
- Reinvoke the routing program, on the routing region, for route selection
failure.
- 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:
- EXEC CICS SHUTDOWN
- EXEC CICS XCTL
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.
UEP_PC_REMOTE_SYSTEM
If 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.
UEP_PC_REMOTE_NAME
If 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.
- 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:
- EXEC CICS SHUTDOWN
- EXEC CICS XCTL
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.
The command-level parameter structure contains 11 addresses, PC_ADDR0
through PC_ADDRA
. 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
- PC_FUNCT
- PC_BITS1
- PC_BITS2
PC_EIDOPT4
- PC_EIDOPT5
- PC_EIDOPT6
- 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.
PC_BITS2

One 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.

PC_EIDOPT4
Not used by program control.
- 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.
PC_ADDR9
is not used.
PC_ADDRA
is the address of the 16-byte channel name, as specified on the CHANNEL
parameter.
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.
PC_BITS2
- X'40'
- The existence bit for CHANNEL.
- 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:
- Modify or set completion or resource information in XPCREQ and XPCREQC.
- Examine completion information in XPCREQC.
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
- Scan the global work area (GWA) to locate a suitable CICS region - for
example, the region currently processing the least number of LINK requests.
- Having decided which system to route the request to, increment the use
count for this system.
- 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.
- Set PC_ADDR7 to the address of the 4-byte area.
- 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.
- Set the X'02' existence bit on in PC_BITS1 to indicate that a
SYSID is specified.
- Return to CICS.
In XPCREQC
- Scan the global work area (GWA) and locate the entry for the CICS region
specified in the SYSID parameter.
- Decrement the use count for this system.
- If a GETMAIN was issued in XPCREQ to obtain an area to hold the SYSID,
issue a FREEMAIN for the address held in UEPPCTOK.
- Return to CICS.
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.
When 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.
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.
A 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.
A setting of PCUE_REAL (X'20') indicates that a real entry
point is set in PCUE_REAL_ENTRY.
- 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
Address of the program’s communication area, if the program
has one.
- PCUE_COMMAREA_SIZE
Fullword containing the length of the program’s communication
area, if the program has one.
- 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).
PCUE_REAL_ENTRY
From 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.
PCUE_CHANNEL_NAME
Address 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.
- 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.
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:
- The code that is invoked receives control in the execution key that the
internal abend routine would have received control in--that is, the key
in force when the EXEC CICS HANDLE ABEND LABEL command was issued.
- The resume address is placed
in either register 14 or register 15, depending on the language of the application.
For COBOL, R14 holds the return address; for Assembler, R15 is used. If you
run in a mixed environment, your exit program may need to set up its own base
register. For
example, you could set up addressability using:
BASSM 15,0
USING *,15
- 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.
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:
- Set a resume address, instead of letting CICS process the abend
- Specify the subspace that control is passed in.
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:
- It is possible that the XDUREQ dump domain exit may be invoked before
XPCTA. (For details of XDUREQ, see topic Exit XDUREQ.)
- 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.
A
resume address, normally obtained from the return code UERCMEA from XPCTA,
is ignored for C and C++ programs compiled with the XPLINK option.
- 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.
A
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.
- 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.
XPCABND is invoked after a transaction
abend and before a transaction dump call: you can use it to suppress the dump. 
When invoked
After a transaction abend and before a transaction dump call is made.
- 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.

[[ Contents Previous Page | Next Page Index ]]