The formats for the host names and the port numbers are shown in the following table.

Start the Jolt Relay Adapter (JRAD)

Type tmloadcf -y <UBBFILE>.
Type tmboot.

Configure the JRAD

A single JRAD process can only be connected to a single JRLY. A JRAD can be configured to communicate with only one JSL and its associated JSH. However, multiple JRADs can be configured to communicate with one JSL. The CLOPT parameter for BEA Tuxedo services must be included in the UBBCONFIG file.

Type -l hexadecimal format (The JSL port to which the JRLY connects on behalf of the client.)
Type -c hexadecimal format (The address of the corresponding JSL to which JRAD connects.)

Note: The format is 0x0002PPPNNN, or, in dot notation, 100.100.10.100.

Configure networked components.

Jolt is now configured.

Jolt Background Information

This section contains additional information on Jolt components.

Jolt Server

The Jolt Server is a listener that supports one or more handlers.

Jolt Server Listener (JSL)—the JSL is configured to support clients on an IP/port combination.The JSL works with the Jolt Server Handler (JSH) to provide client connectivity to the back-end of the BEA Jolt system. The JSL runs as a BEA Tuxedo server.

Jolt Server Handler (JSH)—the JSH is a program that runs on a BEA Tuxedo server machine to provide a network connection point for remote clients. The JSH works with the JSL to provide client connectivity residing on the back-end of the BEA Jolt system. More than one JSH can be available to the JSL, up to 32,767. (Refer to the description of the -M command-line option in JSL Command-line Options for additional information.)

System Administrator Responsibilities—the system administrator's responsibilities for the server components of BEA Jolt include:

• Determining the JSL network address.
• Determining the number of Jolt clients to be serviced. (The number of clients to be serviced is limited by MAXWSCLIENTS in UBB.)
• Determining the minimum and maximum number of JSHs.

Starting the JSL

To start all administrative and server processes in the UBBCONFIG file:

Type tmloadcf.

This command parses the configuration file and loads the binary version of the configuration file.

Type tmboot -y.

This command activates the application specified in the configuration file.

If you do not enter any options, a prompt asks you if you really want to overwrite your TUXCONFIG file.

See Administering a BEA Tuxedo Application at Run Time or the BEA Tuxedo Command Reference for information about tmloadcf and tmboot.

Shutting Down the JSL

All shutdown requests to the Jolt servers are initiated by the BEA Tuxedo command:

 tmshutdown -y

During shutdown:

• No new client connections are accepted.
• All current client connections are terminated. BEA Tuxedo rolls back in-flight transactions. Each client receives an error message indicating that the service is unavailable.

Restarting the JSL

BEA Tuxedo monitors the JSL and restarts it in the event of a failure. When BEA Tuxedo restarts the listener process, the following events occur:

• Clients attempting a listener connection must try to reconnect. Clients attempting a handler connection receive a timeout or a time delay.
• Clients currently connected to a handler are disconnected (JSH exits when its corresponding JSL exits normally).

Configuring the JSL

The Jolt Server Listener (JSL) is a BEA Tuxedo server responsible for distributing connection requests from Jolt to the Jolt Server Handler (JSH). BEA Tuxedo must be running on the host machine where the JSL and JREPSVR are located.

Note: The way the JSL selects ports for the JSH is different than the process for the BEA Tuxedo Workstation Server Listener (WSL). For detailed information regarding on properly configuring JSL ports, refer to the "SERVERS Section" of Creating the UBBCONFIG File on page 3-33.

JSL Command-line Options

The server may need to obtain information from the command line. The CLOPT parameter allows you to specify command-line options that can change some defaults in the server. The JSL command-line options are described in the following table.

Security and Encryption

Authentication and key exchange data are transmitted between Jolt clients and the JSL/JSH using the Diffie-Hellman key exchange. All subsequent exchanges are encrypted using RC4 encryption. International packages use a DES key exchange and a 128-bit key, with 40 bits encrypted and 88 bits exposed.

Programs using the 128-bit encryption cannot be exported outside the United States without proper approval from the United States government. Customers with intranets extending beyond the United States cannot use this mode of encryption if any internal clients are outside the United States.

Jolt Relay

The combination of the Jolt Relay (JRLY) and its associated Jolt Relay Adapter (JRAD) is typically referred to as the Internet Relay. Jolt Relay routes messages from a Jolt client to a JSL or JSH. This eliminates the need for the JSH and BEA Tuxedo to run on the same machine as the Web server (which is generally considered insecure). The Jolt Relay consists of the two components illustrated in the figure Jolt Internet Relay Path.

