Using the VisiBroker Console

This chapter provides information about the VisiBroker Console including: managing transactions with the VisiTransact Transaction Service, tracking heuristic completions, viewing error messages, and configuring a connection to a database for data access using the Session Manager Configuration Server.

Overview of the VisiBroker Console

The VisiBroker Console provides you with an easy way to graphically monitor transaction status, view heuristic logs, view message logs, and configure database access. The VisiTransact functionality of the VisiBroker Console is divided into the following three sections:

•	Transaction Services section

•	Session Manager Profile Sets section

Transaction Services section

The Transaction Services section lets you manage VisiTransact Transaction Service instances and their transactions over the network. Also, you can monitor the status of and control the completion of transactions running under the VisiTransact Transaction Service instance you choose to monitor.

When you select the Transaction Services section, it displays all the instances of the VisiTransact Transaction Service that are running at that particular OSAGENT_PORT.

When you select an instance of the VisiTransact Transaction Service, the right panel displays three tabs. You can move between these tabs to:

•	View transactions. The Transactions tab lets you view information about the transactions for this instance of the VisiTransact Transaction Service. You can also view transaction details, force the transaction to roll back or commit, or shutdown the VisiTransact Transaction Service.

•	Monitor heuristics. The Heuristics tab lets you view information about heuristic outcomes for VisiTransact transactions. You can view the specific details for each participant of a transaction that had a heuristic outcome. For more information about heuristics, see “Managing heuristic decisions”.

•	View log messages. The Message Logs tab lets you view the error, warning, and information messages in the Message Log for all VisiTransact components on the same node as that instance of the VisiTransact Transaction Service.

Session Manager Profile Sets section

The Session Manager Profile Sets section lets you create, configure, and edit connection profiles for the Session Manager. The Session Manager provides pre-configured database connections to applications and XA Resource Directors.

Starting the VisiBroker Console

Before you start the VisiBroker Console, make sure that you start either an instance of an VisiTransact Transaction Service, or an instance of an Session Manager Configuration Server. See “Starting a VisiTransact Transaction Service” and “Starting the Session Manager Configuration Server” for instructions.

Starting a VisiTransact Transaction Service

The VisiTransact Transaction Service may have been started by the OAD. However, you can start the Transaction Service manually by using this command:

prompt>ots

For a complete list of the options for the OTS command, see “ots”.

Note

If the VisiTransact Transaction Service you want to manage is not running or is not on your network, then it will not appear in the list of VisiTransact Services you can manage with the VisiBroker Console. You can use the osfind utility to determine if the instance of the VisiTransact Transaction Service is running on your network.

Starting the Session Manager Configuration Server

The Session Manager Configuration Server may have been started by the OAD. However, you can start the Session Manager Configuration Server manually by using this command:

prompt>smconfig_server

For a complete list of the options for the smconfig_server see “smconfig_server”.

Launching the VisiBroker Console

In Windows, you can click the VisiBroker Console icon, found in the VisiBroker program group, and enter your credentials.

Alternatively, at the command prompt in either Windows or UNIX, type the following command:

vbconsole

The VisiBroker Console screen displays.

Using the Transaction Services section

You use the features in the Transaction Services section to monitor and manage transaction information for the VisiTransact Transaction Service you selected, to resolve the status of a transaction by committing or rolling back the transaction, and to shutdown an instance of the Transaction Service, monitor heuristics, and view messages.

For more information on using the Transaction Services section, see one of the following sections:

•	Locating an instance of the Transaction Service

•	Monitoring transactions

•	Refreshing the transaction list

•	Displaying details for specific transactions

•	Controlling specific transactions

•	Filtering the transaction list

•	Viewing heuristic transactions

•	Viewing heuristic details

•	Viewing the message log

•	Filtering the message logs

Locating an instance of the Transaction Service

To view a list of transactions for a specific VisiTransact Transaction Service, you must choose from the list of VisiTransact Transaction Service instances running on your network. If you want to switch to another instance, you can select a VisiTransact Transaction Service from the ones listed under Transaction Services. However, you can view only the transactions for one instance of the VisiTransact Transaction Service at a time in the Transactions tab.

Monitoring transactions

The Transactions tab displays a list of transactions for the VisiTransact Transaction Service you select. This lets you keep track of which transactions have not completed. From this list of transactions, you can view the current status and periodically, you can refresh the view to track the most current information. Use the following instructions to monitor transactions:

1	Select the instance of the VisiTransact Transaction Service you want to monitor from the list under Transaction Services. A list of transactions for that instance displays in the table.

The list provides you with the following information for each transaction:

• Transaction Name

• Status

• Host of the Transaction Originator

• Age in seconds

• The number of times transaction completion was attempted

2	To sort the list of transactions in ascending order, click on the header of the column you want to sort.

