JetNet/Oracle Tuxedo Guide


Chapter 3 . Configuring the Enterprise

The graphical JetNet Manager (JetMan) integrates all the facilities you need to configure and manage the middleware component of a Panther application. With it, you create and edit a binary JetNet configuration file; this file specifies how to set up an application's clients and servers and configure their interaction—for example, whether multiple workstations can attach to the application, the maximum number of machines, servers, and services that the application can support, how many servers to activate and on which machine.

JetNet configuration files can be used with the Tuxedo middleware adapter, and are accessible to all Tuxedo utilities, including xtuxadm. Thus, you can use the JetNet manager to create a configuration file, then edit and enhance it for use with Tuxedo later on.

Note: The JetNet manager is designed for editing JetNet configuration files only; you should edit and manipulate Tuxedo configuration files with the appropriate Tuxedo utilities.

This chapter shows how to use the JetNet manager to create and configure an application. It describes the interface and the properties that you can set for each object— application, machine, and server. For information about using the JetNet manager to manage a running application, refer to page 4-1.


Using the JetNet Manager

You invoke the JetNet manager through the executable jetman. When you start JetNet manager on UNIX, it automatically reads its Jetman resource file; on Windows, it reads the jetman32.ini initialization file. It then reads the configuration file specified by SMRBCONFIG or TUXCONFIG; if neither is set, the JetNet manager opens without a configuration file.

The following steps create a basic configuration file. For more information about each field, refer to page 3-7.


Creating a Configuration File

How to Create a Basic Configuration File

  1. Choose FileNew Application from the menu bar or the New Application button from the toolbar. If another configuration file is already selected, the JetNet manager asks whether to close it.

    The JetNet manager displays the Application Configuration dialog:

  2. Assign a name to the application through the Application Name property. Other application properties are optional; set these as desired (refer to page 3-8).
  3. When you finish editing application properties, choose Next. The JetNet manager displays the Machine Configuration dialog, where you configure the master machine:

  4. Configure the master machine properties as desired (refer to page 3-12). The Name property is initially set to the machine on which you are running the JetNet manager.

    Note: In a multi-machine application, this machine is initially defined as the master machine. Later, you can reassign this machine to a non-master role after other machines are added (refer to page 3-8).

  5. Check the path specified for the Panther installation, the application directory, and the configuration file. These files should be located on the same machine.
  6. When you finish setting machine properties, choose Networking.

  7. To enable remote access, select Workstation Listener, and choose OK.
  8. When you finish setting machine properties on Machine Configuration, choose Done. If the file name specified in Local

JetNet Configuration File already exists, a message asks for confirmation to overwrite it.

Note: You can create a minimal configuration through the utility rbconfig.


Editing a Configuration File

The JetNet manager's opening Application Status dialog shows the hierarchy of components in an application. Initially, only the top-level component—for the application itself—is shown. Double-click on each component in the list to toggle in and out of view components that are one level below. Or you can expand and collapse the list of all components below the selected component by choosing ViewExpand Subtree and ViewCollapse Subtree. A component with subordinates is prefixed with a - or + symbol to indicate whether they are visible or not.

Note: In an inactive multi-machine application, you can edit the configuration file from the master machine only.

When you edit an inactive application's configuration, the hierarchy list can contain three types of components:

You can also edit the configuration file of an active application. Some component properties are editable only when the component itself is inactive. For more information about managing an active application, refer to page 4-1.

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.

You can use the hierarchy window to add and delete components from an application's configuration; you can also use it to access those components' definitions and edit them:

Adding and Deleting Components

Add servers and machines to a configuration by selecting a higher-level object—for a new server, its host machine; for a new machine, the application—and choosing the appropriate FileNew option or toolbar button. Servers and machines can be added and removed whether their parent objects are active or inactive.

You can also create a copy of an existing server by selecting the server and choosing FileNewServer or the corresponding toolbar button. This adds a new server to the host machine and copies all non_unique properties from the selected server to the new one. You must assign the new server a unique name in order to save it.

To delete a component from the configuration, select it and choose EditDelete. You can delete any inactive component from the configuration. If the selected component has subordinate components, these are deleted also.

Editing Components

A JetNet configuration file defines three types of application components—the application itself, machines, and servers. You access these definitions through the JetNet manager. Definitions can be viewed and edited whether a component is active or not; however, you can change some settings only when the component is inactive. All changes that you make in the JetNet manager are written to the configuration file immediately.

To edit a component's settings, select its name from the hierarchy list and choose EditProperties or the Object Properties button from the toolbar. Properties for each component type are described in later sections of this chapter.

Selecting Another Enterprise's Configuration

To edit another configuration file, choose FileSelect Application. This invokes the Select File dialog where you choose the desired configuration file. When you select a file, Panther reads the configuration definition. If the JetNet manager was connected to the previous application (refer to page 4-4), the connection is automatically broken.


Setting Enterprise Properties

To access application properties, select the application name from the hierarchy list and choose EditProperties.

General Settings

The application properties that are initially displayed set an application's identity—its name, IPC key, and whether it runs on a single or multiple machines. For more advanced application properties, choose the Advanced push button.

Application Name
The application's logical name, a value of up to 30 characters. This name identifies the application in the hierarchy list.

IPC Key
Specifies the application's address of shared memory. The default value is system-assigned. You can assign a value between 32,769 and 262,142, inclusive. Panther uses this address to allocate application IPC resources so that they can be located easily by new processes as they join the application. This key is used internally to allocate the bulletin board, message queues, and semaphores that must be available to processes when they join the application.

Memory Model
Specifies whether the application runs on a single processor or across a network with multiple machines:

Roles
This push button is accessible only for multi-machine applications. In a networked application, you must identify the master machine and, optionally, the machine that acts as its backup. The first machine to be defined for the application is the default master machine.

You should always specify a backup master machine; this is especially important for 24-hour applications to allow a smooth transfer of operations in case the master machine unexpectedly ceases operation or is deliberately brought down for periodic maintenance. In a running application, the backup master is always prepared to take over the role of master machine.

In an inactive application, you reassign the master machine by running the JetNet manager from the machine that you want to designate as the new master. You must always reassign the backup master from the master machine.

In a running application, you can reassign machine roles by running the JetNet manager from any active machine.

How to Assign or Reassign Machines Roles

  1. From the Application Configuration dialog, choose the Roles push button. This invokes the Machine Roles dialog:

    Two list boxes show all machines in the application. The Master list highlights the current master; the Backup Master list highlights the current backup master, if any.

  2. Select the desired machine from the appropriate list. When your assignments are complete, choose OK.

Advanced Settings

The Advanced Application Configuration dialog sets limits such as the maximum number of machines and servers that the application supports, and general application properties such as the application password.

Max Machines
The maximum number of machines that can be used by the application. The default value is 256.

Max Server Processes
The maximum number of server processes allowed for the application at any one time. This value must be greater than 0 and less than 8192. The default value is 50.

The value that you should set for this property should account for one listener server on each workstation, and the maximum number of instances anticipated for each server. Because this property directly increases semaphore and shared memory costs, deployed applications should have this property set to the lowest value that ensures acceptable performance. In a development environment, set this property sufficiently high to account for additional resource requirements.

Max Servers
The maximum number of servers allowed for the application at any one time. The value that you set for this property should account for one listener server on each workstation. This property's value must be between 100 and 32,767, inclusive. The default value is 100.

Max Services
The maximum number of services that can be advertised by the application at any one time. This property's value must be between 1 and 32,767, inclusive. The default is 100. Because this property directly increases shared memory costs, set it to the lowest value that allows the application to advertise all desired services.

Max Accessors
Specifies the initial value that is set for a new machine's Max Accessors property (refer to page 3-13).

Load Balancing
Determines whether to load balance client requests among active servers. When load balancing is on, JetNet monitors the total number of all services waiting to be handled by each server. It uses this information to direct requests to the least-busy server that can handle each new request.

All requests are equally weighted; this means that JetNet simply calculates a given server's load from the total number of services waiting to be processed, and ignores their cumulative processing time. To make maximum use of load balancing, organize services into service groups according to their processing requirements and associate these groups with servers as needed. You can also optimize throughput on the machine level by setting Network Load for each machine (refer to page 3-16).

Note: Load balancing is not required when services are offered by only one server.

Application Password
If enabled, this check requires clients to supply a password when joining the application. This password is checked against the password supplied by the system administrator.

When Password is enabled, you supply or change the application password by choosing Change Password. This invokes the Application Password dialog where you enter the new password twice. If the two entries do not match, an error message is posted and you must repeat the process.

The application password provides level-2 authentication. Level-3 authentication is provided in the Oracle Tuxedo version. For more information, refer to page 2-13 in the Programming Guide.

