Integrating a Resource Manager with TUXEDO System

This chapter describes how a resource manager (RM) can be integrated with the TUXEDO System. The resource managers can be either XA compliant or not.

Using TUXEDO System with a RM That Is XA Compliant

The TUXEDO System transparently supports both the Preliminary Specification and the CAE Specification of the X/OPEN XA interface.

Required XA Interface Information

The vendor supplying a resource manager conforming to the X/OPEN XA interface must, in addition to publishing the application interface (for example, the DML), publish the following four items specifically pertaining to the XA interface:

Resource Manager Name: This is the name of the resource manager that is contained in the name element of the xa_switch_t structure (refer to the structure referenced in the next bullet item). It may be up to 31 characters in length. It should be unique so that it is not likely to match the name of a resource manager chosen by another vendor (for example, "sql" is not a good choice). Also, if a vendor supplies multiple resource managers or more than one interface level of the same resource manager, a name that is more specific than simply the vendor name should be chosen. For example, vendor XYZ that offers both SQL and a printer resource manager might choose "XYZ/SQL" and "XYZ/PRINTER" as the resource manager names.
XA Structure Name: This is name of the structure of type xa_switch_t that contains the name of the resource manager, the flags indicating capabilities of the resource manager, and the function pointers for the actual XA functions. This structure is used directly by the Transaction Monitor.
Library Name(s): The object code that provides the services of the XA interface and supporting software is assumed to reside in files (.o object files, .a archive files, or .so shared objects) that can be linked with a C language main program. The list of files needed to support the XA interface must be provided in the order that they must be specified to the linker. These files must be stored in a well known place to the application such that either a full pathname can be given for the files or a pathname relative to a shell environment variable can be given (for example, ${XYZ}/lib/libxyz.a ${XYZ}/lib/libsort.a). In the latter case, this shell environment variable must be set and exported when the Transaction Monitor server (TMS) and application servers are built, as described below.
Format of Open and Close Strings: Each XA implementation of xa_open and xa_close may require a different format for the information strings passed to these functions. For an XA implementation where the open/close is optional (for example, the functions do not really do anything - the real open/close may be done directly by the application through the DML), the information string may be the null string (""). A DBMS vendor might choose to require information such as the name of the database, the location of the database, and the open mode separated by some specified separator. For example, it could look like the following:
```
empdb:/dev/rdsk/c1d1s8:readwrite
```

Integration with TUXEDO System

Assuming that the TUXEDO System binary image has been installed under a directory that is pointed to by $TUXDIR (TUXDIR must be exported) and that the resource manager is also installed on the system, there are four steps to integrate the new resource manager.

