The EXCI user-replaceable module

The external CICS® interface provides a user-replaceable module, DFHXCURM.

The load module is supplied in CICSTS53.CICS.SDFHEXCI, and the source in CICSTS53.CICS.SDFHSAMP. You can find information about assembling and link-editing user-replaceable programs in Assembling and link-editing user-replaceable programs.

DFHXCURM is started 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. You can customize DFHXCURM to do the following actions:

During allocate_pipe processing, you can change the specified CICS APPLID, to route the request to another CICS system.
During allocate_pipe processing, you can direct the request to a different XCF group.
When DFHXCURM is started after an error that can be tried again, you can store information about CICS availability. You can then use this information on the next invocation of DFHXCURM for allocate_pipe processing, so that you can decide 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 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. Also, if the APPLID specified by one of these commands is not a valid specific applid, you must change the APPLID to that of a valid specific applid.

If the CICS_applid parameter is omitted from the allocate_pipe request, 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. If DFHXCURM is started 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 started 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 parameter for each TCB in the address space using EXCI.

URMXCFG

The address of an 8-byte area that contains the XCF group name as specified in the XCFGROUP parameter of the DFHXCOPT table. Use this parameter to change the XCF group name when DFHXCURM is called during the processing of EXCI Allocate_Pipe commands. If the call to DFHXCURM failed but can be tried again, the area contains the value used when previously allocating the pipe. Changing the value has no affect.

The group name must be 8 characters long, padded on the right with blanks if necessary. Valid characters are A-Z 0-9 $ # @. Do not begin group names with the letters A, B, C, E, F, G, H, I "SYS." These names are used by IBM® for its XCF groups. Also, do not use the name "UNDESIG", which is reserved for use by the system programmer in your installation.

It is advisable to use a group name beginning with the letters "DFHIR".