Using Oracle Jolt

     Previous  Next    Open TOC in new window  Open Index in new window  View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

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

  1. In the MACHINES section, specify MAXWSCLIENTS=number (Required).
Note: If MAXWSCLIENTS is not set, JSL does not boot.
  1. In the GROUPS section, set GROUPNAME required parameters [optional parameters].
  2. Set the SERVERS section (Required).
  3. Lines within this section have the form:

    JSL required parameters [optional parameters] 

    where JSL specifies the file (string_value) to be executed by tmboot(1).

  4. Set the required parameters for JSL.
  5. Required parameters are:

    SVRGRP=string_value

    SRVID=number

    CLOPT=”-A...-n...//host port

  6. Set other parameters for JSL.
  7. You can use the following parameters with the JSL, but you need to understand how doing so affects your application. Refer to Parameters Usable with JSL for additional information.

    MAX # of JSHs

    MIN # of JSHs

Configuring the Jolt Repository

The following sections assist you in configuring the Jolt Repository.

In the Groups Section

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

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.

  1. Indicate a new server identification with the SRVID parameter.
  2. Specify the -W flag for one (and only one) JREPSVR to ensure that you can edit the repository. (Without this flag, the repository is read-only.)
  3. Type the -P flag to specify the path of the repository file. (An error message is displayed in the Oracle Tuxedo ULOG file if the argument for the -P flag is not entered.)
  4. Add the file pathname of the Repository file (for example, /app/jrepository).
  5. Boot the Oracle Tuxedo system by using the tmloadcf and tmboot commands.

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.

  1. Build the Oracle Tuxedo server that contains the service.
  2. Access the Oracle Jolt Repository Editor.

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.

Note: You cannot use the Repository Editor until JREPSVR and JSL are running.

To use the Repository Editor, you must:

  1. Start the Repository Editor.
  2. You can start the Repository Editor from either the JavaSoft appletviewer or from your Web browser. Both of these methods are detailed in the following sections.

  3. Log on to the Repository Editor.

Starting the Repository Editor Using the Java Applet Viewer

  1. Set the CLASSPATH to include the Jolt class directory or the directory where the *.jar files reside.
  2. If loading the applet from a local disk, type the following at the URL location:
  3. appletviewer full-pathname/RE.html

    If loading the applet from the Web server, type the following at the URL location:

    http://www.server/URL path/RE.html
  4. Press Enter.
  5. The window is displayed as shown in the figure Oracle Jolt Repository Editor Logon Window.

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
  1. Set the CLASSPATH to include the Jolt class directory.
  2. Type the following:
  3. file:full-pathname/RE.html
  4. Press Enter.
  5. The window is displayed as shown in the figure Oracle Jolt Repository Editor Logon Window.

To start from a Web server
  1. Ensure that the CLASSPATH does not include the Jolt class directory.
  2. Remove the Jolt cases from CLASSPATH.
  3. Type the following:
  4. http://www.server/URL path/RE.html
    Note: If jolt.jar and admin.jar are in the same directory as RE.html, the Web server provides the classes. If they are not in the same directory as RE.html, modify the applet code base.
  5. Press Enter.
  6. The Repository Editor Logon window is displayed as shown in the figure Oracle Jolt Repository Editor Logon Window.

Logging On to the Repository Editor

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

Note: The Oracle Jolt Repository Editor Logon Window must be displayed before you log on. Refer to this figure as you perform the following procedure.
  1. In the logon window, type the name of the Server machine designated as the “access point” to the Oracle Tuxedo application and press Tab.
  2. Type the Port Number and press Enter.
  3. The system validates the server and port information.

    Note: Unless you are logging on through Jolt Relay, the same port number is used to configure the Jolt Listener. Refer to your UBBCONFIG file for additional information.
  4. Type the Oracle Tuxedo Application Password and press Enter.
  5. Depending upon the authentication level, complete steps 5 and 6 as required.

  6. Type the Oracle Tuxedo User Name and press Tab.
  7. Type the Oracle Tuxedo User Password and press Enter.
  8. The Packages and Services command buttons are enabled.

    Note: The Oracle Jolt Repository Editor uses the hardcoded joltadmin for the User Role value.
    Figure 3-1 Oracle Jolt Repository Editor Logon Window


    Oracle Jolt Repository Editor Logon Window

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
Option
Description
Server
The server name.
Port Number
The port number in decimal value.
Note: After the Server Name and Port Number are entered, the User Name and Password fields are activated. Activation is based on the authentication level of the Oracle Tuxedo application.
User Role
Oracle Tuxedo user role. Required only if Oracle Tuxedo authentication level is USER_AUTH or higher.
Application Password
Oracle Tuxedo administrative password text entry.
User Name
Oracle Tuxedo user identification text entry. The first character must be an alpha character.
User Password
Oracle Tuxedo password text entry.
Packages
Accesses the Packages window. (Enabled after the logon.)
Services
Accesses the Services window. (Enabled after the logon.)
Log Off
Terminates the connection with the server.

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.

