Integrating VisiTransact with databases using the Session Manager

This chapter provides information you need to administer VisiTransact transactional applications that integrate with databases.

To integrate VisiTransact with databases, the database administrator is responsible for these tasks:

1	Evaluating the impact of integrating VisiTransact with databases.

2	Making sure databases are ready for integration with VisiTransact.

3	Setting up Session Manager Configuration Servers.

4	Configuring the connection profiles.

5	Deploying and setting up the XA Resource Directors. This involves starting the XA Resource Directors and registering them with the VisiBroker Object Activation Daemon (OAD) if appropriate. This step is only necessary when using the XA implementation of the Session Manager.

6	Starting the application objects that embed the Session Manager.

These tasks are described in detail in the sections that follow. Some of the information is presented in separate sections for XA and DirectConnect. The database administrator has other tasks in addition to the ones listed above. Additional tasks are as follows:

•	Handling heuristics.

•	Tuning for gains in performance.

•	Managing connection profile persistent store files.

These additional tasks are described in detail later on in the chapter.

Evaluating the impact of integrating VisiTransact with databases using XA

One of an administrator's most important tasks is to evaluate the impact of processing distributed transactions in a particular site's environment. Certain circumstances are inherent when processing distributed transactions. Processing a distributed transaction may not always be appropriate for the database your company is using. While making your evaluation, consider the following:

•	Using the XA protocol adds overhead.

•	The database must have a high degree of availability during two-phase commits.

•	Data may be locked or unavailable for longer periods, reducing potential concurrency.

•	The database is involved in a more sophisticated transaction. It may have to work with other application components.

These items are discussed in the following sections.

Using XA adds overhead

Generally, there is extra overhead when communicating with the database using the XA protocol and XA interface calls. The overhead incurred for XA is as follows:

•	A round trip to the database to perform the association with the transaction.

•	A round trip to the VisiTransact Transaction Service to register the database's participation in the transaction.

•	One or two round trips from the VisiTransact Transaction Service to the XA Resource Director to perform the prepare and commit processing.

With VisiTransact, the calls to associate and disassociate only happen to those database connections that the application has specifically requested to use at that time. Overhead does not incur for Resource Managers that have not been used.

Requiring high availability

If the VisiTransact Transaction Service invokes two-phase commit on a set of databases, and if any are unavailable during the prepare phase, the transaction is rolled back. Any productive work done during those transactions is lost.

Locked or unavailable data

Performing a two-phase commit may cause concurrency bottlenecks. Between data being locked and committed, the database prevents anyone from reading or modifying data which is locked by that particular transaction. For example, if you lock data in a row because you updated it, it will not be available for someone else to modify until you commit the transaction. This reduces concurrency.

Note

The behavior of databases locking data varies widely—a row or more of data could be locked depending on the database and the application.

Yielding some control

When evaluating the advantages and disadvantages of processing distributed transactions, consider that the scope of administrative tasks has increased. This causes a different set of advantages and disadvantages. You lose some control because you cannot force completion after the prepare phase has started. This is because the scope is wider and there are other components to consider. If the two-phase commit is interrupted, a heuristic outcome occurs. You can force a heuristic outcome using database utilities.

For more information about how the VisiTransact Transaction Service handles heuristics, see “Transaction completion”.

Evaluating the impact of integrating VisiTransact with databases using DirectConnect

There are fewer administration duties for DirectConnect transactions than for XA transactions.

Restrictions when using DirectConnect are as follows:

•	Only one Resource (the DirectConnect Resource) can participate in the transaction.

•	The transaction work with one database is restricted to one process.

Advantages to using DirectConnect are:

•	Simpler deployment scenarios

•	Reduced RPCs to the database for XA coordination

Preparing databases

Before you can use the features in the Session Manager, check with the database administrator that the database has the required software subsets for distributed transaction access. Your database administrator may need to modify your database installation by loading additional libraries, running SQL scripts in the database, modifying configuration parameters for the database server, and installing client-side libraries. For more information, see “XA Session Manager for Oracle OCI, version 9i Client” and “DirectConnect Session Manager for Oracle OCI, version 9i Client”.

