Chapter 5: Performing BEA TUXEDO Operations

Introduction

As an administrator, you can use the BEA TUXEDO Web-based Graphical User Interface (GUI) to perform the following operations on your BEA TUXEDO application:

Adding New Objects

 For information about adding new BEA TUXEDO objects, see Chapter 3, "Creating New Domains and Administrative Class Objects."

Modifying Objects

For information about modifying existing BEA TUXEDO objects, see Chapter 4, "Configuring Administrative Class Objects."

Quick Menu Options

To perform most BEA TUXEDO operations, you can select options from the Quick Menu that is displayed when you position the cursor over an object name and press the right mouse button. The options available in the Quick Menu vary depending upon the object class. This section provides a general description of each Quick Menu option; the rest of this chapter provides more detailed instructions on when and how to perform the BEA TUXEDO operations represented by these Quick Menu options.

To perform the following function Use this Quick Menu option
Display the tabbed folders containing information about a selected object View
Change one or more parameters for a selected object Edit
Add a new BEA TUXEDO object New
Delete a BEA TUXEDO object Delete...
Indicate which classes of objects you want to see represented in the tree Folders...
Activate a selected object Activate...
Deactivate a selected object Deactivate...
Migrate the Master and Backup servers in a distributed configuration Swap
Detect and remove dead clients and servers; remove partitioned machines Clean
Move groups of servers to an alternate processor Migrate
Establish a connection (bridge) between two machines Connect
Advertise a service Advertise
Hide a currently advertised object from other applications Unadvertise
Prevent the application from accessing a service Suspend
Make a currently suspended service available Resume
Terminate a BEA TUXEDO client or service Kill
Stop a transaction that is currently in progress and roll back all affected data Abort
Allocate and initialize shared memory and semaphores for a /Q queue space Open
Remove shared memory and other IPC resources for a /Q queue space Close

Common Quick Menu Options

This section provides a description of the more common Quick Menu Options.

About the View Option

To view detailed configuration information about a BEA TUXEDO object, click the right mouse button on the object name and choose View from the Quick Menu.

About the Edit Option

To make changes to the configuration of a BEA TUXEDO object, click the right mouse button on the object name and choose Edit from the Quick Menu.

About the New Option

To create a new BEA TUXEDO object, click the right mouse button on the object class name in the Object Tree and choose New from the Quick Menu. A screen will be displayed prompting you to enter required information about the new object. For detailed information about filling in these fields, see Chapter 3, "Creating New Domains and Administrative Class Objects."

About the Delete Option

To delete a BEA TUXEDO object, click the he right mouse button on the object name and choose Delete from the Quick Menu. You cannot delete all BEA TUXEDO objects in this fashion.

About the Folders Option

The Folders option on the Quick Menu allows you to customize your view of the Object Tree so that you see only the type(s) of object you want to see. You can use this option to limit the Object Tree to displaying only one class of object or you can choose to display every object. To use the Folders option, complete the following steps:

  1. Click the right mouse button on the object name and choose Folders from the Quick Menu. A list of object classes is displayed.

  2. Use the left mouse button to place a check in the box in front of each object class you want to see represented in the Object Tree or to remove the check if you don't want to see that class of objects.

  3. Click on the OK button at the bottom of the list.

Connecting to and Disconnecting From a Domain

 There are a number of operations that you can perform only when you are connected to a domain. These include:

How to Connect to a Domain

 To explicitly connect to a particular domain, complete the following steps:

  1. Choose the name of the domain you want to open from the Domain menu or select Open from the Domain menu.

  2. If prompted, enter the name of the Domain you want to open in the Domain Name field and the full TUXCONFIG file path in the TUXCONFIG File field.

  3. If prompted, enter your login name in the Login Name field and your password in the Password field. If the connection is successful, the fields in the configuration tool area will display information about the domain.

How to Disconnect From a Domain

 The BEA TUXEDO Web-based GUI automatically disconnects you from a domain whenever necessary (for example, when you choose another domain name from the pull-down menu of Domains). To explicitly disconnect from the domain to which you are currently connected, exit the GUI by choosing Exit Application from the Domain menu.

Activating the BEA TUXEDO Application

As the BEA TUXEDO administrator, you are the only user, aside from root, who is authorized to activate the BEA TUXEDO application. You must perform the initial activation process on the Master machine on which the application configuration file is located.

You can activate the following objects using the Activate Objects screen:

Introducing the Activate Objects Screen

 You use the Activate Objects screen, shown below, to select the object(s) you want to activate.

Figure 5-1: Activate Objects Screen