• Jolt Relay (JRLY)—the JRLY is the Jolt Relay front-end. It is not a BEA Tuxedo client or server and is not dependent on the BEA Tuxedo version. It is a stand-alone software component. It requires only minimal configuration to allow it to work with Jolt clients.
• Jolt Relay Adapter (JRAD)—the JRAD is the Jolt Relay back-end. It is a BEA Tuxedo system server, but does not include any BEA Tuxedo services. It requires command-line arguments to allow it to work with the JSL and the BEA Tuxedo system.

Note: The Jolt Relay is transparent to Jolt clients and Jolt servers. A Jolt server can simultaneously connect to intranet clients directly, or through the Jolt Relay to Internet clients.

Figure 3-3 Jolt Internet Relay Path

This figure illustrates how a browser connects to the Web server software and downloads the BEA Jolt applets. The Jolt applet or client connects to the JRLY on the Web server machine. The JRLY forwards the Jolt messages across the firewall to the JRAD. The JRAD selectively forwards messages to the JSL or appropriate JSH.

Jolt Relay Failover

There are two points of failover associated with JRLY:

• Jolt Client to JRLY connection failover
• JRLY to JRAD connection failover

Jolt Client to JRLY Connection Failover

If one server address does not result in a successful session, the failover function allows the Jolt Client API to connect to the next free (unconnected) JRLY specified in the argument list of the API. To enable this failover in a Windows 2003 environment, multiple Windows 2003 JRLY services can be executed. In a non-Windows 2003 environment, multiple JRLY processes are executed. Each JRLY (service or process) has its own configuration file. This type of failover is handled by the client API features in BEA Jolt, which allow you to specify a list of Jolt server addresses (JSL or JRLY).

JRLY to JRAD Adapter Connection Failover

Each JRLY configuration file has a list of JRAD addresses. When a JRAD is unavailable, JRLY tries to connect to the next free (unconnected) JRAD, in a round-robin fashion. Two JRLYs cannot connect to the same JRAD. Given these facts, you can make the connection efficient by giving different JRAD address orders. That is, if you make one extra JRAD available on standby, the first JRLY that loses its JRAD connects to the extra JRAD. This type of failover is handled by JRLY alone.

If any of the listed JRADs are not executing when JRLY is started, the initial connection fails. When a Jolt client tries to connect to JRLY, the JRLY again tries to connect to the JRAD.

To accommodate the failover functionality, you have to boot multiple JRADs by configuring them in the UBBCONFIG file.

Jolt Relay Process

The JRLY (front-end relay) process can be started before or after the JRAD is started. If the JRAD is not available when the JRLY is started, the JRLY attempts to connect to the JRAD when it receives a client request. If JRLY is still unable to connect to the JRAD, the client is denied access and a warning is written to the JRLY error log file.

Starting the JRLY on UNIX

Start the JRLY process by typing the command name at a system prompt.

jrly -f config_file_path

If the configuration file does not exist or cannot be opened, the JRLY prints an error message.

If the JRLY is unable to start, it writes a message to standard error and attempts to log the startup failure in the error log, then exits.

JRLY Command-line Options for Windows 2003

This section describes command-line options that are available from the Windows 2003 version of JRLY.exe. Note the following:

• JRLY as a Windows service is available only for Windows 2003.
• When the display suffix is optional (when [display_suffix] is shown), all operations are performed on the default JRLY Windows 2003 service instance.
• For manually installed, additional JRLY services, a suffix (any string) is required. Also, you can install the default service manually by omitting the optional string suffix.
• Each instance of JRLY Windows 2003 service uses the same binary executable file.
• A new process is started for each instance of JRLY Windows 2003 service.
• The syntax for these options is: jrly -command.
• Text specified within brackets ( [ ] ) is optional.
• All commands in the following list of command options except -start and -stop require that you have write access to Windows 2003 Registry.
• The -start and -stop commands require that you have Windows 2003 Service control access. These requirements are based on Windows 2003 user restrictions.

The JRLY command-line options are detailed in the following table:

JRLY Command-line Option for UNIX

There is only one JRLY command-line option for UNIX:

JRLY Configuration File

The format of the configuration file is a TAG=VALUE format. Blank lines or lines starting with a "#" are ignored. The following listing contains an example of the formal specifications of the configuration file.

Listing 3-3 Specification of Configuration File

LOGDIR=<LOG_DIRECTORY_PATH>
ACCESS_LOG=<ACCESS_FILE_NAME in LOGDIR>
ERROR_LOG=<ERROR_FILE_NAME in LOGDIR>
LISTEN=<IP:Port combination where JRLY will accept connections>
CONNECT=<IP:Port combination associated with JRAD>

SOCKETTIMEOUT=<Seconds for socket accept()function>