In general, for DirectConnect, there are no additional steps in preparing your database because the connections are regular user connections.

Connection profile sets

For the Session Manager to connect to a database, it must be supplied with information about how to make that connection. The information is packaged into a set of attributes called the connection profile. Connection profiles are created using the VisiBroker Console, or using the smconfigsetup utility, and saved onto disk so that they can be persistently stored and retrieved by the Session Managers running in the application servers. Because the connection profiles are available on disk, the Configuration Servers do not have to be running continuously. A profile set (logical grouping of connection profiles) is associated with the same Configuration Server. Each Configuration Server is identified by a unique name. This section provides information to help you manage connection profile persistent store files.

Note

You may want to decouple changes made to profile attributes by an application's Session Manager from the profile attributes used by the XA Resource Director. To do so, create separate connection profiles for the Session Manager and the XA Resource Director.

The profile sets are stored in persistent storage files. You can locate the persistent storage files in the default location, or you can use different locations and then point to these locations using the argument -Dvbroker.sm.pstorePath.

Modifying connection profiles used by Session Manager clients

To modify a connection profile used by Session Manager clients:

1	Change the connection profile using the VisiBroker Console.

2	Shut down any application processes which use this connection profile.

3	Restart the application processes.

Modifying connection profiles used by XA Resource Directors

To modify a connection profile used by the XA Resource Director:

1	Change the connection profile using the VisiBroker Console.

2	Shut down any application processes which use the affected XA Resource Director.

3	Shut down and restart the XA Resource Director.

Note

While it is possible to leave the application processes running, transactions which attempt completion while the XA Resource Director is shut down may be rolled back.

Using the XA Resource Director

The XA Resource Director is used in conjunction with the XA implementation of the Session Manager for transaction completion and recovery processing. The XA Resource Director is deployed as a standalone program.

If you are using the DirectConnect implementation of the Session Manager, an XA Resource Director is unnecessary.

Deploying an XA Resource Director

Deploy an instance of the XA Resource Director for each database server accessible from VisiBroker VisiTransact. The XA Resource Director should be running whenever the database server is running if the XA implementations are being used. This way the Resource Director is available to take part in the completion and recovery protocols.

We recommend that only one XA Resource Director be deployed for each database for the same OSAGENT_PORT. Having multiple XA Resource Directors on the same OSAGENT_PORT for the same database is inefficient because, although they are successful at committing and rolling back transactions during normal operation, they also duplicate recovery operations if the VisiTransact Transaction Service goes down and comes back up. This results in overloading the VisiTransact Transaction Service with replay requests when it has finished its internal recovery cycle.

Starting an XA Resource Director

Start the XA Resource Director with the following command:

prompt>xa_resdir -Dvbroker.sm.profileName=<profile>
[-Dvbroker.sm.pstorePath=<path>] [-Dvbroker.sm.configName=<name>]

The following table describes the start-up parameters for the XA Resource Director.

Parameter	Description
-Dvbroker.sm.profileName=<profile>	The name of the Session Manager connection profile you want to use to establish a connection with the database. This is required.
-Dvbroker.sm.pstorePath=<path>	The path to the directory where the persistent store files are located. By default, the persistent store files are located in <VBROKER_ADM>/its/session_manager/.
-Dvbroker.sm.configName=<name>	The name of the Session Manager Configuration Server you're using. By default, the name assigned to the Session Manager Configuration Server is <host>_smcs where host is the name of the server on which you created the Session Manager connection profile. This can also be thought of as the profile set name.

For information about what defaults are used if you do not specify the -Dvbroker.sm.pstorePath parameter, see “Checking for the default path to persistent store files”. For information about how to set up a Session Manager connection profile, see “Using the Session Manager Profile Sets section”.

How the XA Resource Director uses connection profiles

Besides creating connection profiles for the Session Manager, you must create them for the XA Resource Directors as well. Depending on what attributes they need for configuring connections, the Resource Director may use the same profile as some of the Session Managers use; it might use a profile that none of the Session Managers use. While there might be multiple profiles that Session Managers use to contact one database, the XA Resource Director for that database uses only one profile.

Deploying client-side libraries