Six tabbed folders are displayed on the Activate Objects screen. To activate the entire domain or a particular type of object, you must select the appropriate tabbed folder.

To Activate Select the
The entire domain Domain folder
A selected list of machines Machine folder
A selected list of groups Group folder
A selected list of servers Server folder
A selected list of workstation listeners WSL folder
For future use WSH folder

Selecting Objects to Activate

Two lists appear on the Activate folders for all objects except Domains: ACTIVATE THESE and DO NOT ACTIVATE THESE. The BEA TUXEDO objects on the ACTIVATE THESE list will be activated; objects on the DO NOT ACTIVATE THESE list will not be activated. By moving an object name into the appropriate list, you can specify whether the object will be activated or not.

Figure 5-2: Activate These and Do Not Activate These Lists

How to Move Objects from One List to Another

To move objects from one list to another, complete the following steps:

  1. In one column, click on the object name(s) you want to move.

  2. To move the highlighted object name(s), choose one of the following options.

    To move the highlighted object name to the Click on the
    DO NOT ACTIVATE THESE list Right arrow button
    ACTIVATE THESE list Left arrow button

  3. Repeat Steps 1 and 2 until every object name is in the appropriate list

Activating Only Administrative Servers

 The Bulletin Board Liaison Processes (BBLs) and the Distinguished Bulletin Board Liaison Process (DBBL) are BEA TUXEDO administrative servers. Generally, these servers are activated first. If a BBL fails to activate, the other servers on that machine will not be activated. If the DBBL fails to activate, the entire application's activation process fails.

You can choose whether to limit your activation to BBLs and the DBBL when activating the entire Domain or selected Machines. Turning on the Only Activate Administrative Servers option on the Activate Objects screen means that only BBLs and the DBBL will be activated.

How to Activate Only Administrative Servers

To activate only administrative servers, click on the Only Activate Administrative Servers button. A checkmark is displayed in the box when the option is turned on.

How to Activate an Object

To activate an object, complete the following steps:

  1. Click on the Activate icon in the Power Bar, choose Activate from the Tools menu, or click the right mouse button on the appropriate object name and choose Activate from the Quick Menu. The Activate Objects screen is displayed.

  2. Click on the appropriate tab for the type of object you want to activate. The activation folder is displayed.

  3. If the "Only Activate Administrative Servers" button is displayed and you want to activate only administrative servers, click on the "Only Activate Administrative Servers" button. For more information about this option, see "Activating Only Administrative Servers" on page 8.

  4. If necessary, move the individual object(s) you want to activate into the ACTIVATE THESE list and all other objects into the DO NOT ACTIVATE THESE list. For more information about these two lists, see "Selecting Objects to Activate" on page 8.

  5. Click on the Activate button at the bottom of the screen. The Progress of Activate screen is displayed. For more information about this screen, see "Introducing the Progress of Activate Screen" on page 9.

Introducing the Progress of Activate Screen

 As objects are activated, the Progress of Activate screen is displayed. The Progress of Activate screen tracks the status of the activation process as it occurs. You can:

Deactivating the BEA TUXEDO Application

 You can deactivate the following objects using the Deactivate Objects screen:

Introducing the Deactivate Objects Screen

 You use the Deactivate Objects screen, shown below, to select the object(s) you want to deactivate.

Figure 5-4: Deactivate Objects Screen

Six tabbed folders are displayed on the Deactivate Objects screen. To deactivate the entire domain or a particular type of object, you must select the appropriate tabbed folder.

To Deactivate Select the
The entire domain Domain folder
A selected list of machines Machine folder
A selected list of groups Group folder
A selected list of servers Server folder
A selected list of workstation listeners WSL folder
For future use WSH folder

Selecting Objects to Deactivate

Two lists appear on the Deactivate folders for all objects except Domains: DEACTIVATE THESE and DO NOT DEACTIVATE THESE. The BEA TUXEDO objects on the DEACTIVATE THESE list will be deactivated; objects on the DO NOT DEACTIVATE THESE list will not be deactivated. By moving an object name into the appropriate list, you can specify whether the object will be deactivated or not.

Figure 5-5: Deactivate These and Do Not Deactivate These Lists

How to Move Objects from One List to Another

To move objects from one list to another, complete the following steps:

  1. In one column, click on the object name(s) you want to move.

  2. To move the highlighted object name(s), choose one of the following options.

    To move the highlighted object name to the Click on the
    DO NOT DEACTIVATE THESE list Right arrow button
    DEACTIVATE THESE list Left arrow button

  3. Repeat Steps 1 and 2 until every object name is in the appropriate list.