Figure 3-2 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.

  1. Click Back in a previous window to return to the Repository Editor Logon window.
  2. Click Log Off to terminate the connection with the server.
  3. The Repository Editor Logon window shows disabled fields.

  4. Click Close from your browser menu to close the window.

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:

Listing 3-1 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.

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

Note: 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 files specified in LOGDIR, ACCESS_LOG, or ERROR_LOG cannot be opened for writing, JRLY prints an error message on stderr and exits.
Note: The formats for the host names and the port numbers are shown in Table 3-2.
Start the Jolt Relay Adapter (JRAD)
  1. Type tmloadcf -y <UBBFILE>.
  2. 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 Oracle Tuxedo services must be included in the UBBCONFIG file.

  1. Type -l hexadecimal format (The JSL port to which the JRLY connects on behalf of the client.)
  2. Type -c hexadecimal format (The address of the corresponding JSL to which JRAD connects.)
  3. Note: The format is 0x0002PPPNNN, or, in dot notation, 100.100.10.100.
  4. Configure networked components.
  5. 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 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:

  1. Type tmloadcf.
  2. This command parses the configuration file and loads the binary version of the configuration file.

  3. Type tmboot -y.
  4. 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 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.

Note: The way the JSL selects ports for the JSH is different than the process for the Oracle 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-34.

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

Table 3-2 JSL Command-line Options
Option
Description
[-a]
Enables or disables the security context for a Jolt connection pool. This option should be enabled if you want to implement authentication propagation between WebLogic Server and Jolt. If identity propagation is desired, then the Jolt Service Handler (JSH) must be started with this option. If the -a option is not set, but SecurityContext is enabled, the JSH will not accept this request. If the SecurityContext attribute is enabled, then the Jolt client will pass the username of the caller to the JSH.
If the JSH, gets a message with the caller’s identity, it calls impersonate_user() to get the appkey for the user. JSH caches the appkey, so the next time the caller makes a request, the appkey is retrieved from the cache and the request is forwarded to the service. A cache is maintained by each JSH, which means that there will be a cache maintained for all the session pools connected to the same JSH.
[-A]
Specifies that certificate-based authentication should be required when accepting an SSL connection from a remote application.

Note: The JSL -A option is equivalent to the ISL(5) and WSL(5) -a option. For more information see, Section 5 - File Formats, Data Descriptions, MIBs, and System Processes Reference.

[-c compression_threshold]
Enables application data sent between a Jolt client and a Jolt server (JSH) to be compressed during transmission over the network.
compression_threshold is a number that you specify between 0 and 2,147,483,647 bytes. Any messages that are larger than the specified compression threshold are compressed before transmission.
The default is no compression; that is, if no compression threshold is specified, Oracle Jolt does not compress messages on client or server.
[-d device_name]
The device for platforms using the Transport Layer Interface. There is no default. Required. (Optional for sockets)
[-H external netaddr]
Specifies the network address mask Jolt clients use to connect to the application when there is network address translation. The JSL process uses this address to listen for clients attempting to connect at this address. If the external address mask is 0x0002MMMMdddddddd and the JSH network address is 0x00021111ffffffff, the known (or external) network address is 0x00021111dddddddd. If the address starts with "//" network address, the type is IP based and the TCP/IP port number of the JSH network address is copied into the address to form the combined network address.
The external IP address mask must be specified in the following form:
-H //external ip address:MMMM
(Optional for JSL in Oracle Tuxedo 6.4 and 6.5)

Note: The option does not support IPv6.