Note: SOCKETTIMEOUT is the duration (in seconds) of which the relay Windows 2003 service blocks the establishment of new socket connections to allow network activity (new connections, data to be read, closed connections). It is valid only on Windows 2003 machines. SOCKETTIMEOUT also affects the SCM. When the SCM requests that the service stop, the SCM needs to wait at least SOCKETTIMEOUT seconds before doing so.

The following listing shows an example of the JRLY configuration file. The CONNECT line specifies the IP address and port number of JRAD machine.

Listing 3-4 Example of JRLY Configuration File

LOGDIR=/usr/log/relay
ACCESS_LOG=access_log
ERROR_LOG=errorlog
# jrly will listen on port 4444
LISTEN=200.100.10.100:4444
CONNECT=machine1:port1
CONNECT=machine2:port2

SOCKETTIMEOUT=30            //See text under listing

The format for directory and filenames is determined by the operating system. UNIX systems use the forward slash (/). Windows 2003 systems use the backslash (\). If any file specified in LOGDIR, ACCESS_LOG or ERROR_LOG cannot be opened for writing, the JRLY prints an error message on stderr and exits.

The formats for host names and port numbers are shown in the following table.

Jolt Relay Adapter

The Jolt Relay Adapter (back-end relay) is a BEA Tuxedo system server. The Jolt Relay Adapter (JRAD) server may or may not be located on the same BEA Tuxedo host machine in single host mode (SHM) and server group to which the JSL server is connected.

The JRAD can be started independently of its associated JRLY. JRAD tracks its startup and shutdown activity in the BEA Tuxedo log file.

JRAD Configuration

A single JRAD process can only be connected to a single JRLY. A JRAD can be configured to communicate with only one JSL and its associated JSHs. However, multiple JRADs can be configured to communicate with one JSL. The CLOPT parameter for the BEA Tuxedo servers must be included in the UBBCONFIG file. A sample of the file is shown in the listing Sample JRAD Entry in UBBCONFIG File.

The following table contains additional information about the CLOPT parameters.

The address for the JRAD CLOPT parameters can be specified in either of the following formats:

//hostname:port

0x0002pppphhhhhhhh
(where pppp is the port number and hhhhhhhh is the hexadecimal IP address)

Listing 3-5 Sample JRAD Entry in UBBCONFIG File

# JRAD host 200.100.100.10 listens at port 2000, connects to JSL port 8000 on the same host

JRAD    SRVGRP=JSLGRP   SRVID=60
        CLOPT="-A -- -l 0x000207D0C864640A -c 0x00021f40C864640A"

Network Address Configurations

A Jolt Internet Relay configuration requires that several networked components work together. Prior to configuration, review the criteria in the following table and record the information to minimize the possibility of misconfiguration.

Jolt Repository

The Jolt Repository contains BEA Tuxedo service definitions that allow Jolt clients to access BEA Tuxedo services. The Jolt Repository files included with the installation contain service definitions used internally by BEA Jolt. See Using the Jolt Repository Editor for detailed instructions on how to add definitions to the application services.

Configuring the Jolt Repository

To configure the BEA Jolt Repository, modify the application UBBCONFIG file. The UBBCONFIG file is an ASCII version of the BEA Tuxedo configuration file. Create a new UBBCONFIG file for each application. See the BEA Tuxedo Command Reference for information regarding the syntax of the entries for the file. The following listing shows relevant portions of the UBBCONFIG file.

Listing 3-6 Sample UBBCONFIG File

*GROUPS
JREPGRP        GRPNO=94 LMID=SITE1
*SERVERS
JREPSVR SRVGRP=JREPGRP SRVID=98 
RESTART=Y GRACE=0 CLOPT="-A -- -W -P /app/jrepository"
JREPSVR SRVGRP=JREPGRP SRVID=97 
RESTART=Y RQADDR=JREPQ GRACE=0 CLOPT="-A -- -P /app/jrepository"
JREPSVR SRVGRP=JREPGRP SRVID=96 
RESTART=Y RQADDR=JREPQ REPLYQ=Y GRACE=0 CLOPT="-A -- -P /app/jrepository"

Note: For UNIX systems, use the slash (/) when setting the path to the jrepository file (for example, app/repository). For Windows 2003 systems, use the backslash (\) and specify the drive name (for example, c:\app\repository).

Change the sections of the UBBCONFIG file as indicated in the following table:

GROUPS Section

A GROUPS entry is required for the group that includes the BEA Jolt Repository. The group name parameter is a name selected by the application.

Specify the same identifiers given as the value of the LMID parameter in the MACHINES section.
Specify the value of the GRPNO between 1 and 30,000 in the GROUPS section.

SERVERS Section

The Jolt Repository Server, JREPSVR, contains services for accessing and editing the repository. Multiple JREPSVR instances share repository information through a shared file. Include JREPSVR in the SERVERS section of the UBBCONFIG file.