The status bar at the bottom of the screen provides additional information about the number of transactions, filtering status, and current system activity.

Refreshing the transaction list

You can refresh the list of transactions by clicking the Refresh button on the toolbar in the main window. Transactions that have completed will no longer display in the table.

Displaying details for specific transactions

You can use the Transactions tab to view the details of a specific transaction. This detailed information can provide you with insight so you can resolve the status of the transaction.

To view detail for a specific transaction select the row from the list of all the transactions.

The bottom table in the Transaction view tab displays the following information for each participant in the selected transaction:

•	IOR of the Participants

•	Host of the participant

•	Vote for Prepare

•

Outcome

The PrepareVote column contains the participant's vote. The possible values are:

•

Unknown

•

ReadOnly

•

Commit

•

Rollback

The last three values will only appear if the transaction has been prepared.

The Outcome column contains the outcome of the commit phase for a participant. The possible values are:

•

None

•

Commit

•

Rollback

•	HeuristicCommit

•	HeuristicRollback

•	HeuristicMixed

•	HeuristicHazard

Note

For more information on heuristics and the heuristic logs, see , “Managing heuristic decisions.”

Controlling specific transactions

In the Transactions tab, you can resolve the status of a transaction that has not completed by using the Force Rollback or Stop Completion functions.

•	Force Rollback can be used on any transaction that has not finished the prepare phase of completion.

•	Stop Completion tells the VisiTransact Transaction Service to stop attempting to complete the transaction. To stop the completion of a transaction, click Stop Completion.

Resolving hung or in-doubt transactions

If the transaction does not complete in a reasonable amount of time or if the outcome is in doubt, you can resolve it by either stopping or rolling back the transaction. Use the following instructions to resolve the transaction:

1	Use the instructions in “Displaying details for specific transactions” to view the details of the transaction in question.

2	Resolve the transaction by choosing either to rollback or to stop committing.

•	To rollback the transaction, click Force Rollback.

If the transaction has progressed beyond the prepare phase of completion but still exists, then the Transaction Is In Second-Phase dialog box displays indicating that you cannot rollback the transaction.

If the transaction no longer exists, then the Transaction Not Found dialog box displays indicating that the completed transaction cannot be rolled back.

•	To stop the completion of a transaction, click Stop Completion.

If the VisiTransact Transaction Service does not know about this transaction (for example, possibly because it has already completed) then the Unknown Transaction dialog box displays indicating that you can no longer resolve the transaction.

Filtering the transaction list

You can filter the transactions that you view in the Transactions tab by clicking Filter Transactions.

The Filter dialog box lets you set the filter value option in minutes and seconds. Only those transactions older than the age filter value will be displayed.

To cancel the filter option, click Filter Off from the Transactions tab.

Viewing heuristic transactions

The Heuristics tab lets you view the transactions that had heuristic outcomes and were placed in the heuristic log. To view this information:

1	Click the Heuristics tab.

VisiTransact produces one heuristic log per instance of the Transaction Service, referred to as the heuristic.log file. By default, the path to this directory is <VBROKER_ADM>/its/transaction_service/<transaction_service name>/heuristic.log. The Heuristics tab provides the following information for each item listed:

• transaction's name

• originator

• time of the heuristic outcome

2	To cancel the list of transactions from loading in the tab, click Cancel Refresh.

Viewing heuristic details

You can use the Heuristics tab to view the details of a specific heuristic completion. These details provide you with information so you can resolve the transaction.

To view the detail for a specific heuristic decision, select the row in the list of all the heuristic decisions.

The bottom table in the Heuristics view tab displays the following information for the selected transaction:

•	Participant

•

Host

•	PrepareVote

•

Outcome

•	Last Exception (This is the last exception that occurred before the heuristic occurred.)

Note

The number appearing in the header corresponds to the heuristic's place in the list of heuristics. The number for the first heuristic in the list is 1 (one).

 

The PrepareVote column contains the participant's vote. The possible values are Commit or Rollback.

The Outcome column contains the outcome of the commit phase for a participant. The possible values are HeuristicCommit, HeuristicRollback, HeuristicHazard, HeuristicMixed, or None, which means that there were no heuristics for that participant.

Note

For more information on heuristics and the heuristic logs, see “Managing heuristic decisions”

Viewing the message log

A message log is created for every physical machine running a VisiTransact Transaction Service. The message logs are located in <VBROKER_ADM>/its/message.log.

To view a list of messages for the node on which the selected Transaction Service resides, you must use the Message Log tab. The Message Log displays these messages:

•

Error

•	Information

•

Warning

Filtering the message logs

You can filter the messages in the message log by clicking Filter Messages.

This displays the Filter dialog box.

You can filter messages as follows:

•	By specifying a time window

•	By specifying the type of message to be displayed