Shared Memory Protection
Shields the system tables that are kept in shared memory from clients and servers. Enable this option when you are developing an application that is not yet fully debugged and tested. In finished applications, disable this option for faster response time.

Default Blocking Timeout
Specifies how much time elapses before a call times out and returns to its caller. Calls are blocked only if the tp_block property is set to PV_YES. The default is 60 seconds. If the application uses a server executable that has the debugger linked in, increase this value sufficiently to allow for slower response time.

The entered value must be a multiple of 10. If an entry's last digit is non-zero, the JetNet manager changes it to 0.


Setting Machine Properties

A Panther application can run on a single machine or across a network on multiple machines. To access machine properties, select the machine name from the hierarchy list and choose Edit—Properties.

Name
A logical name that identifies this machine to the network. Names should not include an embedded period (.) character.

Multiprocessor
Enable if the machine has multi-processor capabilities.

Max Accessors
The maximum number of processes, clients and servers, that can attach to the application on this machine. The initial value is set from the application's Max Accessors property. Because this property directly increases semaphore and shared memory costs, set it to the lowest value that ensures acceptable performance.

Machine Type
In a multi-machine application, identifies the machine type, either UNIX or Windows. This setting enables JetNet to manage communication between machines of different types. When you define a new machine, its machine type is initially set to the machine on which the JetNet manager is running. You can change this setting for any non-master machine; it is inaccessible for the application's master machine.

A UNIX machine can also specify its user and group IDs, UID and GID. When you define a new UNIX machine, its UID and GID values are initially set to the UID and GID of the machine on which the JetNet manager is running, if available. You can change these values to any integer between 0 and 2,147,483,647, inclusive.

A Windows machine prevents access to the UID and GID properties and sets them to 0.

Panther Install Directory
Shows where Panther is installed.

Application Directory
The working directory where servers running on this machine are started. The machine's log file (ULOGmmddyy) is also written to this directory.

Machine Environment Variable File
Specifies to execute this machine with the environment in the named file. This property's default is set to machine.env in the application directory. You can override the default by entering the pathname directly or by using the Browse push button to select the desired file.

This environment supplements the one already established when the machine is activated. For example, you can set a different server library for each server by setting SMFLIBS in its environment file. You cannot use this file to override settings in Panther Install Directory, Application Directory, and Local JetNet Configuration File.

For more information about the contents and format of a machine environment file, refer to page 2-5.

Local JetNet Configuration File
For the master machine, specifies the JetNet configuration file that is read when the application is booted. For non-master machine, this property specifies the pathname of the local copy of the configuration file. When this machine is activated, it copies the master machine's JetNet configuration file into this location.

If you are defining a new configuration file, the JetNet manager creates a file according to the pathname specified and stores your initial settings in it. Settings for SMRBCONFIG must exactly match this pathname.

Note: Under shared file systems such as NFS, make sure that local configuration files on different machines have unique pathnames.

Warning: The configuration file created by JetNet manager or rbconfig includes references to itself. If you change the master machine's Local JetNet Configuration File property, these internal references become invalid. To rename a configuration file, convert it to ASCII with rb2asc and edit the TUXCONFIG string to the new file; then run rb2asc again to convert the edited file back to binary.


Network Settings

Networking settings specify the information that each workstation requires to contact other computers and vice versa.

IP Address
This machine's network identifier, valid only for multi-machine configurations. The JetNet manager assigns a value to this property based on the machine's IP address. Modify this value if the machine is known by multiple IP addresses and you need to use a different one.

Network Device
Specifies a machine's network device. The default value is platform-specific—for example, /dev/tcp.

Listener Port
Identifies the port that is used by this machine's listener process. Enter any number between 32,768 and 65,535, inclusive. Be sure to reserve this port number for Panther use only. The default value is the default IPC Key value plus 10.

At boot time there is no bridge process to receive communication. Instead, each listener process on the non-master and backup master machines awaits a message from the master machine to begin the local boot process. The master machine uses the port number in each machine's Listener Port property to address its listening process. Consequently, the port number supplied to rblisten to invoke a machine's listening process must match this property.

For more information about rblisten's role in booting a Panther application, refer to page A-7.

Bridge Port
Identifies the port that this machine's bridge process uses to communicate with other machines in the network. Enter any number between 32,768 and 65,535, inclusive. The default value is the application's default IPC key value plus 20.