Indicate a new server identification (for example, 98) with the SRVID parameter.
Specify the -W flag for one JREPSVR to ensure that you can edit the Repository. The Repository is read-only without this flag.

Note: You must install only one writable JREPSVR (that is, only one JREPSVR with the -W flag). Multiple read-only JREPSVRs can be installed on the same host.

Type the -P flag to specify the path of the repository file. An error message is displayed in the BEA Tuxedo ULOG file if the argument for the -P flag is not entered.
Add the file pathname of the repository file (for example, /app/jrepository).
Boot the BEA Tuxedo system using the tmloadcf command (for example, tmloadcf -y ubbconfig) and tmboot command. See Administering a BEA Tuxedo Application at Run Time for information about tmloadcf and tmboot.

Repository File

A repository file, jrepository, is available with BEA Jolt. This file includes bankapp services and the repository services that you can modify, test, and delete using the Repository Editor.

Note: If you are upgrading from version 1.x of BEA Jolt, you must use the Bulk Loader to regenerate the jrepository file in order to ensure compatibility with the current version.

Start with the jrepository file provided with the installation, even if you are not going to test the bankapp application with BEA Jolt. Delete the bankapp packages or services that you do not need.

The pathname of the file must match the argument of the -P option.

Warning: Do not modify the repository files manually or you will not be able to use the Repository Editor. Although the jrepository file can be modified and read with any text editor, the BEA Jolt system does not have integrity checks to ensure that the file is in the proper format. Any manual changes to the jrepository file might not be detected until run time. See Using the Jolt Repository Editor for additional information.

Initializing Services By Using BEA Tuxedo and the Repository Editor

Define the BEA Tuxedo services by using BEA Tuxedo and BEA Jolt Repository Editor in order to make the Jolt services available to the client.

Build the BEA Tuxedo server containing the service. See Administering a BEA Tuxedo Application at Run Time or Programming BEA Tuxedo ATMI Applications Using C for additional information on the following:
• Building the BEA Tuxedo application server
• Editing the UBBCONFIG file
• Updating the TUXCONFIG file
• Administering the tmboot command
Access the BEA Jolt Repository Editor. See Using the Jolt Repository Editor for additional information on the following:
• Adding a Service
• Saving Your Work
• Testing a Service
• Exporting and Unexporting Services

Event Subscription

Jolt Event Subscription receives event notifications from either BEA Tuxedo services or other BEA Tuxedo clients:

• Unsolicited Event Notifications—a Jolt client receives these notifications as a result of a BEA Tuxedo client or service subscribing to unsolicited events, and a BEA Tuxedo client issuing a broadcast (using either a tpbroadcast() or a directly targeted message via a tpnotify() ATMI call). Unsolicited event notifications do not need the TMUSREVT server.
• Brokered Event Notifications—a Jolt client receives these notifications through the BEA Tuxedo Event Broker. The notifications are only received when both Jolt clients subscribe to an event and any BEA Tuxedo client or server posts an event using tppost(). Brokered event notifications require the TMUSREVT server.

Configuring for Event Subscription

Configure the BEA Tuxedo TMUSREVT server and modify the application UBBCONFIG file. The following listing shows the relevant sections of TMUSREVT parameters in the UBBCONFIG file. See Programming BEA Tuxedo ATMI Applications Using C for information about the syntax of the entries for the file.

Listing 3-7 UBBCONFIG File

TMUSREVT        SRVGRP=EVBGRP1  SRVID=40        GRACE=3600
                ENVFILE="/usr/tuxedo/bankapp/TMUSREVT.ENV"
                CLOPT="-e tmusrevt.out -o tmusrevt.out -A --
                -f /usr/tuxedo/bankapp/tmusrevt.dat"
                SEQUENCE=11

In the SERVERS section of the UBBCONFIG file, modify the SRVGRP and SRVID parameters as needed.

Filtering BEA Tuxedo FML or VIEW Buffers

Filtering is a process that allows you to customize a subscription. If you require additional information about the BEA Tuxedo Event Broker, subscribing to events, or filtering, refer to Programming BEA Tuxedo ATMI Applications Using C.

In order to filter BEA Tuxedo FML or VIEW buffers, the field definition file must be available to BEA Tuxedo at run time.

Note: There are no special requirements for filtering STRING buffers.

Buffer Types

FML Buffer Example

The listing FIELDTBLS Variable in the TMUSREVT.ENV File shows an example that uses the FML buffer. The FML field definition table is made available to BEA Tuxedo by setting the FIELDTBLS and FLDTBLDIR variables.

To filter a field found in the my.flds file:

Copy the my.flds file to /usr/me/bankapp directory.
Add my.flds to the FIELDTBLS variable in the TMUSREVT.ENV file as shown in the following listing:

