OpenTP1 Version 7 User's Guide
(1) Registering SQL Server
You must register SQL Server in the OpenTP1 system. Use the trnlnkrm command to do this.
The following shows an example of the trnlnkrm command:
trnlnkrm -a MS_SQL_Server -s msqlsrvxa1 -o xaswitch.lib
|
For details about the trnlnkrm command, see Chapter 7. Operation Commands. For details about the information to be specified in the trnlnkrm command, such as RM name, RM switch name, and RM-related object name, see the SQL Server documentation.
The following notes explain execution of the trnlnkrm command.
- -o option in the trnlnkrm command
Set the path of a related object in the LIB environment variable beforehand. If you specify the absolute path including folders for the related object, use \\ as the folder delimiter.
- Specification of the prcsvpath definition command
When you register SQL Server in the OpenTP1 system, the transaction service process uses SQL Server runtime libraries. Therefore, you must specify the folder containing the SQL Server runtime libraries in the prcsvpath process service definition command. The following shows an example of the prcsvpath definition command:
(2) Specifying the transaction service definition
Use the trnstring transaction service definition command to specify the information required in order to access the resource manager. When you link OpenTP1 with SQL Server, specify the -n, -o, -O, -c, and -C options and, if necessary, the -d option in the trnstring definition command.
Specify in the -o, -O, -c, and -C options the xa_open and xa_close function strings used to access the resource manager. Specify the xa_open and xa_close function strings as follows:
- For the -o, -O, -c, and -C options, specify the same value.
- For RmRecoveryGuid, specify a value that is unique globally. Specify the value (without the parentheses) acquired by Registry Format of the Windows guidgen utility program.
- For Timeout, specify the XA transaction timeout value (in milliseconds). When the specified timeout value expires, SQL Server (Windows MSDTC) rolls back the XA transaction automatically.
For details about the xa_open and xa_close function strings to be specified in SQL Server, see the SQL Server documentation.
The following shows an example of a transaction service definition:
set trn_extend_function=00000001 #add when SQL Server is used.
trnstring -n MS_SQL_Server \
-o "Tm=OpenTP1,\
RmRecoveryGuid=986D495E-F4D4-4e80-8B70-9377FFAF33E7,Timeout=180000" \
-O "Tm=OpenTP1,\
RmRecoveryGuid=986D495E-F4D4-4e80-8B70-9377FFAF33E7,Timeout=180000" \
-c "Tm=OpenTP1,\
RmRecoveryGuid=986D495E-F4D4-4e80-8B70-9377FFAF33E7,Timeout=180000" \
-C "Tm=OpenTP1,\
RmRecoveryGuid=986D495E-F4D4-4e80-8B70-9377FFAF33E7,Timeout=180000"
|
- Note
- If a character string enclosed in double quotation marks (") continues onto the next line following a continuation line symbol (\), make sure that the specification on the continuation line begins in column 1.
- Note
- Many of the errors that occur when an SQL Server database is accessed from OpenTP1 while using the X/Open XA interface are due to invalid xa_open and xa_close function string definitions. If the KFCA00901-W message is issued, check the xa_open and xa_close function string definitions and revise them as necessary.
(3) Compiling and linking UAPs
When you compile and link a UAP that accesses SQL Server, you must use the trnmkobj command to link the transaction control object created under %DCDIR%\spool\trnrmcmd\userobj.
For details about how to compile and link UAPs, see 3.2 Compiling and linking UAPs, the edition of the manual OpenTP1 Programming Reference for the applicable language, and the SQL Server documentation. For details about the trnmkobj command, see Chapter 7. Operation Commands.
The following shows examples of creating a transaction control object for UAPs that access SQL Server in C language and in COBOL.
In C language
trnmkobj -o rm_obj -r MS_SQL_Server
|
In COBOL
trnmkobj -o rm_obj -C "/Zl" -r MS_SQL_Server
|
(4) Example of a makefile (in C language)
This subsection presents an example of a makefile that is used when an SPP is created in C language.
(a) Source file names
The source file names used in the example makefile are as follows:
- Source program names of UAP created in C language:
- exmain.c (main function)
- exsv1.c (service function 1)
- exsv2.c (service function 2)
- exsql.c (SQL)
- RPC interface definition file name: ex.def
(b) Example of a makefile
The following shows an example of a makefile:
NODEBUG = 1
!include <ntwin32.mak>
#TP1TEST Make File
SYSLIB = $(conlibsdll)
TP1LIB = [libdam.lib]#1 [libtam.lib]#2 libbetran.lib
SQLSRVLIB = xaswitch.lib odbc32.lib
all:TP1TEST.exe
# Compile
exmain.obj:exmain.c
$(cc) $(cflags) $(cvarsdll) $*.c
exsv1.obj:exsv1.c
$(cc) $(cflags) $(cvarsdll) $*.c
exsv2.obj:exsv2.c
$(cc) $(cflags) $(cvarsdll) $*.c
ex_sstb.obj:ex_sstb.c
$(cc) $(cflags) $(cvarsdll) $*.c
exsql.obj:exsql.c
$(cc) $(cflags) $(cvarsdll) $*.c
# Create a stub source file
ex_sstb.c:ex.def
$(DCDIR)\bin\stbmake $?
# Link
TP1TEST.exe: exmain.obj exsv1.obj exsv2.obj ex_sstb.obj exsql.obj
$(link) $(conflags) -out:$*.exe $** \
[$(DCDIR)\spool\trnrmcmd\userobj\rm_obj.obj \]#3
$(TP1LIB) $(SYSLIB) $(SQLSRVLIB)
|
- #1
- Specify libdam.lib only if you use TP1/FS/Direct Access.
- #2
- Specify libtam.lib only if you use TP1/FS/Table Access.
- #3
- If you use TP1/FS/Direct Access or TP1/FS/Table Access, add OpenTP1_DAM or OpenTP1_TAM when you use the trnmkobj command to create a transaction control object.
(5) Example of a makefile (for COBOL)
This subsection presents an example of a makefile that is used when an SPP is created in COBOL.
(a) Source file names
The source file names used in the example makefile are as follows:
- Source program name of UAP created in COBOL2002: main.cbl
- Service program name of UAP created in COBOL2002: sev1.cbl
- Service program name of UAP created in COBOL2002: sev2.cbl
- SQL program name 1 created in COBOL2002: exsql1.cbl
- SQL program name 2 created in COBOL2002: exsql2.cbl
- RPC interface definition file name: ex.def
(b) Example of a makefile
The following shows an example of a makefile:
!include <ntwin32.mak>
# TP1TEST Make File
CBLFG1 = -Compile,NoLink -Comp5 -Lib,CUI -SQL,ODBC -Main,System
CBLFG2 = -Compile,NoLink -Comp5 -Lib,CUI -SQL,ODBC
SYSLIB = $(conlibsdll)
TP1LIB = [libdam.lib]#1 [libtam.lib]#2 libbetran.lib
SQLSRVOBJ = xaswitch.lib
CCBL = ccbl2002
LK = ccbl2002 -Lib,CUI
all:TP1TEST.exe
# Compile
main.obj:main.cbl
$(CCBL) $(CBLFG1) main.cbl
sev1.obj:sev1.cbl
$(CCBL) $(CBLFG2) sev1.cbl
sev2.obj:sev2.cbl
$(CCBL) $(CBLFG2) sev2.cbl
exsql1.obj:exsql1.cbl
$(CCBL) $(CBLFG2) exsql1.cbl
exsql2.obj:exsql2.cbl
$(CCBL) $(CBLFG2) exsql2.cbl
ex_sstb.obj:ex_sstb.c
$(cc) $(cflags) /Zl $(cvarsdll) $*.c
# Create a stub source file
ex_sstb.c:ex.def
$(DCDIR)\bin\stbmake $?
# Link
TP1TEST.exe: main.obj sev1.obj sev2.obj ex_sstb.obj \
exsql1.obj exsql2.obj
$(LK) -OutputFile $*.exe $** \
[$(DCDIR)\spool\trnrmcmd\userobj\rm_obj.obj \]#3
$(TP1LIB) $(SYSLIB) $(SQLSRVOBJ)
|
- #1
- Specify libdam.lib only if you use TP1/FS/Direct Access.
- #2
- Specify libtam.lib only if you use TP1/FS/Table Access.
- #3
- If you use TP1/FS/Direct Access or TP1/FS/Table Access, add OpenTP1_DAM or OpenTP1_TAM when you use the trnmkobj command to create a transaction control object.
(6) Notes about linking SQL Server
- If you link OpenTP1 and SQL Server while using the X/Open XA interface, make sure that all SQL Server-related services are running.
- If you link OpenTP1 and SQL Server while using the X/Open XA interface, use the following OpenTP1 functions to start transactions and acquire synchronization points:
dc_trn_begin, tx_begin, dc_trn_unchained_commit, dc_trn_chained_commit, tx_commit, dc_trn_unchained_rollback, dc_trn_chained_rollback, tx_rollback
If SQL Server's SQL language is used to perform commit and rollback processing or if SQL Server linked with the XA interface makes an attempt to use an unsupported function, transactions might not be processed correctly, resulting in a data integrity error in resources or in shutdown of the OpenTP1 system.
- The following notes apply to UAP creation when OpenTP1 and SQL Server are linked while using the X/Open XA interface.
- Using DB-Library and XA interface to link OpenTP1 and SQL Server (creating UAPs in C or C++ language)
In order to associate OpenTP1 transactions with an SQL Server connection while using the XA interface, you must issue a function (dbenlistxatrans) for establishing an association at the beginning of each transaction branch. If this function is not issued, the determination of transactions managed by OpenTP1 cannot be achieved. For details, see the SQL Server documentation.
- Using an ODBC connection and the XA interface to link OpenTP1 and SQL Server (creating UAPs in C or C++ language)
In order to associate OpenTP1 transactions with an SQL Server connection while using the XA interface, you must issue a function (SQLSetconnectOption) for establishing an association at the beginning of each transaction branch. If this function is not issued, the determination of transactions managed by OpenTP1 cannot be achieved. For details, see the SQL Server documentation.
- Using an ODBC connection and the XA interface to link OpenTP1 and SQL Server (creating UAPs in COBOL2002)
In order to associate OpenTP1 transactions with an SQL Server connection while using the XA interface, you must issue a service routine (CBLSQLSETOPT provided by COBOL2002) for establishing association at the beginning of each transaction branch. If this service routine is not issued, the determination of transactions managed by OpenTP1 cannot be achieved. You must also specify the following environment variable in the user service definition of the user server that is linked with SQL Server by the XA interface:
- If you link OpenTP1 and SQL Server while using the X/Open XA interface, use of chained RPCs requires special attention. You must make sure that none of the three functions that associate OpenTP1 transactions with the SQL Server connection via the XA interface (dbenlistxatrans, SQLSetconnectOption, and CBLSQLSETOPT) is issued in the second or subsequent RPC.
- If you link OpenTP1 and SQL Server while using the X/Open XA interface, specify the Timeout setting for the XA interface open and close strings. If the Timeout setting is not specified and a UAP terminates abnormally, a transaction in the status SPID=-2 might remain permanently in SQL Server (Windows MSDTC). In Windows Server 2003, you must apply Service Pack 2 in order to specify the Timeout setting.
- If you link OpenTP1 and SQL Server while using the X/Open XA interface, specify the following setting in the transaction service definition at all OpenTP1 nodes associated with the transaction branch:
set trn_extend_function=00000001
|
If the following conditions are satisfied, OpenTP1's transaction determination function returns DCTRNER_HAZARD(-904) or TX_HAZARD(-4), not DC_OK(0):
- SQL Server is the only available resource manager access (one-phase commit is used to determine transactions).
- SQL Server rolls back transactions automatically based on the specified Timeout setting.
All Rights Reserved. Copyright (C) 2012, Hitachi, Ltd.