This section contains Product-sensitive Programming Interface information.
The external CICS® interface provides a user-replaceable module, DFHXCURM.
The load module is supplied in CICSTS31.CICS.SDFHEXCI, and the source in CICSTS31.CICS.SDFHSAMP. You can find information about assembling and link-editing user-replaceable
programs in the CICS Customization Guide.
DFHXCURM is invoked by the external CICS interface in the non-CICS region
during the processing of Allocate_Pipe commands, and after the occurrence
of any retryable error. The
retryable responses are:
- The target CICS region is not available
- There are no pipes available on the target CICS region
- There has been no IRC activity since the MVS™ IPL.
To retry after a retryable error, issue the EXCI call again.
As supplied, DFHXCURM is effectively a dummy program because of a branch
instruction that bypasses the sample logic and returns control to the external CICS interface caller. To use the sample logic, remove the branch instruction
and assemble and link-edit the module. Customizing DFHXCURM allows you to
do the following:
- When invoked during Allocate_Pipe processing, you can change the specified CICS APPLID, in order to route the request to another CICS system.
- When invoked after a retryable error you can store information regarding CICS availability. You can then use this information on the next invocation
of DFHXCURM for Allocate_Pipe processing, so that you can decide to which CICS system to route the request.
DFHXCURM is called using standard MVS register conventions, with register 1 containing
the address of the parameter list, and register 14 the return address of the
caller. The parameters addressed by register 1 are mapped in the EXCI_URM_PARMS
DSECT, which is contained within the DFHXCPLD copybook. The parameters passed
to DFHXCURM are as follows:
- URMINV
- The address of a fullword that contains the reason for the invocation
of DFHXCURM, defined by the following equates:
URM_ALLOCATE EQU 1 This invocation is for an Allocate_Pipe
URM_NO_CICS EQU 2 The target CICS region is not available
URM_NO_PIPE EQU 3 There are no pipes available
URM_NO_CICS_IRC EQU 4 There has been no IRC activity since the MVS IPL
- URMCICS
- The address of an 8-byte area that contains the generic APPLID of the
target CICS system, as specified on the CICS_applid parameter
of the Allocate_Pipe command, or on the APPLID parameter of the EXEC CICS LINK command.
When specified by one of these commands, you can change the APPLID to that
of a different target CICS region.
If the CICS_applid parameter is omitted from the Allocate_Pipe call, or APPLID is omitted
from the EXEC CICS LINK command, the field addressed by this parameter
contains 8 blanks. In this case, you must specify an APPLID in DFHXCURM before
returning control to the caller.
- URMAPPL
- The address of an 8-byte area that contains the client program's user
name as specified on the my_name parameter of the
Initialize_User command. Note that if DFHXCURM is invoked for an EXEC CICS LINK command, this name is always set to DFHXCEIP.
- URMPROG
- The address of an 8-byte area that contains the name of the target program
(if available). This name is available only if DFHXCURM is invoked for an
EXEC CICS LINK command. For an external CICS interface Allocate_Pipe command, the
program name is not known until the DPL call is issued.
- URMOPTS
- The address of a 1-byte area that contains the allocate options, which
can be X'00' or X'80', as specified on the allocate_opts parameter. This address is valid for an Allocate_Pipe request
only.
- URMANCH
- The address of a 4-byte area that is provided for use by DFHXCURM only.
A typical use for this is to store a global anchor address of an area used
to save information across a number of invocations of DFHXCURM. For example,
you can GETMAIN the necessary storage and save the address in the 4-byte area
addressed by this parameter. The initial value of the 4-byte area is set to
zero.
There is one URMANCH for each TCB in the
address space using EXCI.

[[ Contents Previous Page | Next Page Index ]]