Listing 3-8 FIELDTBLS Variable in the TMUSREVT.ENV File

FIELDTBLS=Usysflds,bank.flds,credit.flds,event.flds,my.flds
FLDTBLDIR=/usr/tuxedo/me/T6.2/udataobj:/usr/me/bankapp

If ENVFILE="/usr/me/bankapp/TMUSREVT.ENV" is included in the definition of the UBBCONFIG file (shown in the listing UBBCONFIG File), the FIELDTBLS and FLDTBLDIR definitions are taken from the TMUSREVT.ENV file and not from your environment variable settings.

If you remove the ENVFILE="/usr/me/bankapp/TMUSREVT.ENV" definition, the FIELDTBLS and FLDTBLDIR definitions are taken from your environment variable settings. The FIELDTBLS and FLDTBLDIR definitions must be set to the appropriate value prior to booting the BEA Tuxedo system.

For additional information on event subscriptions and the BEA Jolt Class Library, refer to Using the Jolt Class Library..

BEA Tuxedo Background Information

The following sections provide detailed configuration information. Even if you are familiar with BEA Tuxedo, you should refer to this section for information concerning Jolt Service Handler (JSL) configuration.

Configuration File

The BEA Tuxedo configuration file for your application exists in two forms, the ASCII file, UBBCONFIG, and a compiled version called TUXCONFIG. Once you create a TUXCONFIG, consider your UBBCONFIG as a backup.

You can make changes to the UBBCONFIG file with your preferred text editor. Then, at a time when your application is not running, and when you are logged in to your MASTER machine, you can recompile your TUXCONFIG by running tmloadcf(1). System/T prompts you to make sure you really want to overwrite your existing TUXCONFIG file. (If you enter the command with the -y option, the prompt is suppressed.)

Creating the UBBCONFIG File

A binary configuration file called the TUXCONFIG file contains information used by tmboot(1) to start the servers and initialize the bulletin board of a BEA Tuxedo system in an orderly sequence. The binary TUXCONFIG file cannot be created directly. Initially, you must create a UBBCONFIG file. That file is parsed and loaded into the TUXCONFIG using tmloadcf(1). Then tmadmin(1) uses the configuration file or a copy of it in its monitoring activity. tmshutdown(1) references the configuration file for information needed to shut down the application.

Configuration File Format

The UBBCONFIG file can consist of up to nine specification sections. Lines beginning with an asterisk (*) indicate the beginning of a specification section. Each such line contains the name of the section immediately following the *. Allowable section names are: RESOURCES, MACHINES, GROUPS, NETGROUPS, NETWORK, SERVERS, SERVICES, INTERFACES, and ROUTING.

Note: The RESOURCES (if used) and MACHINES sections must be the first two sections, in that order; the GROUPS section must be ahead of SERVERS, SERVICES, and ROUTING.

To configure the JSL, you must modify the UBBCONFIG file. For further information about BEA Tuxedo configuration, refer to Administering a BEA Tuxedo Application at Run Time.

The following listing shows relevant portions of the UBBCONFIG file.

Listing 3-9 UBBCONFIG File

*MACHINES
MACH1 	LMID=SITE1	
	MAXWSCLIENTS=40
*GROUPS
JSLGRP		GRPNO=95   LMID=SITE1
*SERVERS	
JSL SRVGRP=JSLGRP	 SRVID=30 CLOPT= " -- -n 0x0002PPPPNNNNNNNN -d 
/dev/tcp -m2 -M4 -x10"

The parameters shown in the following table are the only parameters that must be designated for the Jolt Server groups and Jolt Servers. You are not required to specify any other parameters.

Change the sections of the UBBCONFIG file as shown in the following table.

MACHINES Section

The MACHINES section specifies the logical names for physical machines for the configuration. It also specifies parameters specific to a given machine. The MACHINES section must contain an entry for each physical processor used by the application. Entries have the form:

ADDRESS or NAME required parameters [optional parameters]

where ADDRESS is the physical name of the processor, for example, the value produced by the UNIX system uname -n command.

LMID=string_value

This parameter specifies that the string_value is to be used in other sections as the symbolic name for ADDRESS. This name cannot contain a comma, and must be 30 characters or less. This parameter is required. There must be an LMID line for every machine used in a configuration.

MAXWSCLIENTS=number

The MAXWSCLIENTS parameter is required in the MACHINES section of the configuration file. It specifies the number of accesser entries on this processor to be reserved for Jolt and Workstation clients only. The value of this parameter must be between 0 and 32,768, inclusive.

The Jolt Server and Workstation use MAXWSCLIENTS in the same way. For example, if 200 slots are configured for MAXWSCLIENTS, this number configures BEA Tuxedo for the total number of remote clients used by Jolt and Workstation.

