The EXCI user-replaceable module

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:

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:

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.

Related concepts
Introduction to the external CICS interface
Related tasks
The EXCI CALL interface
The EXCI EXEC CICS interface
Using EXEC CICS LINK command
Retries on an EXEC CICS LINK command
Translation required for EXEC CICS LINK command
[[ Contents Previous Page | Next Page Index ]]