The first step to integrating a new resource manager into the TUXEDO System is to provide the XA interface information so that it can be used for building servers. This is done by updating the file ${TUXDIR}/udataobj/RM. The format of the RM file is
```
rm_name:rm_structure_name:library_names
```
where these three items match the information published by the vendor above. White space (tabs and/or spaces) is allowed before and after each of the values and may be embedded within the library_names. The colon (:) character may not be embedded within any of the values. Lines beginning with a pound sign (#) are treated as comments and are ignored.
The second step is to create a transaction monitor server (TMS) for the new resource manager. A unique name must be chosen for this program such that it does not conflict with TMS programs for other resource managers (currently, TMS, TMS_D, and TMS_SQL are reserved). The TMS server is created by executing:
```
$TUXDIR/bin/buildtms -r rm_name -o $TUXDIR/bin/outputfile
```
where rm_name is the resource manager name as published by the vendor and stored in the resource manager table in step 1, and outputfile is the chosen name for the TMS program. Note this program is being stored in $TUXDIR/bin so that the TUXEDO System boot program can find it.
The third step is to link all applications servers with the new resource manager. This is done by using the buildserver(1) command with the -r rm_name option, where rm_name is the resource manager name as published by the vendor and stored in the resource manager table in step 1. An example might be
```
$TUXDIR/bin/buildserver -r rm_name -f svcfile.o -s SVC1,SVC2 -o myserver
```
where the -r option is used to specify the resource manager name, the -f option is used (one or more times) to specify the files containing the application services, the -s option is used to specify the application service names for this server, and the -o option is used to specify the output server file name.
The fourth step is to set up the configuration file, UBBCONFIG, to correctly reference the new resource manager. In the *GROUPS section of the configuration file, each group entry is associated with a single resource manager. This is done with the TMSNAME, OPENINFO, and CLOSEINFO parameters. The TMSNAME parameter value should be set to the file name that is the output filename chosen for the TMS program (this assumes it was installed in $TUXDIR/bin - if it was installed elsewhere, the full pathname with no shell variables must be given). The TMSCOUNT parameter indicates how many invocations of the program should exist (the default is three). The OPENINFO parameter value must be the string to be passed to the xa_open function for the resource manager prefixed with rm_name: (the published name of the resource manager followed by a colon with no white space). For a vendor that does not require information on open, the null string may be supplied (it is not required to enter rm_name:) or the OPENINFO parameter may be omitted. The CLOSEINFO parameter value must be the string to be passed to the xa_close function for the resource manager prefixed with rm_name: (the published name of the resource manager followed by a colon with no white space). For a vendor that does not require information on close, the null string may be supplied or the CLOSEINFO parameter may be omitted. The servers, as created with buildserver, are specified in the *SERVERS section of the UBBCONFIG file. Each is associated with the server group entry appearing in the *GROUPS section via the SRVGRP parameter value.

This completes the setup of an application using a resource manager that supports the XA interface through the TUXEDO System to do distributed (two-phase commit) transactions. Note that since the TUXEDO System does not currently handle the booting of processes that are not TUXEDO System servers, it may be necessary as part of application start-up to first execute some resource manager processes before using the TUXEDO System tmboot program to boot the application servers.

Using TUXEDO System with a RM That Is Not XA Compliant

The client/server architecture provided by the TUXEDO System can be used by an application accessing a non-XA compliant resource manager.

TUXEDO System applications using a non-XA compliant resource manager cannot use all the capabilities of the Distributed Transaction Processing (DTP) facility. DTP allows a series of actions that involve multiple server groups and/or resource managers to act as a single unit of work. One of the main jobs of the TUXEDO System is to coordinate the termination of the distributed transaction. The TUXEDO System assumes that each resource manager provides the necessary capabilities for persistence, isolation, and recovery of the data managed by that resource manager.

The XA interface is a basis for the integration of a resource manager within the DTP facility provided by the TUXEDO System. This interface provides an abstraction of the control and the two-phase commitment protocol required to coordinate the termination of distributed transactions.

As a result, an application using a non-XA compliant resource manager must be structured according to the following guidelines:

Servers using a resource manager that is not XA compliant are like servers that do not use any resource manager.
Clients cannot include within a distributed transaction a request for a service offered by a non-XA compliant resource manager. Therefore, the DTP facility can not be used with all its power. (Note that distributed transactions are optional within the TUXEDO System.) The TUXEDO System returns an error when a service request is issued within a transaction to a server of this type. Therefore, application programs issuing such a request must explicitly exclude the request from the current transaction by using the TPNOTRAN flag.

Integration with TUXEDO System

The TUXEDO System binary image must be installed under a directory that is pointed to by $TUXDIR. The resource manager must also be installed somewhere on the system. The following are the rules that application programmers must consider when using a non-XA compliant resource manager:

Build servers using the buildserver(1) command without the -r option. An example might be
```
$TUXDIR/bin/buildserver -f svcfile.o -s S1,S2 -o myserver -l "rmlib1 rmlib2"
```
where the -f option is used (one or more times) to specify the files containing the application services, the -s option is used to specify the application service names for this server, the -o option is used to specify the output server file name, and the -l option is used to specify the resource manager libraries used by the application. (See the chapter "Writing Service Routines" of the TUXEDO Programmer's Guide.)
The configuration file, UBBCONFIG, must be set up to define the services, servers, and server groups so they correctly reference the new resource manager. (See Chapter 3, "Services, Servers Server Groups" An entry must be defined in the *GROUPS section of the UBBCONFIG file. The group represents the servers accessing the resource manager. An entry must be added in the *SERVERS section for each server; the SRVGRP parameter should refer to the previously defined group name.
Servers using non-XA compliant resource managers cannot participate in any distributed transaction. Hence, if a client application starts a distributed transaction that uses services offered by those servers, then the client must explicitly exclude the request from the transaction (option TPNOTRAN); otherwise, TUXEDO rejects the request with an error (TPETRAN).