[-I init-timeout]
The time (in seconds) that a Jolt client is allowed to complete initialization through the JSH before it is timed out by the JSL. Default is 60 seconds. (Optional)
[-j connection_mode]
The following connection modes from clients are allowed:
RETAINED—the network connection is retained for the full duration of a session.
RECONNECT—the client establishes and brings down a connection when an idle timeout is reached, reconnecting for multiple requests within a session.
ANY—the server allows a client to request either a RETAINED or RECONNECT type of connection for a session.
The default is ANY. That is, if no option is specified, the server allows a client to request either a RETAINED or RECONNECT type of connection. (Optional)
[-m minh]
The minimum number of JSHs that are available in conjunction with the JSL at one time. The range of this parameter is from 0 through 255. Default is 0. (Optional)
[-M maxh]
The maximum number of JSHs that are available in conjunction with the JSL at one time. If this option is not specified, the parameter defaults to the MAXWSCLIENTS divided by the -x multiplexing factor (MPX), with the result rounded up. If specified, the -M option takes a value from 1 to 32,767. (Optional)
[-n netaddr]
Network address used by the Oracle Jolt listener with Oracle Tuxedo 6.4 and 6.5, and WebLogic Enterprise 4.2.
TCP/IP addresses may be specified in the following formats:
  • IPv4
  • //IP:port

    //hostname:port_number

    //#.#.#.#:port_number

    The domain finds an address for hostname by using the local name resolution facilities (usually DNS). hostname must be the local machine, and the local name resolution facilities must unambiguously resolve hostname to the address of the local machine.

    The “#.#.#.#” is in dotted decimal format. In dotted decimal format, each # should be a number from 0 to 255. This dotted decimal number represents the IP address of the local machine. In both of the above formats, port_number is the TCP port number at which the domain process listens for incoming requests. port_number can either be a number between 0 and 65535 or a name.

  • IPv6
  • //[IPv6 address]:port

    //hostname:port_number

    Note: IPv6 does not support hexadecimal format

  • SDP
  • sdp://IB_IP:port

[-R renegotiation-interval]
Specifies the renegotiation interval in minutes. After the specified number of minutes have elapsed without renegotiation of the SSL encryption parameters for a particular SSL session, the SSL encryption parameters will be renegotiated on the next exchange of data, as described in the SSL and TLS standards. The default is 0 minutes which results in no periodic session renegotiation.

Note: If the -R parameter is specified and the -S parameter is not specified or set to 0, the JSL sends a warning message to the userlog.

[-S Client-timeout]
The idle time (in minutes) when the client does not have any outstanding requests. In other words, when the client is “snoozing.”
This option can be used together with the -T option. When either timeout reached, JSH will close the session.
If a parameter is not specified, the default is no timeout. (Optional)
[-s secure-port]
Specifies the port number that the JSL should use to listen for secure connections using the SSL protocol. You can configure the JSL to allow only secure connections by setting the port numbers specified by the -s and -n options to the same value.
This option cannot be used if the JRLY and JRAD processes are used.
The JSL -s option is equivalent to the ISL(5) and WSL(5) -S option. For more information see, Section 5 - File Formats, Data Descriptions, MIBs, and System Processes Reference.
[-T Client-timeout]
The time (in minutes) allowed for a client to stay idle. If a client does not make any requests during this time, the JSH disconnects the client and the session is terminated. If an argument is not supplied, the session does not timeout.
When the -j ANY or -j RECONNECT option is used, always specify -T with an idle timeout value. If -T is not specified and the connection is suspended, JSH does not automatically terminate the session. The session never terminates if a client abnormally ends the session.
If a parameter is not specified, the default is no timeout. (Optional)
[-w JSH]
This command-line option indicates the Jolt Server Handler. Default is JSH. (Optional)
[-x mpx-factor]
This is the number of clients that one JSH can service. Use this parameter to control the degree of multiplexing within each JSH process. If specified, this parameter takes a value from 1 to 32767 for UNIX and Windows 2003. Default value is 10. (Optional)
[-Z 0|56|128|256]
When a network link between a Jolt client and the JSH is being established, this option allows encryption up to the specified level. The initial 0 means no DH nodes, no RC4. The numbers 56, 128, and 256 specify the length (in bits) of the encryption key. The DH key exchange is needed to generate keys. Session keys are not transmitted over the network. The default value is 0.

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.

Notes: 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.
Note: Tuxedo 10 supports SSL for Jolt clients and the JSL/JSH; however, SSL support has not been implemented for the JRAD and JRLY. Therefore, Tuxedo 10 Jolt configurations using SSL cannot make use of the JRAD and JRLY processes.
Figure 3-3 Jolt Internet Relay Path

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