•	By entering other criteria in the Source, Category, Code or Host fields (information entered in these fields is case sensitive)

To stop filtering, click Filter Off.

Trimming the message log

You can permanently remove entries from the message log. All messages older than the date and time you select will be removed permanently from the message log. To trim the message log:

1	Click Trim Message Log to view the Trim dialog box.

The Trim dialog box opens.

2	Set the date and time criteria and click OK. The date reads as month, day, and year. The time reads as hours, minutes, and seconds.

Using the Session Manager Profile Sets section

The Session Manager Profile Sets section lets you access the Session Manager Configuration Server. Do not confuse this with the Session Manager.

The Session Manager Configuration Server reads and writes connection profiles to the persistent store file. Once you have gained access to the Session Manager Configuration Server, you can create and configure a new connection profile or edit an existing connection profile. For more information about the Session Manager Configuration Server, see “Integrating VisiTransact with databases using the Session Manager” For more information on using the VisiBroker Console to configure connection profiles, see the following sections:

•	Gaining access to the Session Manager Configuration Server

•	Creating and configuring a new connection profile

•	Editing an existing connection profile

What are connection profiles?

A connection profile consists of all the required connection attributes to make a connection to a particular database. For more information, see “Session Manager overview”.

Attributes required to create Session Manager Configuration Profiles are specific to the type of database to which you are connecting. For example, to integrate VisiBroker VisiTransact with an Oracle DBMS, you must use the Session Manager for Oracle OCI. Then you may create a connection profile using a combination of attributes that are common to all databases, plus specific ones for Oracle.

Currently, the Session Manager provides connectivity with Oracle9i databases. See “XA Session Manager for Oracle OCI, version 9i Client” and “DirectConnect Session Manager for Oracle OCI, version 9i Client” for more information.

The Pluggable Resource Interface provides the capability to create a Session Manager to integrate with the database of your choice. See “Pluggable Database Resource Module for VisiTransact” for more information.

Gaining access to the Session Manager Configuration Server

Make sure that you have started the Session Manager Configuration Server, as described in “Starting the Session Manager Configuration Server”.

To gain access to the Session Manager Configuration Server, choose a Session Manager Configuration Server under Session Manager Profile Sets.

The profile names and details for connection profiles managed by the selected Session Manager Configuration Server appear in a table in the right hand panel.

Creating and configuring a new connection profile

Before you can create a new connection profile, you must gain access to the Session Manager Configuration Server, as described in “Gaining access to the Session Manager Configuration Server”.

Note

Alternatively, you can use the smconfigsetup utility to create connection profiles. See smconfigsetup for more information.

To create and configure a new connection profile, perform the following steps:

1	To create a new profile, click New in the right hand panel.

The New Profile dialog box appears.

Note

You can create a new profile based on an existing one by selecting the profile you wish to copy and clicking Duplicate. You can keep the same attribute settings or change them. However, you must give this new profile a unique name.

2	Enter a unique profile name in the New Profile Name field.

3	Select a database type from the DB Type drop down list box.

The database type indicates the kind of database and transactional access type for the connection profile. Each database type has particular attributes associated with it. Entering the database type will determine which attributes display in the Connection Profile Editor screen.

4

Click OK.

The Connection Profile Editor dialog box appears.

5	Fill in the Database Name field.

This field requires a value that is database dependent.

6	In the User Name and Password fields, enter the user name and password for the database.

7	Click Save.

Once you have saved, the values are written to the persistent store file and any Session Manager or XA Resource Director that has access can read from that file.

Editing an existing connection profile

Before you can edit an existing connection profile, you must gain access to the Session Manager Configuration Server. For information on how to gain access, see “Gaining access to the Session Manager Configuration Server”.

To edit an existing connection profile, perform the following steps:

1	To edit an existing profile, select the profile you want to edit from the list.

2	Click Open.

The Connection Profile Editor dialog box appears.

3	Make your changes in the Connection Profile Editor screen

4	Click Save.

See “Modifying connection profiles used by Session Manager clients” for details on when the new values will take effect.

Filtering the connection profiles

When you first access connection profiles for a Session Manager Configuration Server, it displays profiles that are common to all database types.

1	To filter the profiles by database, select a database type from the DB Type drop down list box.

Only profiles for the selected database type display in the tab.

Each database type has particular attributes associated with it. For example, if you select Oracle as the DB Type, you will only see the profiles (containing attributes) associated with Oracle databases. If there are attributes specific to Oracle databases, columns are added to the right of the common attribute columns.

2	If you want to see profiles for all databases, you can select All in the DB Type drop down list box.

Deleting a connection profile

To delete a connection profile, select it and click Delete. A confirmation dialog box appears to confirm your decision.

Refreshing the list of connection profiles

Click Refresh to update the list of connection profiles for the selected Session Manager Configuration Server.