The Session Manager and the XA Resource Director must be able to access the client-side database libraries, including the XA client-side library for the databases that the Session Manager and XA Resource Director objects will be accessing.

Shutting down an XA Resource Director remotely

To shut down an XA Resource Director remotely, use the following command:

prompt> vshutdown -type rd [-name <ITS_XA_Resource_Director_name>]

The XA Resource Director's type (rd) is a required argument.

You can find the name of the Resource Director by either using the osfind command, or by looking at the connection profile. To avoid confusion, it is best to name the Resource Director the same name as its connection profile and database name. See “vshutdown” for more details on using the vshutdown command.

Registering the XA Resource Director with the OAD

To start the XA Resource Director without operator intervention, register it with the VisiBroker OAD (Object Activation Daemon). Implementations of the XA Resource Director can be registered using the oadutil reg command-line interface.

The syntax for registering an XA Resource Director with the OAD is as follows:

oadutil reg -i visigenic.com/VISSessionManagerSupport/ImplicitResource
-o <resource_director_name> -cpp <installation_dir_path>/bin/xa_resdir -a
-Dvbroker.sm.profileName=<profile> -a -Dvbroker.sm.pstorePath=<path> -a -Dvbroker.sm.configName=lt;name>

The following table describes the parameters for registering the XA Resource Director with the OAD.

Parameter	Description
resource_director_name	This is the name of the XA Resource Director you wish to register with the OAD, and the object name that will be activated. We recommend that the profile used to start the Resource Directors be named the same as the Resource Director name in the profile, and reflect the database name. In installations with multiple databases, this makes it easy to associate Resource Directors with profile names.

Note

For description of the profile, path, and name parameters, see “Starting an XA Resource Director”.

The connection profile used to start the XA Resource Director should be named the same as the XA Resource Director name in the profile. Additionally, it should be the same as the database name. In installations with multiple databases, this makes it easy to associate XA Resource Directors with profile names.

See “Using the Session Manager Profile Sets section” for details on how to set up a Session Manager connection profile.

Note

The OAD must be running before you can use any of the OAD commands. Refer to Starting the OAD in the VisiBroker for C++ Developer's Guide for instructions on starting the OAD. When registering an object implementation, use the same object name that is used when the implementation object is constructed.

Starting Session Manager-based application processes

It is not necessary for an administrator to explicitly start up the Session Manager. The Session Manager is started and initialized automatically in the programs in which it is used. The ORB initialization accesses the command-line arguments that contain the connection profile attributes and any other options relating to the Session Manager.

If you want to use a path other than the default, or a profile set name other than the default, use the following arguments when starting the application so that the persistent store of connection profile attributes is used:

-Dvbroker.sm.pstorePath=<path> -Dvbroker.sm.configName=<name>

The path argument is not required. If you do not specify a path argument, see “Checking for the default path to persistent store files” on page 114 for information about how the Session Manager and the Session Manager Configuration Server check for the default path and profile set name.

Note

See “Starting an XA Resource Director” for a description of the command-line arguments to application for the Session Manager.

Checking for the default path to persistent store files

When using the Session Manager, the -Dvbroker.sm.pstorePath argument is not required. If you do not specify the path argument, the Session Manager and the Session Manager Configuration Server check the following settings in this order:

1	What you set in the command-line argument for -Dvbroker.sm.pstorePath. If you did not specify the path at the command line, it checks:

2	What was set with the VBROKER_ADM environment variable. This is the default when you accept all the defaults during installation. VisiTransact puts the persistent store files in subdirectory its/session_manager under VBROKER_ADM.

Forcing heuristics

You may use database utilities to monitor transactions after they reach the prepare phase. In some cases, you may need to interfere to resolve transactions; for example, in the case of long-lived failures with the VisiTransact Transaction Service or one of its participants, or a failure in network connectivity. When a database administrator intervenes to commit or roll back a prepared transaction without using the VisiTransact Transaction Service, the resulting state is called a heuristic. This means that the database may have completed the transaction in a way different than the VisiTransact Transaction Service has. Most databases which support two-phase commits have interfaces for forcing heuristics.