Be sure to specify MAXWSCLIENTS in the configuration file. If it is not specified, the default is 0.

Note: If MAXWSCLIENTS is not set, the JSL does not boot.

GROUPS Section

This section provides information about server groups, and must have at least one server group defined in it. A server group entry provides a logical name for a collection of servers and/or services on a machine. The logical name is used as the value of the SRVGRP parameter in the SERVERS section to identify a server as part of this group. SRVGRP is also used in the SERVICES section to identify a particular instance of a service with its occurrences in the group. Other GROUPS parameters associate this group with a specific resource manager instance (for example, the employee database). Lines within the GROUPS section have the form:

GROUPNAME required parameters [optional parameters]

where GROUPNAME specifies the logical name (string_value) of the group. The group name must be unique within all group names in the GROUPS section and LMID values in the MACHINES section. The group name cannot contain an asterisk(*), comma, or colon, and must be 30 characters or less.

A GROUPS entry is required for the group that includes the Jolt Server Listener (JSL). Make the GROUPS entry as follows:

The group name is selected by the application, for example: JSLGRP and JREPGRP.
Specify the same identifiers given as the value of the LMID parameter in the MACHINES section.
Specify the value of the GRPNO between 1 and 30,000 in the *GROUPS section.

Note: Make sure that Resource Managers are not assigned as a default value for all groups in the GROUPS section of your UBBCONFIG file. Making Resource Managers the default value assigns a Resource Manager to the JSL and you receive an error during tmboot. In the SERVERS section, default values for RESTART, MAXGEN, etc., are acceptable defaults for the JSL.

SERVERS Section

This section provides information on the initial conditions for servers started in the system. The notion of a server as a process that continually runs and waits for a server group's service requests to process may or may not apply to a particular remote environment. For many environments, the operating system, or perhaps a remote gateway, is the sole dispatcher of services. When either of these is the case, you need only specify SERVICE entry points for remote program entry points, and not SERVER table entries. BEA Tuxedo system gateway servers would advertise and queue remote domain service requests. Host-specific reference pages must indicate whether or not UBBCONFIG server table entries apply in their particular environments, and if so, the corresponding semantics. Lines within the SERVERS section have the form:

AOUT required parameters [optional parameters]

where AOUT specifies the file (string_value) to be executed by tmboot(1). tmboot executes AOUT on the machine specified for the server group to which the server belongs. tmboot searches for the AOUT file on its target machine, thus, AOUT must exist in a file system on that machine. (Of course, the path to AOUT can include RFS connections to file systems on other machines.) If a relative pathname for a server is given, the search for AOUT is done sequentially in APPDIR, TUXDIR/bin, /bin, and then in path, where <path> is the value of the last PATH= line appearing in the machine environment file, if one exists. The values for APPDIR and TUXDIR are taken from the appropriate machine entry in the TUXCONFIG file.

Clients connect to BEA Jolt applications through the Jolt Server Listener (JSL). Services are accessed through the Jolt Server Handler (JSH). The JSL supports multiple clients and acts as a single point of contact for all the clients to connect to the application at the network address that is specified on the JSL command line. The JSL schedules work for handler processes. A handler process acts as a substitute for clients on remote workstations within the administrative domain of the application. The handler uses a multiplexing scheme to support multiple clients on one port concurrently.

The network address specified for the JSL designates a TCP/IP address for both the JSL and any JSH processes associated with that JSL. The port number identified by the network address specifies the port number on which the JSL accepts new client connections. Each JSH associated with the JSL uses consecutive port numbers at the same TCP/IP address. For example, if the initial JSL port number is 8000 and there are a maximum of three JSH processes, the JSH processes use ports 8001, 8002, and 8003.

Note: Misconfiguration of the subsequent JSL results in a port number collision.

Parameters Usable with JSL

In addition to the parameters specified in the previous sections, the following parameters can be used with the JSL, although you need to understand how doing so would affect your application.

SVRGRP=string_value

This parameter specifies the group name for the group in which the server is to run. string_value must be the logical name associated with a server group in the *GROUPS section, and must be 30 characters or less. This association with an entry in the *GROUPS section means that AOUT is executed on the machine with the LMID specified for the server group. This association also specifies the GRPNO for the server group and parameters to pass when the associated resource manager is opened. All server entries must have a server group parameter specified.

SRVID=number 

This parameter specifies an identifier, an integer between 1 and 30,00, inclusive, that identifies this server within its group. This parameter is required on every server entry, even if the group has only one server. If multiple occurrences of servers are desired, do not use consecutive numbers for SRVIDs; leave enough room for the system to assign additional SRVIDs up to MAX.

Optional Parameters

The optional parameters of the SERVERS section are divided into boot parameters and run-time parameters.

Boot Parameters

Boot parameters are used by tmboot when it executes a server. Once running, a server reads its entry from the configuration file to determine its run-time options. The unique server identification number is used to find the right entry. The following are boot parameters.

CLOPT=string_value

The CLOPT parameter specifies a string of command-line options to be passed to AOUT when booted.The servopts(5) page in the File Formats, Data Descriptions, MIBs, and System Processes Reference lists the valid parameters.

Some of the available options apply primarily to servers under development. For example, the -r option directs the server to write a record to its standard error file each time a service request begins or ends.

Other command-line options can be used to direct the server's standard out (stdout) and standard error (stderr) to specific files, or to start the server so that it initially advertises a limited set of its available services.

The default value for the CLOPT parameter is -A, which means that the server is started with all available services advertised.

The maximum length of the CLOPT parameter value is 256 characters; it must be enclosed in double quotes.

SEQUENCE=number

This parameter specifies when to shut down or boot relative to other servers. If SEQUENCE is not specified, servers are booted in the order found in the SERVERS section (and shut down in the reverse order). If some servers have sequence numbers specified and others do not, all servers with sequence numbers are booted first from low to high sequence number, then all servers without sequence numbers are booted in the order in which they appear in the configuration file. Sequence numbers range between 1 and 9999. If the same sequence number is assigned to more than one server, tmboot may boot those servers in parallel.

MIN=number

The MIN parameter specifies the minimum number of occurrences of the server to boot by tmboot. If an RQADDR is specified, and MIN is greater than 1, the servers form a multiple servers single queue (MSSQ) set. The identifiers for the servers are SRVID up to (SRVID + (MAX -1)). All occurrences of the server have the same sequence numbers as well as any other server parameters. The value range for MIN is 0 to 1000. If MIN is not specified, the default value is 1.

MAX=number

The MAX parameter sets the maximum number of occurrences of the server to be booted. Initially, tmboot boots MIN servers, and additional servers can be booted up to MAX occurrences using the -i option of tmboot to specify the associated server identifier. The value range for MAX is 0 to 1000. If no value is specified for MAX, the default is the same as for MIN, or 1.

• tmboot starts MIN occurrences unless you explicitly call for more with the -i SRVID option of tmboot.
• If RQADDR is specified and MIN is greater than one, an MSSQ set is formed
• If MIN is not specified, the default is 1.
• If MAX is not specified, the default is MIN.
• MAX is especially important for conversational servers because they are spawned automatically as needed.

Run-time Parameters

The server uses run-time parameters after it is started by tmboot. As indicated previously, tmboot uses the values found in the TUXDIR, APPDIR and ENVFILE parameters for the MACHINES section when booting the server. It also sets the PATH for the server to:

"APPDIR:TUXDIR/bin:/bin:path"

where path is the value of the last PATH= line appearing in the ENVFILE file. The following parameters are run-time parameters.

ENVFILE=string_value

You can use the ENVFILE parameter for a server to add values to the environment established by tmboot during initialization of the server. You can optionally set variables specified in the file named in the SERVERS ENVFILE parameter after you set those in the MACHINES ENVFILE used by tmboot. These files cannot be used to override TUXDIR, APDIR, TUXCONFIG, or TUSOFFSET. The best policy is to include in the server's ENVFILE only those variable assignments known to be needed to ensure proper running of the application.

On the server, the ENVFILE file is processed after the server starts. Therefore, it cannot be used to set the pathnames used to find executable or dynamically loaded files needed to execute the server. If you need to perform these tasks, use the machine ENVFILE instead.

Within ENVFILE only lines of the form

VARIABLE =string

are allowed. VARIABLE must start with an underscore or alphabetic character and can contain only underscore or alphanumeric characters. If the server is associated with a server group that can be migrated to a second machine, the ENVFILE must be in the same location on both machines.

CONV={Y | N}

CONV specifies whether the server is a conversational server. CONV takes a Y value if a conversational server is being defined. Connections can only be made to conversational servers. For a request/response server, you can either set CONV=N, which is the default, or omit the parameter.

RQADDR=string_value

RQADDR assigns a symbolic name to the request queue of this server. MSSQ sets are established by using the same symbolic name for more than one server (or by specifying MIN greater than 1). All members of an MSSQ set must offer an identical set of services and must be in the same server group.

If RQADDR is not specified, the system assigns a unique key to serve as the queue address for this server. However, tmadmin commands that take a queue address as an argument are easier to use if queues are given symbolic names.

RQPERM=number

Use the RQPERM parameter to assign UNIX-style permissions to the request queue for this server. The value of number can be between 0001 and 0777, inclusive. If no parameter is specified, the permissions value of the bulletin board, as specified by PERM in the RESOURCES section, is used. If no value is specified there, the default of 0666 is used (the default exposes your application to possible use by any login on the system, so consider this carefully).