Deactivating Only Application Servers

 Application servers are user-defined or TUXEDO-defined servers configured by the user in the UBBCONFIG file. Turning on the Only Deactivate Application Servers option on the Deactivate Objects screen means that all application servers will be deactivated and only BBLs and the DBBL will remain active.

How to Deactivate Only Application Servers

To deactivate only application servers, click on the Only Deactivate Application Servers button. A checkmark is displayed in the box when the option is turned on.

Forcing Deactivation

If you attempt to deactivate the domain or a machine while there are clients still connected to the machine, the deactivation will fail. However, you can choose to force deactivation even if clients remain connected.

How to Force Deactivation

To force deactivation even if clients remain, click on the Force Deactivate Even If Clients Remain button. A checkmark is displayed in the box when the option is turned on.

How to Deactivate an Object

To deactivate the entire domain, complete the following steps:

  1. Click on the Deactivate icon in the Power Bar, choose Deactivate from the Tools menu, or click the right mouse button on the appropriate object name and choose Deactivate from the Quick Menu. The Deactivate Objects screen is displayed.

  2. Click on the appropriate tab for the type of object you want to deactivate. The deactivation folder is displayed.

  3. If the "Only Deactivate Application Servers" button is displayed and you want to deactivate only application servers, click on the "Only Deactivate Application Servers" button. For more information about this option, see "Deactivating Only Application Servers" on page 13.

  4. If the "Force Deactivate Even If Clients Remain" button is displayed and you want to force deactivation even if clients remain, click on the button "Force Deactivate Even If Clients Remain" button. For more information about this option, see "Forcing Deactivation" on page 13.

  5. If necessary, move the individual object(s) you want to deactivate into the DEACTIVATE THESE list and all other objects into the DO NOT DEACTIVATE THESE list. For more information about these two lists, see "Selecting Objects to Activate" on page 8.

  6. Click on the Deactivate button at the bottom of the screen. The Progress of Deactivate screen is displayed. For more information about this screen, see "Introducing the Progress of Deactivate Screen" on page 14.

Introducing the Progress of Deactivate Screen

 As objects are deactivated, the Progress of Deactivate screen is displayed. The Progress of Deactivate screen tracks the status of the deactivation process as it occurs. You can:

Migrating Server Groups and Machines

 Using the web-based GUI, you can migrate server groups and machines to alternate processors. This allows you to schedule downtime maintenance for the original machine. A server group is the smallest unit that can be migrated to an alternate location.

Prerequisites

Before you can migrate server groups and machines, MIGRATE must be an option for the domain (see the Options field on the System Parameters folder for the domain) and a backup machine must be specified (see the Master, Backup Machine field on the General folder for the domain).

When you migrate a server group, the environment on the destination machine must duplicate the environment on the source machine, including all packages such as database software and any other application software necessary to run the BEA TUXEDO application.

Introducing the Progress of Migrate Screen

As objects are migrated, the Progress of Migrate screen is displayed. The Progress of Migrate screen tracks the status of the migration process as it occurs. You can:

How to Migrate a Server Group to Another Machine

 To migrate a server group from the machine on which it is located to another machine, complete the following steps:

  1. Click on the Migrate icon in the Power Bar or click the right mouse button on the appropriate group name and choose Migrate from the Quick Menu. The Migrate Objects screen is displayed.

  2. Select the name of the server group you want migrated using the drop-down menu in the Migrate Group field.

  3. Enter the name of the machine on which the server group is currently located (source) in the From Machine field.

  4. Enter the name of the machine to which you want to migrate the server group (destination) in the To Machine field.

  5. Click on the Migrate button. The Progress of Migrate screen is displayed. For more information about this screen, see "Introducing the Progress of Migrate Screen" on page 16.

  6. Your next steps depend entirely on the applications you have running. You may need to drain queues, shut down groups, migrate databases using tools provided by the database vendor, and so on, to ensure an orderly migration.

How to Migrate All Servers From One Machine to Another Machine

 To migrate all servers from one machine to another, complete the following steps:

  1. Click on the Migrate icon in the Power Bar or click the right mouse button on the appropriate Machine name and choose Migrate from the Quick Menu. The Migrate Objects screen is displayed.

  2. Enter the name of the machine from which you are migrating servers in the Migrate Servers From field.

  3. Enter the name of the machine to which you want to migrate the servers in the To Machine field.

  4. Click on the Migrate button. The Progress of Migrate screen is displayed.

  5. Your next steps depend entirely on the applications you have running. You may need to drain queues, shut down groups, migrate databases using tools provided by the database vendor, and so on, to ensure an orderly migration.

