OpenTP1 Version 7 User's Guide
(1) Registering Oracle
You must register Oracle in the OpenTP1 system. Use the trnlnkrm command to do this.
The following shows an example of the trnlnkrm command for Oracle Database 11g:
trnlnkrm -a Oracle_XA -s xaosw -o oraxa11.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 Oracle 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 Oracle in the OpenTP1 system, the transaction service process uses Oracle runtime libraries. Therefore, you must specify the folder containing the Oracle runtime libraries in the prcsvpath process service definition command. The following shows an example of the prcsvpath definition command:
(2) Specifying environment variables
You must set appropriate values in the Oracle environment variables in order to access Oracle. Specify the environment variables in putenv format in the following OpenTP1 system definitions:
- Transaction service definition
- User service definition
- User service default definition
The following shows an example of these definitions:
putenv ORACLE_HOME c:\orant
putenv ORACLE_SID ORCL
|
For details about the OpenTP1 system definition, see Chapter 5. System Definitions. For details about the environment variables to be specified and their settings, see the settings used for installing Oracle and the Oracle documentation.
(3) 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 Oracle, specify the -n, -o, and -O options and, if necessary, the -d option in the trnstring definition command.
Specify in the -o and -O options the xa_open function string used to access the resource manager. There is no need to specify the xa_close function string (specified in the -c and -C options in the trnstring definition command).
For uid in the xa_open function string for the transaction service that is specified in the -o option, specify the Oracle database administrator. If the specified uid does not belong to the Oracle database administrator or the specified uid does not have the DBA privilege, partial UAP recovery processing or transaction recovery processing after an OpenTP1 system restart might not be performed successfully. For details about the xa_open function string to be specified in Oracle, see the Oracle documentation.
The following shows an example of a transaction service definition:
trnstring -n Oracle_XA \
-o "Oracle_XA+Acc=P/sys/change_on_install+SesTm=60" \
-O "Oracle_XA+Acc=P/scott/tiger+SesTm=60"
|
- 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 Oracle database is accessed from OpenTP1 while using the X/Open XA interface are due to an invalid xa_open function string definition. If the KFCA00901-W message is issued, check the xa_open function string definition and revise it as necessary.
(4) Settings required for accessing multiple Oracle databases
This subsection explains the settings required in order to access multiple Oracle databases from OpenTP1. These settings also apply when a single Oracle database is accessed using multiple Oracle uids.
- Setting up SQL*Net
If OpenTP1 is to access multiple Oracle databases, SQL*Net is required according to the specifications for Oracle open and close strings. Set up SQL*Net by referencing the Oracle documentation.
- Defining the xa_open function string
If OpenTP1 is to access multiple Oracle databases, the method for defining the xa_open function string used for accessing the resource manager varies as described below.
- Define the -i option in the trnstring transaction service definition command so that multiple Oracle databases can be identified by resource-manager-name + resource-manager-extension.
- In the -i option of the trnrmid user service default definition command, define the resource manager extension that was defined in step 1.
The following shows an example of a transaction service definition:
trnstring -n Oracle_XA -i s1 \
-o "Oracle_XA+Acc=P/sys/change_on_install+SesTm=60" \
-O "Oracle_XA+Acc=P/scott/tiger+SesTm=60"
trnstring -n Oracle_XA -i s2 \
-o "Oracle_XA+SqlNet=host01+Acc=P/sys/change_on_install+SesTm=60"\
-O "Oracle_XA+SqlNet=host01+Acc=P/scott/tiger+SesTm=60"
|
The following shows an example of a user service default definition:
trnrmid -n Oracle_XA -i s1
|
The following shows an example of a user service definition:
trnrmid -n Oracle_XA -i s2
|
- Note
- The trnrmid definition command takes effect for each resource manager extension. If s1 is specified in the user service default definition and s2 is specified in the user service definition, both s1 and s2 take effect in the user service definition.
(5) Compiling and linking UAPs
When you compile and link a UAP that accesses Oracle, 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 Oracle 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 Oracle in C language and in COBOL.
In C language
trnmkobj -o rm_obj -r Oracle_XA
|
In COBOL
trnmkobj -o rm_obj -C "/Zl" -r Oracle_XA
|
(6) 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)
- exproc.pc (pc file)
- 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
ORACLELIB = oraxa11.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
exproc.obj:exproc.c
$(cc) $(cflags) $(cvarsdll) $*.c
# Create a stub source file
ex_sstb.c:ex.def
$(DCDIR)\bin\stbmake $?
# Precompile
exproc.c:exproc.pc
$(ORACLE_HOME)\bin\proc release_cursor=yes $?
# Link
TP1TEST.exe: exmain.obj exsv1.obj exsv2.obj ex_sstb.obj exproc.obj
$(link) $(conflags) -out:$*.exe $** \
[$(DCDIR)\spool\trnrmcmd\userobj\rm_obj.obj \]#3
$(TP1LIB) $(SYSLIB) $(ORACLELIB)
|
- #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.
(7) 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
- pco file name 1: exprocb1.pco
- pco file name 2: exprocb2.pco
- 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
ORACLELIB = oraxa11.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
exprocb1.obj:exprocb1.cbl
$(CCBL) $(CBLFG2) exprocb1.cbl
exprocb2.obj:exprocb2.cbl
$(CCBL) $(CBLFG2) exprocb2.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 $?
# Precompile
exprocb1.cbl:exprocb1.pco
$(ORACLE_HOME)\bin\procob release_cursor=yes $?
exprocb2.cbl:exprocb2.pco
$(ORACLE_HOME)\bin\procob release_cursor=yes $?
# Link
TP1TEST.exe: main.obj sev1.obj sev2.obj ex_sstb.obj \
exprocb1.obj exprocb2.obj
$(LK) -OutputFile $*.exe $** \
[$(DCDIR)\spool\trnrmcmd\userobj\rm_obj.obj \]#3
$(TP1LIB) $(SYSLIB) $(ORACLELIB)
|
- #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.
(8) Notes about linking Oracle
- If you link OpenTP1 and Oracle while using the X/Open XA interface, make sure that all Oracle-related services are running.
- If you link OpenTP1 and Oracle 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 Oracle's SQL language is used to perform commit and rollback processing or if Oracle 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.
- Grant access permissions that enable a user with an OpenTP1 service logon account to write data to the Oracle troubleshooting information storage folder. If there is no write permission for this folder, OpenTP1 might not be able to store troubleshooting information for XA functions that are issued by OpenTP1 server processes.
- If you link OpenTP1 and Oracle while using the X/Open XA interface and either of the following messages is issued, make sure that Oracle and communication processes are running:
- The KFCA00901-W message while Oracle's communication process (part of the SQL*Net function) is not running during transaction processing or results in an error.
- Oracle's ORA-1012 message during SQL access processing.
- If you link OpenTP1 and Oracle while using the X/Open XA interface and the number of processes that use the XA interface to access Oracle exceeds the value specified in Oracle's SESSIONS definition, the KFCA00901-W message is also issued. In such a case, use the following formula and, if necessary, revise Oracle's SESSIONS definition:
Minimum value of SESSIONS definition basic number of Oracle accesses x n#1
Basic number of Oracle accesses
(total number of user service processes that access Oracle
+ number of concurrent recovery processes#2 + 1#3)
x (number of Oracle databases) |
- #1
- n indicates the number of sessions required to complete the processing from xa_open to xa_start to UOC(SQL) to xa_end to xa_close (normally about 1 to 5). For details, check the Oracle settings.
- #2
- The number of concurrent recovery processes is the trn_recovery_process_count operand value in the transaction service definition.
- #3
- 1 indicates the number of OpenTP1 resource manager monitoring processes.
- If you link OpenTP1 and Oracle while using the X/Open XA interface, Oracle's SesTm open string indicates the Oracle global transaction monitoring interval. If the value of SesTm is too small, Oracle might determine transactions without waiting for OpenTP1's instruction once the specified interval has elapsed, resulting in shutdown of the user server or of the OpenTP1 system. Be sure to specify an adequate value for SesTm.
- If you link OpenTP1 and Oracle while using the X/Open XA interface and Oracle is shut down and then restarted during transaction processing, Oracle might no longer accept requests from the process that had accessed Oracle before Oracle shut down. In such a case, the KFCA00901-W, KFCA00905-E, or KFCA00906-E message may be issued. If any of these messages is issued, terminate the corresponding server and then restart it. If the corresponding server is _trnrcv, terminate the OpenTP1 system and then restart it.
All Rights Reserved. Copyright (C) 2012, Hitachi, Ltd.