REPLYQ={ Y | N }

The REPLYQ parameter specifies whether a reply queue, separate from the request queue, should be established for AOUT. If N is specified, the reply queue is created on the same LMID as the AOUT. If only one server is using the request queue, replies can be retrieved from the request queue without causing problems. However, if the server is a member of an MSSQ set and contains services programmed to receive reply messages, REPLYQ should be set to Y so that an individual reply queue is created for this server. If set to N, the reply is sent to the request queue shared by all servers for the MSSQ set, and you cannot ensure that the reply will be picked up by the server that is waiting for it.

It should be standard practice for all member servers of an MSSQ set to specify REPLYQ=Y if replies are anticipated. Servers in an MSSQ set are required to have identical offerings of services, so it is reasonable to expect that if one server in the set expects replies, any server in the set can also expect replies.

RPPERM=number

Use the RPPERM parameter to assign permissions to the reply queue. number is specified in the usual UNIX fashion (for example, 0600); the value can be between 0001 and 0777, inclusive. If RPPERM is not specified, the default value 0666 is used. This parameter is useful only when REPLYQ=Y. If requests and replies are read from the same queue, only RQPERM is needed; RPPERM is ignored.

RESTART={ Y | N }

The RESTART parameter takes a Y or N to indicate whether AOUT is restartable. The default is N. If the server is in a group that can be migrated, RESTART must be Y. A server started with a SIGTERM signal cannot be restarted; it must be rebooted.

An application's policy on restarting servers might vary according to whether the server is in production or not. During the test phase of application development it is reasonable to expect that a server might fail repeatedly, but server failures should be rare events once the application has been put into production. You might want to set more stringent parameters for restarting servers once the application is in production.

Parameters Associated with RESTART

RCMD=string_value

If AOUT is restartable, this parameter specifies the command that should be executed when AOUT abnormally terminates. The string, up to the first space or tab, must be the name of an executable UNIX file, either a full pathname or relative to APPDIR. (Do not attempt to set a shell variable at the beginning of the command.) Optionally, the command name can be followed by command-line arguments. Two additional arguments are appended to the command line: the GRPNO and SRVID associated with the restarting server. string_value is executed in parallel with restarting the server.

You can use the RCMD parameter to specify a command to be executed in parallel with the restarting of the server. The command must be an executable UNIX system file residing in a directory on the server's PATH. An example is a command that sends a customized message to the userlog to mark the restarting of the server.

MAXGEN=number

If AOUT is restartable, this parameter specifies that it can be restarted at most (number - 1) times within the period specified by GRACE. The value must be greater than 0 and less than 256. If not specified, the default is 1 (which means that the server can be started once, but not restarted). If the server is to be restartable, MAXGEN must be equal to or greater than 2. RESTART must be Y or MAXGEN is ignored.

GRACE=number

If RESTART is Y, the GRACE parameter specifies the time period (in seconds) during which this server can be restarted, (MAXGEN - 1) times. The number assigned must be equal to or greater than 0, and less than 2,147,483,648 seconds (or a little more than 68 years). If GRACE is not specified the default is 86,400 seconds (24 hours). Setting GRACE to 0 removes all limitations; the server can be restarted an unlimited number of times.

Entering Parameters

You can use BEA Tuxedo parameters, including RESTART, RQADDR, and REPLYQ, with the JSL. (See Administering a BEA Tuxedo Application at Run Time for additional information regarding run-time parameters.) Enter the following parameters:

To identify the SRVGRP parameter, type the previously defined group name value from the GROUPS section.
To indicate the SRVID, type a number between 1 and 30,000 that identifies the server within its group.
Verify that the syntax for the CLOPT parameter is as follows:

CLOPT= "-- -n 0x0002PPPPNNNNNNNN -d /dev/tcp -m2 -M4 -x10"

Note: The CLOPT parameters may vary. Refer to the table JSL Command-line Options for pertinent command-line information.

If necessary, type the optional parameters:
• Type the SEQUENCE parameter to determine the order that the servers are booted.
• Specify Y to permit release of the RESTART parameter.
• Type 0 to permit an infinite number of server restarts using the GRACE parameter.

Sample Applications in BEA Jolt Online Resources

You can access sample code that can be modified for use with BEA Jolt through the BEA Jolt product Web page at:

http://www.bea.com/products/jolt/index.htm

These samples demonstrate and utilize BEA Jolt features and functionality.

Other Web sites with Java-related information include:

• Javasoft Home page (http://www.java.sun.com/)
• Newsgroups in the comp.lang.java hierarchy. These groups contain lists of past articles and communications regarding Java, and are a valuable source of archival material.