Swapping the Master and Backup Machines

 If you have identified one machine as a Master and a second machine as a Backup, you can choose to run the BEA TUXEDO application from either machine. For example, you can swap the application from the Master to the Backup so that you can perform downtime maintenance on the Master machine. Or, if the Master processor loses the virtual circuit to other processors while the application is running, you can log into the Backup machine. This allows you to bring up the DBBL on the backup node, allowing the application to continue (although possibly in a degraded state).

Prerequisites

To have the option to swap machines, you must have set the names of the machines that serve as the Master and Backup nodes of your system. For more information, see Chapter 4, "Configuring Administrative Class Objects."

How to Swap the Master and Backup Machines

To swap the Master and Backup machines click the right mouse button on the domain name in the Object Tree and select Swap from the Quick Menu. A confirmation screen is displayed, indicating whether the swap was successful.

Cleaning a Machine

Occasionally, you may find it necessary to clean your machine (e.g., when the network has gone down or when clients or servers have been killed). The clean operation has the following effects:

How to Clean A Machine

 To clean a machine, click the right mouse button on the machine name and choose Clean from the Quick Menu. A message is displayed telling you whether the clean operation was successful or not

Advertising, Unadvertising, Suspending, and Resuming Services

You can perform the following service-related operations:

To You can
Make a service available Advertise the service
Make a currently advertised service unavailable Unadvertise the service
Prevent the application from accessing a service Suspend the service
Make a suspended service available to the application Resume the service

How to Advertise a Service

To advertise a service (either from an existing service or from a service default object), complete the following steps:

  1. Click the right mouse button on the name of the server on which the service you want to advertise resides and choose Advertise from the Quick Menu. The Advertise Service screen is displayed.

    Advertise Service screen

  2. Enter the name of the service to be advertised in the Service Name field.

  3. Optionally, enter the name of the C program function that will handle the service request in the Function Name field. The function name must be one of the functions that is allowed to receive service requests (see buildserver(1)). If you leave this field blank, the entry in the Service Name field is used as the Function Name.

  4. Click on the OK button at the bottom of the Advertise Service screen. A confirmation message is displayed.

How to Unadvertise a Service

 To make a currently advertised service unavailable, click the right mouse button on the name of the advertised service and choose Unadvertise from the Quick Menu.

How to Suspend a Service

To suspend a service, click the right mouse button on the object name and choose Suspend from the Quick Menu. If the suspension was successful, a Result of Requested Change menu is displayed. The suspended service icon now is displayed with an "X" superimposed on it.

If the service cannot be suspended, an error message is displayed specifying the reason.

How to Resume a Service

To reactivate a suspended service, click the right mouse button on the object name and choose Resume from the Quick Menu. A Result of Requested Change screen is displayed, indicating whether the reactivation was successful.

Suspending, Resuming, and Killing Clients

You can perform the following client-related tasks using the Client Quick Menu:

To You can
Prevent a client from accessing the application Suspend the client
Allow a suspended client to access the application again Resume the client
To remove a client from the BEA TUXEDO application Kill the client

Suspending a Client

If you want to isolate your client temporarily, you can suspend it. When you suspend a client, the client is prevented from performing the following tasks:

How to Suspend a Client

 To suspend a client, click the right mouse button on the object name and choose Suspend from the Quick Menu. If suspension was successful, a Result of Requested Change screen is displayed. The suspended client icon now is displayed with an "X" superimposed on it, indicating the client is suspended.

If the client can't be suspended, an error message is displayed specifying the reason.

How to Resume a Suspended Client

To reactivate a suspended client, click the right mouse button on the object name and choose Resume from the Quick Menu. A Result of Requested Change screen is displayed, indicating whether the reactivation was successful.

How to Kill a Client

A client can be killed, or abortively deactivated, to remove it from the BEA TUXEDO application. The recommended method to kill a client is:

  1. Suspend the desired client(s). For more information about suspending clients, see "How to Suspend a Client" on page 23.

  2. Click the right mouse button on the suspended client name and choose Kill from the Quick Menu. If the abortive deactivation was successful, a Result of Requested Change screen is displayed. The client icon is no longer is displayed in the Object Tree.

    If the client can't be killed, an error message is displayed specifying the reason. The web GUI process will refuse to kill itself; however, one web GUI process can be used to kill another.

    The application may not be able to kill the client due to platform or signaling restrictions. In this case, a native client is abortively terminated at its next access to Application Transaction Manager Interface (ATMI), and a workstation client connection to a workstation handler will be preemptively torn down. The connections to all clients attached to that WSH are terminated.

