JetNet/Oracle Tuxedo Guide

This chapter describes how to use the JetNet manager and other utilities to boot, monitor and manage a running Panther application. It also outlines methods for redistributing network load in a multi-machine application, and ways to monitor and act on errors.

Monitoring an Enterprise

When you select an application, JetNet manager's opening dialog shows the hierarchy of all components. These include objects that are defined in the configuration—the application itself, machines and servers; they are described in Chapter 3, "Configuring the Enterprise." In an active application, you can also monitor the following components:

• Server instances—An active server has at least one active instance. When a server is activated, it initially has as many instances as its Minimum Instances property specifies. Thereafter, you can increase and decrease the number of server instances as needed. Instances are shown below their server and use the name of the server executable.

• Services—Standard servers that are active list their services under each instance. Depending on its definition, a server advertises either all JIF-defined services or those that belong to a service group definition. Services are listed for informational purposes only; you cannot perform any action on them.

• Clients—All clients that are attached to the application are listed, including the JetNet manager. Clients are only visible when you connect the JetNet manager to the application from the master machine (refer to page 4-4).

• Workstation listeners— An active machine that is configured to allow workstation client connections always has a workstation listener process. This process intercepts connection requests and, if possible, finds a handler for the connection. For more information about setting workstation listener properties, refer to page 3-17.

Initially, only the top-level component—for the application itself—is shown. Double-click on a component to toggle subordinate components in and out of view. A component with subordinates is prefixed with a - or + symbol to indicate whether they are visible or not.

To the right of the hierarchy list, the Details list displays information about the selected component, such as its name, type, and state (active or inactive). The dialog also contains a Status box that displays informational messages.

Activating and Deactivating Components

The JetNet manager lets you activate and deactivate application components that are visible in the hierarchy list through the Edit menu options Activate and Deactivate. You can deactivate any component except a client and the master machine.

Note: To deactivate clients, use forcible deactivation (EditForcibly Deactivate). Refer to page 4-5 for details. To deactivate the master machine, deactivate the application from the master machine.

The scope of objects accessible to activation and deactivation depends on where you are running the JetNet manager. For example, you can activate and deactivate an application only from the master machine. The following figure shows what activation and deactivation options are available from each type of site:

Deactivating a component can also cause subordinate components to deactivate. For example, deactivation of a server deactivates all instances of that server.

The following sections discuss activation and deactivation according to component types and the issues that are associated with each type.

Enterprise Application

You can activate an application with the JetNet manager or with the command-line utility rbboot. In either case, activation can take place only on the master ma chine. Before activating an application, verify the following conditions:

• All machines have the executables for which their servers are configured.

• Each machine has SMRBCONFIG set to the same value as its Local JetNet Configuration File property (refer to page 3-14).

• In a multi-machine application, the listener process is running on all machines. Start the listener process with rblisten.

To deactivate an application from the JetNet manager, you must be running the JetNet manager from the master machine. You can also shut down an application with the command line utility rbshutdown.

If an application has client connections, attempts to deactivate can yield partial shutdown, where those machines that have client connections remain alive. In this case, the application also remains active. To shut down an application that has client connections, choose FileForcibly Deactivate (refer to page 4-5).

Machine

You can activate and deactivate any machine except the one on which the JetNet manager is running and the master machine. In order to activate a non-master machine, the listener process must already be running on it (refer to page A-7).

If you try to deactivate the machine on which the JetNet manager is running, all subordinate components including servers are deactivated; however, the machine itself remains active.

Note: To activate the master machine, you must activate the entire application from the master machine, either through the JetNet manager or rbboot. Similarly, deactivate the master machine by deactivating the application from the master machine, either through the JetNet manager or rbshutdown.

Servers

You can activate any server. Before you activate a server, make sure that the appropriate server executable is installed in the same location as the server definition specifies (refer to page 3-23).

When you activate a server, it initially has as many server instances as its Minimum Instances property specifies. Thereafter, you can increase and decrease the number of server instances as needed. For more information, refer to page 4-6.

If you deactivate a server, JetNet automatically removes all instances.

Connecting and Disconnecting

If the current application is active, you can connect the JetNet Manager to it as a client by choosing FileConnect to Application. When you choose this option, the Connect dialog displays:

Log in with your user name. If a password is set for the desired application (refer to page 3-12), you must enter it, too. After the JetNet manager is connected, it and all other connections are listed by user name in the hierarchy list. The JetNet manager shows client connections to an application only when it is itself connected to the application.

When you disconnect from an application (FileDisconnect from Application), the JetNet manager terminates its client connection and removes from view all other client connections.

Forcibly Deactivating Components

You can force deactivation of application components by choosing EditForcibly Deactivate. When you choose this option, a confirmation dialog asks whether to proceed. Choose this option instead of Deactivate for one of the following reasons:

• To ensure shutdown on the machine and application level. For example, normal deactivation fails for any machine that has clients connected to it. Forcible deactivation disconnects clients and allows machine shutdown.

• Parts of an application are in an undefined state and are not responsive to deactivation attempts.

• To disconnect a client. Normal deactivation is invalid for client connections.

You can forcibly deactivate four objects: application, machines, server instances, and clients. Forcible deactivation is invalid for servers.