For more information about how the VisiTransact Transaction Service handles heuristics, see “Transaction completion”.

Performance tuning

When you have the VisiTransact Transaction Service embedded in the application server, the client should ensure that it binds to the correct instance of the VisiTransact Transaction Service to realize the potential performance gains.

See “Embedding a VisiTransact Transaction Service instance in your application” for more information on embedding a VisiTransact Transaction Service in your application server.

For XA

Reducing network traffic increases performance when using the VisiTransact Transaction Service with distributed transactions. To reduce network traffic, you can locate some of the components on the same node as the VisiTransact Transaction Service instance, or on the same node as the database. Communication occurs between the Session Manager and the VisiTransact Transaction Service, the Session Manager and the database, the VisiTransact Transaction Service and the XA Resource Director, and the XA Resource Director and the database. Localizing these components on the same node will reduce network traffic. Consider trying to locate the transactional objects which use the Session Manager on the same node with the VisiTransact Transaction Service or the database, and locate the XA Resource Director with the database or with the VisiTransact Transaction Service.

Session Manager Configuration Server

The Session Manager Configuration Server represents one set of connection profiles and servers as the agent for VisiBroker Console. Its purpose is to provide network access for the VisiBroker Console to the connection profiles.

Directory structure for persistent store files

By default, the persistent store files are located on disk in the connection profile set subdirectories. You can use the default directory or specify another one. The default path may be overridden during installation, or when using the command line flag -Dvbroker.sm.pstorePath, or with any process that uses the Session Manager (including the XA Resource Director).

For information about how the Session Manager and the Session Manager Configuration Server checks for the default path to the persistent store files, see “Checking for the default path to persistent store files”.

Caution

There is a directory called install under the session_manager directory. Do not change anything in the install directory or add files to it manually. This directory is created automatically when you install VisiTransact.

When you create a connection profile with the VisiBroker Console, a corresponding file is created in a subdirectory in the session_manager/config directory. The name of subdirectory file corresponds with the Session Manager Configuration Server's name and can be considered the profile set name. By default, the Configuration Server's name consists of <host>_smcs where host is the name of the machine where the Configuration Server resides. For example, if the machine's name is athena, the Configuration Server is named athena_smcs. In the subdirectory for the Configuration Server, the connection profiles are stored, one per file. You can give the connection profiles significant names like test_oracle_xa. The name you give a connection profile using the VisiBroker Console is automatically assigned to its associated persistent store file. You do not have to manually create the persistent store files—they are created by the Session Manager Configuration Server when you use the VisiBroker Console. VisiTransact adds the extension .cfg to the persistent store file, as shown in the following example.

test_oracle_xa.cfg

Note

When you create names for the connection profiles using the VisiBroker Console, the case sensitivity rules for these names are the same as the rules used by your file system where these names are stored. For example, on UNIX if you mix the upper and lower case when you assign the connection profile name, that is what you must use when you try to find it later.

While the persistent store files are binary and cannot be edited by hand, it is possible to copy them to alternate locations as backups. Or, you can copy an entire <configuration_server> subdirectory to another location and rename it with a different profile set name.

It is possible to partition connection profile sets so that you have multiple connection profile sets on the same node. Unless there is a strong reason for doing this, it usually has few advantages. If you have more than one profile set on a node, a subdirectory is created in the session_manager/config (even on different nodes) directory for each profile set. Do not create multiple profile sets with the same name since you will not be able to distinguish them from the ones you create with the VisiBroker Console.

Note

A process using the Session Manager can only access one connection profile set by going to the default location, or to any location you have specified using command-line arguments. It is confined to that namespace for the default location, or location specified by the command-line arguments. It cannot access locations that are not specified. For example, an instance of a Session Manager in a particular application process may only access the Marketing connection profile set. It may not access the Payroll connection profile set.

Deploying persistent store files

Every node which is running an application that uses the Session Manager must be able to read the persistent store files from disk. Consequently, you have several options when deploying the persistent store files:

•	Option 1: One Configuration Server exists on one of the nodes in a connected group of nodes. The on-disk set of persistent store files is shared through a shared file system.

