DL/I interface program exits XDLIPRE and XDLIPOST

The XDLIPRE and XDLIPOST exit points are invoked following the issue of an EXEC DLI command or DL/I call. Exit XDLIPRE is invoked before the request is processed and XDLIPOST is invoked after the request is processed.

When the request is function shipped, the exits are invoked from both the application-owning region and the database-owning region. However, there are restrictions when they are invoked in a database-owning region, as described below.

The CICS® IMS™ Database Control Guide contains a sample program for the XDLIPRE exit.

Notes:
  1. The descriptions of the exits that follow show the general format of the application’s parameter list. For detailed information about the format of the CALL-level DL/I parameter list, refer to the IMS/ESA® Application Programming: DL/I Calls manual.
  2. For all EXEC DLI calls, the application’s parameter list is in assembler-language format (that is, the value of the program language byte pointed to by UEPLANG is always UEPASM, and the parameter list pointed to by UEPAPLIST is always in assembler-language format). This is because all EXEC DLI calls are converted into assembler-language CALL-level requests.

    An EXEC DLI online request is converted by DFHEDP into a CALL-level request for DFHDLI. (IMS does not deal directly with EXEC-level parameter lists.)

    The first parameter in the CALL parameter list contains the address of the parameter count.

    The second parameter in the CALL parameter list contains the address of the function. All other parameters are dependent on the function.

  3. In an XDLIPRE exit program you can change the PSB name and the SYSID name. This helps availability if the originally specified SYSID fails.

    You can change the SYSID from:

    • A remote value to another remote value
    • The local value to a remote value
    • A remote value to the local value.

    Changing the SYSID has an effect only if the associated PSB has a PDIR entry. The SYSID may be the local CICS (that is, the SYSIDNT specified on the CICS region) or a remote connection name. For the new SYSID to be used, the PSB name must have a PDIR entry; if it does not have a PDIR entry, the assumption is made that the local CICS is connected to DBCTL, and an attempt is made to run the IMS request there. An IMS schedule failure is handled in the same way as a failure to route to a connection that does not exist. If the SYSID is changed to either the same value as the SYSIDNT of the local CICS or blanks (hex '40404040'), CICS attempts to run the IMS request on the local system.

Exit XDLIPRE

When invoked
On entry to the DL/I interface program.
Exit-specific parameters
UEPCTYPE
Address of type-of-request byte. Values are:
UEPCEXEC
The original request was an EXEC DLI request.
UEPCCALL
The original request was a CALL-level request.
UEPCSHIP
The request has been function shipped from another region. When this value is set, restrictions apply to the setting and use of the rest of the exit parameters, as described below.
UEPAPLIST
Address of application’s parameter list. The general format for COBOL and assembler language is:
plist address --> parm1 address --> parm1
                parm2 address --> parm2
                parm3 address --> parm3
                ..............
                up to a maximum of 18 parameters
                excluding the optional parmcount.
              The general format for PL/I is:
plist address --> parm1 address --> parm1 (parmcount)
       parm2 address --> locator descriptor --> parm2
       parm3 address --> locator descriptor --> parm3
       ..............
       up to a maximum of 18 parameters
When UEPCTYPE is not UEPCSHIP, your exit program can change any of the parameters in the application parameter list. For UEPCSHIP requests, your exit program cannot change any of the parameters. Furthermore, for UEPCSHIP requests, UEPAPLIST points to a copy of the parameter list in the above format, but which contains only the first two parameters, parm1 and parm2.
Note:
For PL/I applications, parm1 may or may not contain a parameter-count. Your exit program should check this field before using it.
UEPLANG
Address of program language byte. Values are:
UEPPLI
PL/I
UEPCBL
COBOL
UEPASM
Assembler language.

For UEPCSHIP requests, the language is always assembler.

UEPIOAX
Address of I/O area existence flag byte:
UEPIOA1
I/O area exists.

For UEPCSHIP requests, the I/O area existence flag is always off.

UEPIOA
Address of I/O area. This is the application’s IOAREA, or DFHEDP’s IOAREA in the case of EXEC DLI. The contents of the IOAREA can be overwritten in the exit: the new contents are used when the DL/I request is processed. However, it should be noted that IOAREAs can be in a program’s static storage and, in this case, should not be overwritten.

For UEPCSHIP requests, UEPIOA is always zero.

UEPPSBNX
Address of PSB existence flag byte:
UEPPSB1
A PSB exists.
UEPPSBNM
Address of an area containing the 8-character PSB name. The contents of the area can be overwritten by the exit, for all types of request including UEPCSHIP; the new contents are used when the DL/I request is processed.
UEPSYSDX
Address of the SYSID existence flag byte:
UEPSYS1
A SYSID exists.
UEPSYSID
Address of an area containing the 4-character SYSID name. The contents of the area can be overwritten by the exit, for all types of request including UEPCSHIP; the new contents are used when the DL/I request is processed.
Return codes
UERCNORM
Continue processing
UERCBYP
Bypass DL/I request and return
UERCPURG
Task purged during XPI call.
XPI calls
All can be used.

Exit XDLIPOST

When invoked
On exit from the DL/I interface program.
Exit-specific parameters
UEPCTYPE
Address of type-of-request byte. Values are:
UEPCEXEC
An EXEC DLI request.
UEPCCALL
A CALL-level request.
UEPCSHIP
The request has been function shipped from another region. When this value is set, restrictions apply to the setting and use of the rest of the exit parameters, as described below.
UEPAPLIST
Address of application’s parameter list. The general format for COBOL and assembler language is:
plist address --> parm1 address --> parm1
                parm2 address --> parm2
                parm3 address --> parm3
                ..............
                up to a maximum of 18 parameters
                excluding the optional parmcount.
              The general format for PL/I is:
plist address --> parm1 address --> parm1 (parmcount)
       parm2 address --> locator descriptor --> parm2
       parm3 address --> locator descriptor --> parm3
       ..............
       up to a maximum of 18 parameters.
When UEPCTYPE is not UEPCSHIP, your exit program can change any of the parameters in the application parameter list. For UEPCSHIP requests, your exit program cannot change any of the parameters. Furthermore, for UEPCSHIP requests, UEPAPLIST points to a copy of the parameter list in the above format, but which contains only the first two parameters parm1 and parm2. See also Notes.
Note:
For PL/I applications, parm1 may or may not contain a parameter-count. Your exit program should check this field before using it.
UEPLANG
Address of program language byte. Its values are:
UEPPLI
PL/I
UEPCBL
COBOL
UEPASM
Assembler language.

For UEPCSHIP requests, the language is always assembler.

UEPIOAX
Address of I/O area existence flag byte:
UEPIOA1
I/O area exists.

For UEPCSHIP requests, the I/O area existence flag is always off.

UEPIOA
Address of I/O area. This is the application’s IOAREA, or DFHEDP’s IOAREA in the case of EXEC DLI. The contents of the IOAREA can be overwritten in the exit and are returned to the application program in the new form. However, it should be noted that the application’s IOAREA could be in the program’s static storage and, in this case, should not be overwritten.

For UEPCSHIP requests, UEPIOA is always zero.

UEPUIBX
Address of UIB existence flag byte:
UEPUIB1
a UIB exists.
UEPUIB
Address of the UIB, which is mapped by DFHUIB in module DFHDBCOP. The contents of the UIB can be overwritten in the exit for all types of request, including UEPCSHIP. The new contents are returned to the application or to the region that function shipped the request.
Return codes
UERCNORM
Continue processing.
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 ]]