Table 3-3 JRLY Command-line Options for Windows 2003 
Option
Description
jrly -install [display_suffix]
Install jrly as a Windows 2003 service.
Example 1:
jrly -install
In this example, the default JRLY is installed as a Windows 2003 Service and is displayed in the Service Control Manager (SCM) as Jolt Relay.
Example 2:
jrly -install MASTER
In this case, an instance of JRLY is installed as a Windows 2003 Service and is displayed in the SCM as Jolt Relay_MASTER. The suffix, MASTER, does not have any significance; it is only used to uniquely identify various instances of JRLYs.
At this point, this instance of JRLY is not ready to start. It must be assigned the configuration file (see the set command discussion) that specifies the listening TCP/IP port, JSH connection TCP/IP port, log files, and sockettimeout. This file should not be shared between various instances of JRLY.
jrly -remove [display_suffix] | -all
Remove one or all instances of JRLY from Windows 2003 service.
If [display_suffix] is specified, this command removes the specified JRLY service.
If [display_suffix] is not specified, this command removes the default JRLY from being a Windows 2003 Service.
If the -all option is specified, all JRLY Windows 2003 Services are removed. Related Windows 2003 registry entries under
HKEY_LOCAL_MACHINE\System\
CurrentControlSet\Services\Oracle JoltRelay
and
HKEY_LOCAL_MACHINE\Software\
Oracle Systems\Jolt\x.x
are removed.
jrly -set
[-d
display_suffix] -f config_file
Update the registry with the full path of a new configuration file.
Example 1:
jrly -set -f c:\tux71\udataobj\jolt\jrly.con
In this example, the default JRLY Windows 2003 Service (Jolt Relay) is assigned a configuration file called jrly.con that is located in: c:\tuxdir\udataobj\jolt directory.
Example 2:
jrly -set -d MASTER -f c:\tuxdir\udataobj\jolt\master.con
Here, the JRLY Windows 2003 Service instance, called Jolt Relay_MASTER is assigned a configuration file called jrly_master.con that is located in c:\tuxdir\udataobj\jolt directory.
jrly -manual [display_suffix]
Set the start/stop to manual.
This command sets the specified JRLY instance to be manually controlled, using either the command-line options or the SCM.
jrly -auto [display_suffix]
Set the start/stop to automatic.
This command sets all the operations for a specified Windows 2003 Service to be automatically started when the OS boots and stopped when the OS shuts down.
jrly -start [display_suffix]
Start the specified JRLY.
jrly -stop [display_suffix]
Stop the specified JRLY.
jryl -version
Print the current version of JRLY binary.
jrly -help
Print command-line options with brief descriptions.

JRLY Command-line Option for UNIX

There is only one JRLY command-line option for UNIX as shown in Table 3-4:

Table 3-4 JRLY Command-line Option for UNIX
Option
Description
jrly -f config_file_path
Start the JRLY process.
This option starts the JRLY process. If the configuration file does not exist or cannot be opened, the JRLY prints an error message. If the JRLY cannot start, it writes a message to standard error, attempts to log the startup failure in the error log, then exits.

JRLY Configuration File

The format of the configuration file is a TAG=VALUE format. Blank lines or lines starting with a “#” are ignored. Listing 3-3 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.

Listing 3-4 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 Table 3-5.

Note: JRLY supports IPv6.

Table 3-5 Host Name and Port Number Formats
IPv4
IPv6
//IP:port
IP is a dotted notation IP address, port is a decimal number
//[IPv6 address]:port
//hostname:port_number
IP is a dotted notation IP address, port is a decimal number
//hostname:port_number
//#.#.#.#:port_number
Hex format is not supported

 


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.

Table 3-6 contains additional information about the CLOPT parameters.

Table 3-6 JRAD CLOPT Parameter Descriptions 
CLOPT Parameter
Description
-l netaddr
Port to listen for the JRLY to connect on behalf of the client.
  • IPv4
  • //IP:port

    //hostname:port_number

    //#.#.#.#:port_number

    The domain finds an address for hostname by using the local name resolution facilities (usually DNS). hostname must be the local machine, and the local name resolution facilities must unambiguously resolve hostname to the address of the local machine.

    In the second example, the “#.#.#.#” is in dotted decimal format. In dotted decimal format, each # should be a number from 0 to 255. This dotted decimal number represents the IP address of the local machine. In both of the above formats, port_number is the TCP port number at which the domain process listens for incoming requests. port_number can either be a number between 0 and 65535 or a name.

  • IPv6
  • //[IPv6 address]:port

    //hostname:port_number

    Note: IPv6 does not support hexadecimal format.