•	Option 2: A uniquely-named Configuration Server and its on-disk set of persistent store files exist on each node.

•	Option 3: One Configuration Server is shared by a connected group of nodes. There is no shared file system. When the on-disk set of persistent store files changes, you must manually copy the sets of persistent store files from the master location to the other nodes.

Option 1: Persistent store files on a shared file system

The preferred method of deployment is to place the set of persistent store files on a shared file system. When VisiTransact is installed, a Session Manager Configuration Server with an associated on-disk set of persistent store files is deployed on only one node. When installing VisiTransact on the node which runs the Session Manager Configuration Server, you can specify the directory structure for the persistent store files so that it will be created in this shared disk.

After installation, the VisiBroker Console can be used to update all Session Manager connection profiles that are used on this network. They will all appear in one set of connection profiles. Application servers which use the Session Manager on other nodes must be configured so that when they start up they look at the shared disk containing the persistent store (using -Dvbroker.sm.pstorePath=<path>). When you use the VisiBroker Console to update connection profiles, the modified profile will be seen by application servers when they start up.

Note

Because the connection profiles are shared with this option, it is very important that there is only one instance of the Session Manager Configuration Server used in this group of nodes.

Option 2: Persistent store files on each node

Each node that runs the Session Manager has its own Configuration Server and set of persistent store files. One VisiBroker Console on the network can make modifications to each on-disk persistent store file. If you update a connection profile on one node, you have to update it on the other nodes through the VisiBroker Console so that the other nodes are updated with the change too.

This option has the advantage that no disk sharing is needed, but adds much complexity in synchronizing the connection profiles across many nodes. Neither the VisiBroker Console nor the Session Manager Configuration Server processes can synchronize different on-disk sets of connection profiles.

Option 3: Set of persistent store files copied to each node

To distribute the on-disk cache around the network, you can create a master set of persistent store files and manually copy them to each node. Like the previous option, this option has the disadvantage of trying to keep numerous nodes synchronized. However, it may be easier to copy the profile files using operating system or network copy commands than to update each persistent store file using the VisiBroker Console.

Note

You can copy all persistent store files in a Configuration Server subdirectory or just one persistent store file at a time. You must copy the entire install subdirectory too if it does not already exist in the target location.

Starting the Session Manager Configuration Server manually

Once a Session Manager Configuration Server is registered with the OAD, the OAD can start it automatically; however, if you would like to start the Configuration Server manually, use the following command:

prompt>smconfig_server [-Dvbroker.sm.pstorePath=<path>] [-Dvbroker.sm.configName=<name>]

The following table describes the start-up parameters for the Session Manager Configuration Server.

Parameter	Description
-Dvbroker.sm.pstorePath	Provide the path to the directory where the persistent store files are located. By default, the persistent store files are located in <VBROKER_ADM>/its/session_manager.
-Dvbroker.sm.configName	Provide the name of the Session Manager Configuration Service you're using. By default, the name assigned to the Session Manager Configuration Server is <host>_smcs where host is the name of the server on which you created the Session Manager profile.

Shutting down the Configuration Server

You may want to shut down the Session Manager Configuration Server for the following reasons:

•	If you need to perform maintenance.

•	If an error occurs.

•	If you need to reboot the machine the server is on.

Use this command when you want to shut down a Session Manager Configuration Server manually:

prompt>vshutdown -type smcs [-name <smcs_name>]

The Session Manager Configuration Server name should be the one used in the command-line argument -Dvbroker.ots.configName when you started the Configuration Server, or the default name which is <host>_smcs.

Note

If someone else is using the VisiBroker Console to change or create a connection profile that is associated with the same Session Manager Configuration Server that you are trying to shut down, the Session Manager Configuration Server will finish the work and then will shut down.

See “vshutdown” for more information on the vshutdown command.

Security

Database passwords are secure in the sense that they are not displayed through the VisiBroker Console. Applications which link with the Session Manager are able to query cleartext versions of database passwords. Since read access to the configuration files is required of these applications, you can control access to database passwords by restricting access to the connection profile persistent store files. It is up to the application developer and system administrator to provide proper file access permissions and develop applications which do not disclose password information to unauthorized users.