Suspending, Resuming, and Killing WorkStation Handlers

 You can perform the following workstation handler-related tasks using the Client Quick Menu:

To You can
Prevent clients from accessing a workstation handler Suspend the workstation handler
Make a suspended workstation handler available to clients Resume the workstation handler
To remove a workstation handler from the BEA TUXEDO application Kill the workstation handler

Suspending Workstation Handlers

If you want to isolate the clients connected to a particular workstation handler temporarily, you can suspend it. When you suspend a workstation handler, the clients connected to it are prevented from performing any of the following tasks:

How to Suspend a Workstation Handler

 To suspend a workstation handler, click the right mouse button on the object name and choose Suspend from the Quick Menu. If suspension was successful, a Result of Requested Change screen is displayed. The suspended WorkStation Handler icon now is displayed with an "X" superimposed on it, indicating it is now suspended.

If the workstation handler can't be suspended, an error message is displayed specifying the reason.

How to Resume a Suspended Workstation Handler

To reactivate a suspended workstation handler, click the right mouse button on the object name and choose Resume from the Quick Menu. A Result of Requested Change screen is displayed, indicating if the reactivation was successful.

How to Kill a Workstation Handler

A workstation handler can be killed, or abortively deactivated, to remove it from the BEA TUXEDO application.

The recommended method to kill a workstation handler is:

  1. Suspend the desired workstation handlers.

  2. Click the right mouse button on the suspended object name and choose Kill from the Quick Menu. If the abortive deactivation was successful, a Result of Requested Change screen is displayed and the object no longer is displayed in the Object Tree. The connections to all clients attached to that workstation handler are terminated.

    If you can't kill the workstation handler, an error message is displayed, specifying the reason. The application may not be able to kill the workstation handler due to platform or signaling restrictions. In this case, a workstation client connection to a workstation handler will be preemptively torn down.

Opening and Closing Application Queue Spaces

 You can use the web-based GUI to allocate and initialize shared memory and to remove shared memory and other IPC resources (e.g., message queues and semaphores). The options that perform these functions are Open and Close.

How to Open an Application Queue Space

To open an application queue space, click the right mouse button on the name of the application queue space and choose Open from the Quick Menu. A message is displayed to tell you whether the application queue space was opened successfully.

How to Close an Application Queue Space

To close an application queue space, click the right mouse button on the name of the application queue space and choose Close from the Quick Menu. A message is displayed to tell you whether the application queue space was closed successfully.

Deleting Application Queue Messages

You can choose to delete an application queue message from its queue space if you don't need to keep it any longer.

Prerequisites

The message must be in the ACTIVE state to be deleted.

How to Delete Application Queue Messages

To delete the application queue message, click the right mouse button on the message name and choose Delete from the Quick Menu. A Result of Requested Change screen is displayed, indicating whether the application queue transaction was deleted successfully.

Aborting Transactions

If you must stop a transaction before it is complete, you can abort the transaction. Any data that changed as a result of that transaction is rolled back to its value at the start of the transaction. The transaction must be in either the ACTIVE, ABORTONLY, or COMCALLED state.

Caution: There is a very slight risk that the data roll back may not be successful. You can minimize the risk by aborting a transaction early in the process.

How to Abort a Transaction

To abort a transaction, complete the following steps:

  1. Position the cursor over the object name and press the right mouse button. The Quick Menu is displayed.

  2. Choose Abort... A Result of Requested Change screen is displayed, indicating whether the transaction aborted successfully.

    If you can't abort the transaction, an error message is displayed specifying the reason.

Bridges Between Machines

 A bridge is a connection between two machines in a multi-processor domain. You can create, suspend, resume, and deactivate bridges.

How to Create a Bridge

To create a bridge between two machines, complete the following steps:

  1. Click the right mouse button on a machine name in the Object Tree and choose Connect from the Quick Menu. The Connect screen is displayed.

  2. Enter the logical machine identifier (LMID) of the machine to which you want to be connected.

  3. Click on the OK button at the bottom of the screen. A message is displayed to tell you whether the bridge was created successfully.

How to Suspend a Bridge

 To suspend a bridge, click the right mouse button on the bridge name and choose Suspend from the Quick Menu. A message is displayed to tell you whether the bridge was suspended successfully.

How to Resume a Suspended Bridge

To resume a suspended bridge, click the right mouse button on the bridge name and choose Resume from the Quick Menu. A message is displayed to tell you whether the bridge was resumed successfully.

How to Deactivate a Bridge

To deactivate a bridge, click the right mouse button on the bridge name and choose deactivate from the Quick Menu. A message is displayed to tell you whether the bridge was deactivated successfully.