Forcibly deactivating a component causes JetNet to forcibly deactivate all subordinate components. For example, deactivation of a machine also deactivates its server instances and disconnects its clients.

Adding and Deleting Components

You can add servers and machines to an active application exactly as you do with an inactive application. All additions are immediately written to the application's configuration file. You can also delete servers and machines; however, they must first be inactive. If you delete a machine that has servers configured, the JetNet manager deletes the machine and its subordinate components on confirmation. If you delete an application object, the entire application is removed. You cannot delete an application's master machine.

Adding and Removing Server Instances

When a server is activated, it initially has as many instances as its Minimum Instances property specifies (refer to page 3-20). If a server is experiencing a high volume of service requests, you can facilitate throughput by increasing the number of instances. Conversely, you can remove instances from an under-utilized server.

How to Add a Server Instance

1. Select the server from the hierarchy list.
2. Choose EditAdd Instance.

1. Select the instance from the hierarchy list.
2. Choose from the EditDeactivate

If the instance is processing a service request and the tp_block property is set to PV_YES, the instance is not deleted until the service completes or times out. If you attempt to deactivate instances of a workstation listener (WSL) server that is responsible for maintaining workstation client connections, the JetNet manager issues a warning message and asks whether to disconnect these clients.

Note: If you deactivate all instances of a server, JetNet deactivates the server.

Changing Machine Roles

An application that runs on multiple machines—especially one that must run continuously—should always have a machine designated as backup master. In a running application, the backup master is always prepared to take over the role of master machine in case the master machine unexpectedly terminates.

You might also want to reassign the master or backup master machines in a running application—temporarily, in order to bring down the master machine for periodic maintenance; or permanently because of changes in the network.

Recovering From Master Machine Failure

If the master machine failure in a three-tier application fails, or its DBBL and BBL processes fail, the application continues to run but the DBBL is not recreated on the backup master machine. In order to recover from abrupt termination on the master machine, stop all application servers and BBLs when possible and reboot the application to restart the DBBL.

Reassigning Master and Backup Machines

You can reassign the master and backup machines by running the JetNet manager from any active machine and invoking the Machine Roles dialog (refer to page 3-8). When you reassign the master, Panther performs the necessary migration of control without disrupting operations.

Disabling and Reenabling Workstation Connections

In an active application, you can stop a machine's workstation listener and reconfigure the machine to disallow workstation connections as follows:

1. Select the machine's workstation listener server from the Application Status dialog and deactivate it.
2. In the machine's Network Settings dialog, unset the Workstation Listener toggle button.

To restart an active machine's workstation listener, follow the same procedure in reverse: set the machine's Workstation Listener toggle button, then activate its workstation listener server.

Handling Load

You can efficiently distribute application processes and optimize the use of resources in several ways:

• Define service groups and assign them to servers so that service requests can be routed to the servers that can handle them most efficiently. For example, you might have a number of services that can be processed quickly and are frequently requested; several other services are lengthier and are requested less often. In this case, it makes sense to specify the two types of services in separate groups; one server can advertise the group of quick services, with enough instances to handle peak load; another server can advertise the group of lengthy services, with only enough instances to handle occasional requests.

• Use the Load Balancing (page 3-11) and Network Load (page 3-16) properties to route service requests to the server machines that are most available to handle them.

If service requests frequently time out or take a long time to complete, you can increase the setting for the application property Default Blocking Timeout (page 3-12). You might also add machines to the configuration and redistribute servers accordingly.

You should also modify IPC settings to handle the application's resource requirements. IPC requirements can vary according to these property settings:

• Max Accessors—Set on the machine level, this property specifies the maximum number of processes, clients and servers, that can attach to the application on a given machine. This property directly increases semaphore and shared memory costs.

• Enable Cross-Service Calls—Set on individual servers, this property specifies whether to allow this server to request services from another server. Setting this property increases the number of message queues required by the application.

The number of semaphores required on each machine is equal to the value of Max Accessors. To calculate the number of message queues, count one queue for each BBL and the DBBL, one for each client and server, and two for each bridge process. If a server's Enable Service Calls property (in the JetNet configuration file) is set to Yes, also count one queue per server instance.

Queue-related kernel parameters (refer to page 2-12) should be tuned to manage the flow of buffer traffic between clients and servers:

• The maximum total size of a queue in bytes (MSGMNB) must be large enough to handle the largest message that the application allows. The queue should usually be about 75 to 80 percent full.

• The maximum size for a message (MSGMAX) must be set to handle the largest buffer that the application might send.

• The maximum queue length (MSGTQL) must be set high enough to handle application operations.

To gauge a queue's average fullness or length, you must run the application. Finding optimal settings for tunable parameters is typically a trial-and-error process.

If you have a large system, you might want to analyze the effect of parameter settings on the size of the operating system kernel. If it is unacceptable, consider reducing the number of application processes or distributing the application to more machines in order to reduce the Max Accessors setting on each one.

Status and Error Messages

Status and error message can be posted in one of three places:

• The JetNet manager's status window

• Machine log file

• stderr, which gets server error output

Machine log file names have the format ULOGmmddyy. Log files on PC workstation clients have the format ULmmddyy.log. On UNIX, machine log files must be located on the path specified by the machine's Application Directory property. On Windows, the ULOGDIR setting in the machine's Environment panel specifies their location.