Scalable Database Server, HiRDB Version 8 UAP Development Guide
(1) Preprocessing a UAP that uses an X/Open-based API (TX_ function)
This item describes notes on executing a UAP in a HiRDB system that is linked with TP1/LiNK (transaction control).
Linking with TP1/LiNK is possible when both the HiRDB server and the HiRDB client are Windows versions.
(a) UAP preprocessing and linkage
If a UAP is to be executed in a TP1/LiNK environment, execute UAP preprocessing and linkage as described as follows.
During SQL preprocessor execution, specify one of the following options:
- /XAD: Specify this option to create a UAP written in COBOL as a DLL.
- /XA: Specify this option in all other cases.
- Command specification example for C
PDCPP SAMPLE /XA
- Command specification example for COBOL
PDCBL SAMPLE.ECB /XAD
Link the following library to the UAP:
- %PDDIR%\CLIENT\LIB\PDCLTX32.LIB
Do not link CLTDLL.LIB.
(2) Using OpenTP1
UAP compilation and linkage when OpenTP1 is used are explained here. For details about compilation and linkage using OpenTP1, see the OpenTP1 Programming Reference C Language manual or the OpenTP1 Programming Reference COBOL Language manual.
- Transaction control object file creation
When OpenTP1 is used to create a UAP that accesses HiRDB, it is necessary to create a transaction control object file with the OpenTP1 trnmkobj operation command; following is the specification:
trnmkobj -o control-object-filename -r HiRDB_DB_server
- Example
- The transaction control object filename is control.
trnmkobj -o control -r HiRDB_DB_server
The following is specified to compile and link a UAP that uses API.
- To use a shared library:
/usr/bin/cc -c -l$DCDIR/include -I/HiRDB/include filename.c
/usr/bin/cc -o UAP-executable-form-filename UAP-filename.o
$DCDIR/spool/trnrmcmd/userobj/control-object-filename.o
-L/HiRDB/client/lib -lzclty -L$DCDIR/lib -Wl,-B,immediate
-Wl,-a, default -lbetran -L/usr/lib -ltactk -lbsd -lc
|
- Notes
- The directory for installing HiRDB is underlined.
- The -W1, +s option must be specified if different HiRDB distribution library directories are used for UAP creation and for UAP execution. When different distribution library directories are used for linkage and for execution, the SHLIB_PATH environment variable must be used at the time of execution to set the directory containing the distribution library.
- Depending on the method of OLTP registration that is used, the HiRDB system provides the following four libraries for UAPs that use an X/Open-compatible API. The library name that is specified for the linkage must match the applicable OLTP registration method.
-lzcltx (dynamic registration)
-lzclty (static/dynamic registration)
-lzcltxs (dynamic registration when the multi-connection facility is used)
-lzcltys (static/dynamic registration when the multi-connection facility is used)
In static/dynamic registration, the registration type can be switched to static registration or dynamic registration by the switch registered to TM. For details about the registration procedure, see the explanation of registering a HiRDB system in the transaction manager in the HiRDB Version 8 Installation and Design Guide.
- To create a UAP that uses an X/Open-compatible API in AIX 5L, specify -brtl in the linkage option.
- Example
- The filename (UAP name) is sample, UAP executable form filename is SAMPLE, and the transaction control object filename is control.
/usr/bin/cc -c -I$DCDIR/include -I/HiRDB/include sample.c
/usr/bin/cc -o SAMPLE sample.o
$DCDIR/spool/trnrmcmd/userobj/control.o
-L/HiRDB/client/lib -lzclty -L$DCDIR/lib
-Wl,-B,immediate -Wl,-a,default
-lbetran -L/usr/lib -ltactk -lbsd -lc
|
- To use an archive library:
/usr/bin/cc -c -l$DCDIR/include -I/HiRDB/include filename.c
/usr/bin/cc -o UAP-executable-form-filename UAP-filename.o
$DCDIR/spool/trnrmcmd/userobj/control-object-filename.o
-L/HiRDB/client/lib -lcltxa -L$DCDIR/lib -Wl,-B,immediate
-Wl,-a, default -lbetran -L/usr/lib -ltactk -lbsd -lc
|
- Notes
- The directory for installing HiRDB is underlined.
- The archive library provided by HiRDB (-lcltxa) must be specified before the library provided by OpenTP1 (-lbetran).
- Depending on the method of OLTP registration that is used, the HiRDB system provides the following two libraries for UAPs that use an X/Open-compatible API. The library name that is specified for the linkage must match the applicable OLTP registration method.
-lcltxa (dynamic registration)
-lcltya (static/dynamic registration)
In static/dynamic registration, the registration type can be switched to static registration or dynamic registration by the switch registered to TM. For details about the registration procedure, see the explanation of registering a HiRDB system in the transaction manager in the HiRDB Version 8 Installation and Design Guide.
- Example
- The filename (UAP name) is sample, UAP executable form filename is SAMPLE, and the transaction control object filename is control.
/usr/bin/cc -c -I$DCDIR/include -I/HiRDB/include sample.c
/usr/bin/cc -o SAMPLE sample.o
$DCDIR/spool/trnrmcmd/userobj/control.o
-L/HiRDB/client/lib -lcltxa -L$DCDIR/lib
-Wl,-B,immediate -Wl,-a,default
-lbetran -L/usr/lib -ltactk -lbsd -lc
|
- Transaction control object file creation
When OpenTP1 is used to create a UAP that accesses HiRDB, it is necessary to create a transaction control object file with the OpenTP1 trnmkobj operation command; following is the specification:
trnmkobj -o control-object-filename -r HiRDB_DB_SERVER
- Example
- The transaction control object filename is control.
trnmkobj -o control -r HiRDB_DB_SERVER
The following is specified to compile and link a UAP that uses API.
- To use a shared library:
ccbl -o UAP-executable-form-filename -Mw filename.cbl
$DCDIR/spool/trnrmcmd/userobj/control-object-filename.o
-L/HiRDB/client/lib -lzclty -L$DCDIR/lib -Wl,-B,immediate
-Wl,-a, default -lbetran -L/usr/lib -ltactk -lbsd -lc
|
- Notes
- The directory for installing HiRDB is underlined.
- The -Wl, +s option must be specified if different HiRDB distribution library directories are used for UAP creation and for UAP execution. When different distribution library directories are used for linkage and for execution, the SHLIB_PATH environment variable must be used at the time of execution to set the directory containing the distribution library.
- Depending on the method of OLTP registration that is used, the HiRDB system provides the following two libraries for UAPs that use an X/Open-compatible API. The library name that is specified for the linkage must match the applicable OLTP registration method.
-lzcltx (dynamic registration)
-lzclty (static/dynamic registration)
In static/dynamic registration, the registration type can be switched to static registration or dynamic registration by the switch registered to TM. For details about the registration procedure, see the explanation of registering a HiRDB system in the transaction manager in the HiRDB Version 8 Installation and Design Guide.
- Example
- The filename (UAP name) is sample, the UAP executable form filename is SAMPLE, and the transaction control object filename is control.
ccbl -o SAMPLE -Mw sample.cbl
$DCDIR/spool/trnrmcmd/userobj/control.o
-L/HiRDB/client/lib -lzclty -L$DCDIR/lib -Wl,-B,immediate
-Wl,-a,default -lbetran -L/usr/lib -ltactk -lbsd -lc
|
- To use an archive library:
ccbl -o UAP-executable-form-filename -Mw filename.cbl
$DCDIR/spool/trnrmcmd/userobj/control-object-filename.o
-L/HiRDB/client/lib -lcltxa -L$DCDIR/lib -Wl,-B,immediate
-Wl,-a,default -lbetran -L/usr/lib -ltactk -lbsd -lc
|
- Notes
- The directory for installing HiRDB is underlined.
- The archive library provided by HiRDB (-lcltxa) must be specified before the library provided by OpenTP1 (-lbetran).
- Depending on the method of OLTP registration that is used, the HiRDB system provides the following two libraries for UAPs that use an X/Open-compatible API. The library name that is specified for the linkage must match the applicable OLTP registration method.
-lcltxa (dynamic registration)
-lcltya (static/dynamic registration)
In static/dynamic registration, the registration type can be switched to static registration or dynamic registration by the switch registered to TM. For details about the registration procedure, see the explanation of registering an HiRDB system in the transaction manager in the HiRDB Version 8 Installation and Design Guide.
- Example
- The filename (UAP name) is sample, the UAP executable form filename is SAMPLE, and the transaction control object filename is control.
ccbl -o SAMPLE -Mw sample.cbl
$DCDIR/spool/trnrmcmd/userobj/control.o
-L/HiRDB/client/lib -lcltxa -L$DCDIR/lib -Wl,-B,immediate
-Wl,-a,default -lbetran -L/usr/lib -ltactk -lbsd -lc
|
(3) Using TPBroker
UAP compilation and linkage when TPBroker is used are explained here. The UAP is assumed to use the multi-thread XA interface. For details about compilation and linkage using TPBroker, see the TPBroker User's Guide manual. The libraries that are dedicated to the multi-thread XA interface support only C and C++.
(a) Transaction control object file creation
When TPBroker is used to create a UAP that accesses HiRDB, it is necessary to create a transaction control object file with the TPBroker tsmkobj operation command; following is the specification:
tsmkobj -o control-object-filename -r HiRDB_DB_SERVER
|
(b) Compilation and linkage
The following is specified to compile and link a UAP.
aCC +inst_implicit_include +DAportable -c -I$TPDIR/include
-I$TPDIR/include/dispatch -I/HiRDB/include -D_REENTRANT
-D_HP_UX_SOURCE -D_POSIX_C_SOURCE=199506Lfilename.c
aCC +inst_implicit_include +Daportable -o
UAP-executable-form-filename UAP-filename.o
$TPDIR/otsspool/XA/control-object-filename.o
-L/HiRDB/client/lib -lzcltxk -L$TPDIR/lib -Wl,+s -lots_r
-lorb-r
-Wl,-B,immediate -Wl,-a,default -L/usr/lib -lpthread
|
- Notes
- The directory for installing the HiRDB client is underlined.
- The -Wl, +s option must be specified if different HiRDB distribution library directories are used for UAP creation and for UAP execution. When different distribution library directories are used for linkage and for execution, the SHLIB_PATH environment variable must be used at the time of execution to set the directory containing the distribution library.
- Depending on the method of OLTP registration that is used (dynamic registration or static registration), the HiRDB system provides two libraries (-lzcltxk and -lzcltyk) for UAPs that use an XA interface that supports multiple threads. The library name that is specified for the linkage must match the applicable OLTP registration method.
(4) Using TUXEDO
UAP compilation and linkage when TUXEDO is used are explained here. The libraries that are dedicated to the XA interface support only C and C++.
- Load module construction for the transaction manager server (TMS)
buildtms -r HiRDB_DB_SERVER -o TMSload-module-filename |
- Load module construction for the TUXEDO system server
buildserver -r HiRDB_DB_SERVER -s service-name
-o server-load-module-filename -f server-filename.o
|
- Load module creation for the TUXEDO client
buildclient -o client-load-module-name -f client-filename.c
|
(b) Windows
- Load module construction for the transaction manager server (TMS)
set LINK=/EXPORT:_imp_pdtxa_switch=pdtxa_switch
/EXPORT:_inp_pdtxa_switch_y=pdtxa_switch_y
buildtms -r HiRDB_DB_SERVER -o TMSload-module-filename
|
- Load module construction for the TUXEDO system server
set LINK=/EXPORT:_imp_pdtxa_switch=pdtxa_switch
/EXPORT:_inp_pdtxa_switch_y=pdtxa_switch_y
buildserver -r HiRDB_DB_SERVER -s service-name
-o server-load-module-filename -f server-filename.obj
|
- Load module creation for the TUXEDO client
buildclient -o client-load-module-name -f client-filename.c
|
(5) Using TP1/EE (limited to UNIX)
UAP compilation and linkage when TP1/EE is used are explained here. For details about the TP1/EE commands, see the TP1/Server Base Enterprise Option User's Guide.
- Object file creation for resource manager linking
When using TP1/EE to create a UAP that accesses HiRDB, you must use a TP1/EE operation command to create an object file for linking with the resource manager. Use the eetrnmkobj command to create the object file.
The specification for creating an object file for linking with the resource manager is as follows:
eetrnmkobj -o name-of-object-file-for-resource-manager-linking -r HiRDB_DB_SERVER \
-s RM-switch-name -O RM-object-file-name \
-i header-path-provided-by-HiRDB
|
- Example
- The name of the object file for linking with the resource manager is control, and the static registration method is used to create the object file.
eetrnmkobj -o control -r HiRDB_DB_SERVER -s pdtxa_switch_y \
-O /HiRDB/client/lib/libzcltyk.sl -i /HiRDB/include
|
- Compilation and linkage
The following is specified to compile and link a UAP that uses the multi-thread XA interface.
- Using a shared library
/usr/vac/bin/xlc_r -o executable-file-name $DCDIR/lib/ee_main.o
resource-manager-linking-object -brtl -bdynamic -L/HiRDB/lib -L/HiRDB/client/lib
-L$DCDIR/lib -lpthread -lisode -lc_r -ldl -lzcltyk -lee -lee_rm
-lbetran2 -ltactk
|
- Notes
- The directory for installing the HiRDB client is underlined.
- When the multi-thread XA interface is used, specify -lzcltyk as the library for the TP1/EE UAP, and specify a corresponding name as the library name to be specified during linkage. For details about the registration procedure, see the HiRDB Version 8 Installation and Design Guide.
- Example
- The name of the UAP executable file is SAMPLE, and the name of the object file for linking with the resource manager is control.
/usr/vac/bin/xlc_r -o SAMPLE $DCDIR/lib/ee_main.o control.o
-brtl -bdynamic -L/HiRDB/lib -L/HiRDB/client/lib -L$DCDIR/lib
-lpthread -lisode -lc_r -ldl -lzcltyk -lee -lee_rm -lbetran2 -ltactk
|
- Creating an object file for resource manager linking
When TP1/EE is used to create a UAP that accesses HiRDB, a TP1/EE operation command must be used to create an object file for linking with the resource manager. The eetrnmkobj command is used for this purpose.
The following is specified to create an object file for resource manager linking:
eetrnmkobj -o name-of-object-file-for-resource-manager-linking -r HiRDB_DB_SERVER \
-s RM-switch-name -O RM-related-object-file-name \
-i header-path-provided-by-HiRDB
|
- Example
- The name of the object file for resource manager linking is control, and the file is created by the static registration method.
eetrnmkobj -o control -r HiRDB_DB_SERVER -s pdtxa_switch_y \
-O /HiRDB/client/lib/libzcltyk.sl -i /HiRDB/include
|
- Compilation and linkage
For details about compilation and linkage of a UAP that uses the multi-thread XA interface, see the TP1/Server Base Enterprise Option User's Guide.
All Rights Reserved. Copyright (C) 2007, Hitachi, Ltd.