e-docs > Tuxedo > Using JOLT > Configuring the BEA Jolt System |
Using JOLT |
Configuring the BEA Jolt System
This chapter describes how to configure BEA Jolt. Quick Configuration is for users who are familiar with Jolt. The other sections provide more detailed information. It is presumed that readers are system administrators or application developers who have experience with the operating systems and workstation platforms on which they are configuring BEA Jolt.
This topic includes the following sections:
Quick Configuration
If you are already familiar with BEA Jolt and BEA Tuxedo, Quick Configuration provides efficient guidelines for the configuration procedure. If you have not used Jolt, refer to Jolt Background Information before you begin any configuration procedures.
Quick Configuration contains the information you need to configure the Jolt Server Listener (JSL) on BEA Tuxedo and covers the following procedures:
Editing the UBBCONFIG File
Note: If MAXWSCLIENTS is not set, JSL does not boot.
Configuring the Jolt Repository
In the Groups Section
In the Servers Section
The BEA 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.
Initializing Services That Use BEA Tuxedo and the Repository Editor
Define the BEA Tuxedo services that use BEA Tuxedo and BEA Jolt in order to make the Jolt services available to the client.
Getting Started with the Repository Editor
Before you start the Repository Editor, make certain that you have installed all of the necessary BEA Jolt software.
Note: You cannot use the Repository Editor until JREPSVR and JSL are running.
To use the Repository Editor, you must:
Starting the Repository Editor Using the Java Applet Viewer
appletviewer full-pathname/RE.html
Starting the Repository Editor Using Your Web Browser
Use one of the following procedures to start the Repository Editor from your Web browser.
To start the Repository Editor from a local file
file:full-pathname/RE.html
To start from a Web server
http://www.server/URL path/RE.html
Logging On to the Repository Editor
After starting the Jolt Repository Editor, follow these directions to log on:
Note: The BEA Jolt Repository Editor Logon Window must be displayed before you log on. Refer to this figure as you perform the following procedure.
The following table, Repository Editor Logon Window Description, contains details about each of the fields and buttons.
Repository Editor Logon Window Description
Table 3-1 Repository Editor Logon Window Description
Exiting the Repository Editor Exit the Repository Editor when you finish adding, editing, testing, or deleting packages, services, and parameters. Prior to exit, the window is displayed as shown in the figure BEA Jolt Repository Editor Logon Window Prior to Exit. Figure 3-2 BEA Jolt Repository Editor Logon Window Prior to Exit
.
Note that only the Packages, Services, and Log Off command buttons are enabled. All of the text entry fields are disabled. Follow the steps below to exit the Repository Editor.
Configuring the BEA Tuxedo TMUSREVT Server for Event Subscription
Jolt Event Subscription receives event notifications from either BEA Tuxedo services or other BEA Tuxedo clients. Configure the BEA Tuxedo TMUSREVT server and modify the application UBBCONFIG file. The following listing, TMUSREVT Parameters in the UBBCONFIG File, shows the relevant TMUSREVT parameters in the UBBCONFIG file:
Listing 3-1 TMUSREVT Parameters in the UBBCONFIG File In the SERVERS sections of the UBBCONFIG file, specify the SRVGRP and SRVID. Configuring Jolt Relay On UNIX Start the JRLY process on UNIX by typing the following command at the system prompt: If the configuration file does not exist or cannot be opened, the JRLY writes a message to standard error, attempts to log the startup failure in the error log, then exits. On UNIX and Windows 2000
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=11jrly -f <config_file_path>
The format of the configuration file is a TAG=VALUE format. Blank lines or lines starting with a "#" are ignored. The following listing, Formal Configuration File Specifications, is an example of the formal specifications of the configuration file.
Listing 3-2 Formal Configuration File Specifications
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 comma-separated connections>
CONNECT=<IP:Port1, IP:Port2...IP:PortN:Port(List of IP:Port combinations associated with JRADs: can be 1...N)>
On Windows 2000 Only (Optional)
SOCKETTIMEOUT is the time in seconds for which JRLY Windows 2000 service blocks for network activity (new connections, data to be read, closed connections). SOCKETTIMEOUT also affects the Service Control Manager (SCM). When the SCM requests the Windows 2000 service to stop, the SCM must wait for at least SOCKETTIMEOUT seconds before quitting.
Note: The format for directory and filenames is determined by the operating system. UNIX systems use the forward slash (/). Windows 2000 systems use the backslash (\). If any files specified in LOGDIR, ACCESS_LOG, or ERROR_LOG cannot be opened for writing, JRLY prints an error message on stderr and exits.
The formats for the host names and the port numbers are shown in the following table.
Start the Jolt Relay Adapter (JRAD)
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.
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:
Starting the JSL
To start all administrative and server processes in the UBBCONFIG 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:
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:
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-39.
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.
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 failovers associated with JRLY:
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 2000 environment, multiple Windows 2000 JRLY services can be executed. In a non-Windows 2000 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 2000
This section describes command-line options that are available from the Windows 2000 version of JRLY.exe. Note the following:
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 2000 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 2000 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 2000 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 2000 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.
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.
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.
Event Subscription
Jolt Event Subscription receives event notifications from either BEA Tuxedo services or other BEA Tuxedo clients:
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:
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: where ADDRESS is the physical name of the processor, for example, the value produced by the UNIX system uname -n command. 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. 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: 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:
ADDRESS or NAME required parameters [optional parameters]
LMID=string_value
MAXWSCLIENTS=number
GROUPNAME required parameters [optional parameters]
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.
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:
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
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, and rpc requests (via tpacall(3c) or tpcall(3c)) can only be made to non-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:
CLOPT= "-- -n 0x0002PPPPNNNNNNNN -d /dev/tcp -m2 -M4 -x10"
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: