Using Oracle Jolt

Configuring the Oracle Jolt System

This chapter describes how to configure Oracle 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 Oracle Jolt.

This topic includes the following sections:

Quick Configuration

If you are already familiar with Oracle Jolt and Oracle 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 Oracle Tuxedo and covers the following procedures:

Editing the UBBCONFIG File

Configuring the Jolt Repository

The following sections assist you in configuring the Jolt Repository.

In the Groups Section

In the Servers Section

The Oracle 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 Oracle Tuxedo and the Repository Editor

Define the Oracle Tuxedo services that use Oracle Tuxedo and Oracle 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 Oracle Jolt software.

To use the Repository Editor, you must:

Starting the Repository Editor Using the Java Applet Viewer

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

To start from a Web server

Logging On to the Repository Editor

After starting the Jolt Repository Editor, follow these directions to log on:

The following table, Repository Editor Logon Window Description, contains details about each of the fields and buttons.

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 Oracle 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 Oracle Tuxedo TMUSREVT Server for Event Subscription

Jolt Event Subscription receives event notifications from either Oracle Tuxedo services or other Oracle Tuxedo clients. Configure the Oracle 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:

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 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:

jrly -f <config_file_path>

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 2003

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.

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 2003 Only (Optional)

SOCKETTIMEOUT is the time in seconds for which JRLY Windows 2003 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 2003 service to stop, the SCM must wait for at least SOCKETTIMEOUT seconds before quitting.

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 Oracle 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 Oracle Jolt system. The JSL runs as an Oracle Tuxedo server.

Jolt Server Handler (JSH)—the JSH is a program that runs on an Oracle 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 Oracle 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 Oracle Jolt include:

Starting the JSL

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

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

Shutting Down the JSL

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

 tmshutdown -y

During shutdown:

Restarting the JSL

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

Configuring the JSL

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

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

When LLE is used for Jolt security and encryption, authentication and key exchange data are transmitted beween Jolt clients and the JSL/JSH using the Diffie-Hellman key echange. 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.

When SSL is used for Jolt security and encryption, the SSL protocol is used for authentication, key exchange, and data exchange.

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 Oracle 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.

This figure illustrates how a browser connects to the Web server software and downloads the Oracle 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

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 Oracle 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:

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.

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>

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

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 Table 3-6.

Jolt Relay Adapter

The Jolt Relay Adapter (back-end relay) is an Oracle Tuxedo system server. The Jolt Relay Adapter (JRAD) server may or may not be located on the same Oracle 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 Oracle 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 Oracle 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)

# 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 Oracle Tuxedo service definitions that allow Jolt clients to access Oracle Tuxedo services. The Jolt Repository files included with the installation contain service definitions used internally by Oracle 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 Oracle Jolt Repository, modify the application UBBCONFIG file. The UBBCONFIG file is an ASCII version of the Oracle Tuxedo configuration file. Create a new UBBCONFIG file for each application. See the Oracle Tuxedo Command Reference for information regarding the syntax of the entries for the file. The following listing shows relevant portions of the 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"

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 Oracle 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 Oracle Jolt. This file includes bankapp services and the repository services that you can modify, test, and delete using the Repository Editor.

Start with the jrepository file provided with the installation, even if you are not going to test the bankapp application with Oracle 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 Oracle 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 Oracle Tuxedo and the Repository Editor

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

Event Subscription

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

Configuring for Event Subscription

Configure the Oracle 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 Oracle Tuxedo ATMI Applications Using C for information about the syntax of the entries for the 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 Oracle Tuxedo FML or VIEW Buffers

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

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

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 Oracle Tuxedo by setting the FIELDTBLS and FLDTBLDIR variables.

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

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 Oracle Tuxedo system.

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

Oracle Tuxedo Background Information

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

Configuration File

The Oracle 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 an Oracle 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.

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

The following listing shows relevant portions of the 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 Oracle 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.

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:

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. Oracle 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 Oracle 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.

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,000, 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. 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 Oracle Tuxedo parameters, including RESTART, RQADDR, and REPLYQ, with the JSL. (See Administering an Oracle Tuxedo Application at Run Time for additional information regarding run-time parameters.) Enter the following parameters:

Sample Applications in Oracle Jolt Online Resources

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

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

These samples demonstrate and utilize Oracle Jolt features and functionality.

Other Web sites with Java-related information include: