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

[[ Contents Previous Page | Next Page Index ]]