When the machine's bridge process is booted, it appropriates this port for its own use; consequently, you should reserve this port number for Panther.

Network Load
Use this property to inflate the activity of servers on this machine as perceived by clients on remote nodes. Activity is measured by the number of enqueued service requests; so two servers on different machines with the same number of enqueued requests appear equally available to all clients, regardless of their network proximity. The value specified for Network Load augments this number for remote clients. You can enter any value between 0 and 32,767, inclusive. The default value is 0.

For example, a network of two machines, fred and wilma has one server on each, fred_srv and wilma_srv. If fred_srv has 6 requests pending and wilma_srv has 9, fred_srv ordinarily gets the next service call, whether the caller is local or remote. Because routing calls across the network is expensive, you can set each machine's Network Load property to a level that deters excessive network traffic. So, if fred's Network Load property is set to 10, the next remote client with a service call sees fred_srv as having 16 pending requests, so the request broker routes the call to wilma_srv; however, a local client always sees fred_srv's level of activity as it actually is, so its next call is processed locally.

Workstation Connections

In order to permit workstation clients to connect to the application on this machine, enable the Workstation Listener toggle button. This starts the workstation listener process on this machine. When client_init is invoked from a workstation, it uses the workstation's settings in SMRBHOST and SMRBPORT to request a client connection. The workstation listener at this host and port intercepts the connection request and, if possible, finds a handler for the connection.