-c netaddr
The address of the corresponding JSL to which JRAD connects.
Ipv4 and IPv6 address format same as -l netaddr.
-H netaddr
The listening address for an external proxy. An external proxy is one that runs on a client host. This proxy handles HTTP and other protocols. The other end of the proxy connects to JRLY, which connects to JSL/JSH.
In order for the proxy to work for Jolt clients (specifically applets that connect to JRLY), the JRAD passes the -H argument to an applet, instructing it to connect to the proxy address instead of the JRLY address.

Note: Unlike the JSL -H option, the JRAD -H option is not used as a network address translator, nor is it used as an address mask. IPv6 does not support the JRAD -H option.

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 shows the sample JRAD entry in UBBCONFIG file.

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 Table 3-7 and record the information to minimize the possibility of misconfiguration.

Table 3-7 Jolt Internet Relay Network Address Configuration Criteria
JRLY
JRAD
JSL
LISTEN: Location where the clients connect.
CONNECT: Location of your JRAD. Must match the -l parameter of JRAD.
-l: Location where the listener connects to the JRLY.
-c: Location of JSL. Must match -n parameter of JSL.
-n: Location of JSL. Must match -c parameter of JRAD.

 


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

Table 3-8 UBBCONFIG File
Section
Parameters to be specified
GROUPS
LMID, GRPNO
SERVERS
SRVGRP, SRVID

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.

  1. Specify the same identifiers given as the value of the LMID parameter in the MACHINES section.
  2. 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.

  1. Indicate a new server identification (for example, 98) with the SRVID parameter.
  2. Specify the -W flag for one JREPSVR to ensure that you can edit the Repository. The Repository is read-only without this flag.
  3. 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.
  4. Type the -P flag to specify the path of the repository file. An error message is displayed in the Oracle Tuxedo ULOG file if the argument for the -P flag is not entered.
  5. Add the file pathname of the repository file (for example, /app/jrepository).
  6. Boot the Oracle Tuxedo system using the tmloadcf command (for example, tmloadcf -y ubbconfig) and tmboot command. See Administering an Oracle Tuxedo Application at Run Time for information about tmloadcf and tmboot.

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.

Note: If you are upgrading from version 1.x of Oracle 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 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:
Jolt Internet Relay Path
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.

  1. Build the Oracle Tuxedo server containing the service. See Administering an Oracle Tuxedo Application at Run Time or Programming Oracle Tuxedo ATMI Applications Using C for additional information on the following:
    • Building the Oracle Tuxedo application server
    • Editing the UBBCONFIG file
    • Updating the TUXCONFIG file
    • Administering the tmboot command
  2. Access the Oracle 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 Oracle Tuxedo services or other Oracle Tuxedo clients:

Configuring for Event Subscription

Configure the Oracle Tuxedo TMUSREVT server and modify the application UBBCONFIG file. Listing 3-7 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.

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

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

Buffer Types

Table 3-9 shows the Oracle Tuxedo 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:

  1. Copy the my.flds file to /usr/me/bankapp directory.
  2. Add my.flds to the FIELDTBLS variable in the TMUSREVT.ENV file as shown in the following listing:
  3. 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 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.

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 Oracle Tuxedo configuration, refer to Administering an Oracle Tuxedo Application at Run Time.

Listing 3-9 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 Table 3-10.

Table 3-10 UBBCONFIG File Sections
Section
Parameters to be specified
MACHINES
MAXWSCLIENTS
GROUPS
GRPNO, LMID
SERVERS
SRVGRP, SRVID, CLOPT

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.

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:

  1. The group name is selected by the application, for example: JSLGRP and JREPGRP.
  2. Specify the same identifiers given as the value of the LMID parameter in the MACHINES section.
  3. 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. 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.

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

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

  1. To identify the SRVGRP parameter, type the previously defined group name value from the GROUPS section.
  2. To indicate the SRVID, type a number between 1 and 30,000 that identifies the server within its group.
  3. Verify that the syntax for the CLOPT parameter is as follows:
  4. 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.
  5. 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 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:


  Back to Top       Previous  Next