DOC1 Programmer's Guide

User Exits
For Lookup Table exits: use with any entry in the
section.
The name used (‘SendToArchive’ in the example
above) must match the external name specified in the
appropriate DuxRegister… function within the user
program itself.
You will also need to code a section
which identifies the object modules containing the
user programs to be referenced.
If required, you can pass parameters to the user
program either by accessing symbols defined in the
OPS file or by extending the parameters in the
USEREXIT keyword. The DuxGetOpsSymbolValue
and DuxGetInvokeParameter API functions allow you
to retrieve these values within the user program.
The format of these commands is demonstrated in
the OPS example below.
REFER TO THE DOC1 USERS GUIDE FOR GENERAL
INFORMATION ABOUT CREATING AND USING AN OPS FILE.
Sample OPS settings for user exits
;replace input data with a user exit
DataInput=USEREXIT(BWDI)
;The user exit will provide keyed images
Map1=USEREXIT(AKM)
;replace a lookup table with a user exit
;the user program expects 2 parameters
Table1=USEREXIT(BWLT,15,2004)
;this declares the user program modules
1=DOC1IN.DLL
2=DOC1KMAP.DLL
3=DOC1LTAB.DLL
Creating the user program
The user program interfaces with DOC1 Generate
using the DUX API (DOC1 User Exit) which is an
external function library supplied with the DOC1
Generate distribution material. This object module
must be included in the link dependencies when the
user program is built. A header file declaring the
available functions is also supplied and this must be
included in the source code for the user program.
The API is written in standard C and this is also the
language expected in the user program. C++
programs can also access the interface but note that
no C++ classes are provided.
Note the following:
• If the program calls modules in other languages
it is the users responsibility to ensure that all
inter-language linking issues are properly
resolved.
• Under OS/390 or z/OS you may only initiate
one user exit function for each load module.
• Under Windows all user exit functions called by
a single DOC1 program should be contained
within a single DLL to prevent memory
fragmentation.
Program structure
All user exit programs must consist of at least:
A DOC1REG function (the name is fixed) which
registers the user program with DOC1 Generate.
Within DOC1REG you will need to include a call to
the relevant DuxRegister… API function which
defines the type of user exit to DOC1, supplies a
name by which the exit is identified externally and
names a further function that will carry out the
actual user exit activity.
192