Note: When you add a machine to an application's configuration from a PC workstation, you cannot enable the machine's Workstation Listener toggle button (on the machine's Network Settings dialog). To activate a machine's workstation listener process, you must run JetNet manager on the server machine.

You configure a machine for workstation client connections with the following properties:

Listener Port
Identifies the port that is used by the workstation listener. Workstation clients use this port number when they try to connect to the application on this machine. This property's value must be between 32,768 and 65,535, inclusive. Be sure to reserve this port number for Panther use only. The default value is the application's default IPC key value plus 30.

For more about enabling workstation client connections, refer to page 2-9.

Min Handlers
The minimum number of handlers that this machine's workstation listener makes available to clients at any given time. The workstation listener starts this many handlers when it is booted and makes sure that the number of handlers never decreases below this minimum until it shuts down. More handlers are made available as needed in order to accommodate clients that attach to the application on this machine, up to the value set for Max Clients. You can specify up to 255 handlers. The default value is 1.

Client Timeout
The amount of time in minutes that a client can idle before it is disconnected by its workstation handler. A client is considered idle if it makes no requests. Clients that get unsolicited message notifications without responding are also considered idle. Use this option for client platforms that are unstable—for example, a workstation that can be turned off without calling client_exit.

To prevent timeouts, set this property to blank. The default value is 60.

Handler Port
Identifies the port range that is used by the workstation listener. By default, the values are between 2048 and 65535, inclusive.

External Network Address
The network address used by the workstation listener as its listening address. Enter the host machine and port number as a string following two slashes or as a hex value. For example, if the machine is bedrock with a TCP/IP address of 123.1.123.12 and the port number is 9876, the network address could be specified as any of the following:
//bedrock:9876
//123.1.123.12:9876
0x000226947B017B0C

Max Clients
The maximum number of clients that can attach to the application on this machine. The default value is 40.

Multiplex
The maximum number of workstation clients that each workstation handler can support at one time. The workstation listener ensures that new handlers are started as necessary to handle new workstation clients. This property's value must be between 1 and 4096, inclusive. The default value is 10.

Max Init Time
The amount of time in seconds that is allowed for client initialization to complete before it is timed out by the workstation listener. This property's value can be between 1 and 32,767, inclusive. The default value is 60.

Setting Server Properties

All services in a Panther application are processed by a server. Servers are defined as part of each machine's configuration. You can define standard servers that advertise JIF-defined services, and conversion servers that provide services to client screens converted from a two-tier model. Both types can connect to a one or more database engines. You can also define file access servers for access to remote Panther libraries.

To access server properties, select the server name from the hierarchy list and choose EditProperties. The following properties are common to all server types:

Name
The name of this server, up to 30 characters. All server names must be unique within an application and must not be the same as a machine name.

Minimum Instances
The number of instantiations of this server created when it is activated. After the server is activated, you can increase or decrease the number of its instances as needed. The default value is 2.

Server Type
Specifies to use one of the three server executable types that provide services to clients:

Server Environment Variable File
Specifies to execute this server with the environment in the named file. This property's default is set according to the server type that you choose: proserv.env for a standard server or progserv.env for a conversion server. You can override the default by entering the pathname directly or by using the Browse push button to select the desired file. By default, file access servers use the settings in machine.env; however, you can add additional settings in devserv.env.

This environment supplements the one already established when the server is activated. For example, you can set a different server library for each server by setting SMFLIBS in its environment file. You cannot use this file to override the machine settings for Panther Install Directory, Application Directory, and Local JetNet Configuration File.

For more information about the contents and format of a server environment file, refer to page 2-6.

Server Restart Frequency
Specifies whether the server automatically restarts after it unexpectedly terminates and how soon:

Server restart option Time elapsed until restart

Never

Sometimes

Twice within four hours.

Often

Twice every 10 minutes.

Always

Removes all limitations. The server can be restarted an unlimited number of times.


Server Details

You can set one or more properties that define a server's functionality, depending on its type—standard, conversion, or file access. For example, a standard server specifies which JIF-defined services to advertise, whether it is enabled for debugging, and its database connection.

You access server detail properties by choosing Options from the Server Configuration dialog. This invokes a dialog that is appropriate to the server's type. The following sections describe properties for each dialog:

Standard Server

Auto Advertised Services
There are two categories of auto-advertised services, User-defined and Built-in.

Under User-defined, select one of these options to determine which services this server advertises:

Enable Cross-Server Calls
Specifies whether to allow this server to request services from another server. If this property's check box is set, the server is allocated its own reply queue. Because setting this property increases the number of message queues required by the application, you should do so only if necessary. By default, this property is set.

Server Executable
The name of the executable to run when this server is activated. proserv is the default value. You can also specify a standard server that has the Panther debugger linked in, by default prodserv. You can enter the file name directly or use the file browser. If the file name omits a path, JetNet looks for the executable in the application directory (specified in the machine's Application Directory property), or in /bin.

After you set the server executable's file name, specify whether it is configured for development or production environments by setting one of these options:

Service Alias User Name
Specifies to advertise services under their aliases. The value can be up to 8 characters and is prepended to JIF alias entries to construct the advertised service names in this format:
userName+JifAliasEntry

For example, you might define a server that advertises services from the banking service group and sets lisa as the service alias user name. Given the following JIF entries for this group:

Service name Alias entry

deposit

1000

withdrawal

1001

transfer

1002

balance

1003

The server advertises these service aliases:

lisa1001
lisa1002
lisa1003
lisa1004

Servers that advertise aliases are typically set up for the exclusive use of developers who want to modify existing services without affecting the running application. For more information, refer to page 5-8.

Database Connect String
Establishes a connection to the desired database engine through a DBMS DECLARE CONNECTION command. The command is executed after default handlers are established and before the initialization routine executes.

One database connection string is allowed per server. If you want to enable multiple database engine connections, you can do so through the server's initialization routine, specified through its Init Routine property.

Init Routine
Name of a JPL or installed C function to execute when this server is initialized. For example, you might want to call a JPL procedure that uses the advertise command to set the services advertised by this server. Enter the function name and optionally any arguments that it requires, supplied as constant values. The routine is called after default event handlers are established and the database connection is made.

Conversion Server

Conversion servers have three properties:

Server Executable
The name of the executable to run when this server is activated. progserv is the default name for a conversion server. You can enter the file name directly or use the file browser. If the file name omits a path, JetNet looks for the executable in the application directory (specified in the machine's Application Directory property), or in /bin.

Database Connect String
Establishes a connection to the desired database engine through a DBMS DECLARE CONNECTION command. The command is executed after default handlers are established and before the initialization routine executes. One database connection is allowed per server.

Because a server connects to a single database, make sure that none of the services that it advertises depends on a different database connection.

Cache Service Components
Specifies whether to cache service components used by the conversion server after they are called. If this check box is unset, service components are opened each time the conversion server processes a service call, and closed when the service call returns. Set this property's check box if the services are frequently called.

File Access Server

File access servers have a single property, File Access Server ID. This property identifies the server by name. If left blank, the property is set to the name of the host on which the server resides.

A Panther application can get a file access server's ID at runtime through the application property devserv_id. Report services use this property to return the path of report metafile output to the invoking client (refer to page 9-23 in the Reports).

Reasons for setting this property include partitioning requests to your devserv processes by creating multiple devserv groups