JetNet/Oracle Tuxedo Guide


Chapter 2. Setting the Enterprise Environment

Panther typically runs in two types of environment: one tailored for development, the other for production. Each environment has different requirements—for example, a development environment is typically configured to offer shared access to libraries and repositories. Despite these differences, setting up a Panther environment for remote processing and access consists of these tasks:

This chapter describes each task in detail; differences between development and production environments are noted where applicable.

For information about setting up a Panther application that is accessible via the web, refer to Chapter 2, "Web Application Setup," in the Web Development Guide.

Note: This chapter assumes that the Panther software is installed (refer to the Installation).


Setting Up the Enterprise Directory

The application directory is the area in a server machine where Panther runs. You must create this directory on each server machine and populate it with the required server executables, application libraries, and environment files.

Server Executables

Server executables are required for shared library access during development and for deploying three-tier applications. Copy or create symbolic links to the required server executables; in the default distribution, these are located in the util directory. Or set PATH to $SMBASE/util in the machine environment files. Panther provides four server executables:

Application Libraries

The distribution provides three application libraries in the samples/newapp directory which you should copy to your application directory:

Specify to open these libraries by setting the application variable SMFLIBS in the environment file of the host machine or in the standard server's environment file proserv.env:

Environment Files

A machine environment file machine.env supplements the environment that is established on machine activation. In addition, two other server environment files are provided for some server types: proserv.env (used by proserv and prodserv servers), and progserv.env (used by progserv). These can be used to supplement the environment for a given server. All files are in the distribution's config directory; copy these to your application directory.

You specify the machine environment file in JetMan through its Machine Environment Variable File property (refer to page 3-14); you can specify an environment file for each server through its Server Environment Variable File property (refer to page 3-21).

For information about environment file settings and format, refer to page 2-4.


Setting the Environment

On activation, all servers on a UNIX master machine inherit the environment of rbboot; servers on a non-master machine inherit the environment of rblisten; a Windows server inherits the environment of the tuxipc service. Each host machine's environment is supplemented by the settings of its environment file machine.env. All servers inherit their host machine's environment. Each server's environment can be further supplemented with the appropriate server environment file: devserv.env, proserv.env, or progserv.env. You must make sure that all necessary environment variables are properly set, either in the machine environment before activation, or through the appropriate environment file.

UNIX Environment

A UNIX host environment must have these variables set before the server is activated:

SMBASE=<root of Panther installation>
PATH=$SMBASE/util:$PATH
LM_LICENSE_FILE=$SMBASE/licenses/license.dat:$LM_LICENSE_FILE
LD_LIBRARY_PATH=$SMBASE/lib:$LD_LIBRARY_PATH

A prodserv server (one that has the debugger linked in) must also set the terminal display with this variable:

SMTERM=<terminal-type mnemonic>

Windows Environment

A Windows server must have these variables set:

SMBASE=<root of Panther installation>
ULOGDIR=<root of Panther installation>
PATH=$SMBASE\util;%PATH%
LM_LICENSE_FILE=%SMBASE%\licenses\license.dat;%LM_LICENSE_FILE%

On the Control Panel under System, check the Environment settings and update them if necessary.

Environment File Settings

On activation, each machine and server reads the environment files that are specified for it in the middleware's configuration file; in the JetNet manager, these files are set in the Machine Environment Variable File (page 3-14) and Server Environment Variable File (page 3-21) properties. Environment file settings supplement the environment that exists when the host and its servers activate.

Note: You cannot use environment files to override the machine settings for the Panther Install Directory, Application Directory, and Local JetNet Configuration File.

Each line in the environment file contains a variable assignment with the format variable =value, where variable starts with an underscore or alphabetic character and contains only underscores or alphanumeric characters. Within the value, strings of the form ${env} are expanded using variables already in the environment. Forward referencing is not supported, and if a value is not set, the variable is replaced with the empty string. Use backslash (\) to escape the dollar sign or another backslash. All other shell quoting and escape mechanisms are ignored.

Machine Environment File

A machine environment file should contain these settings:

Server Environment File

A server environment file should contain these settings:

Interfacing with SCCS/PVCS

When using remote libraries that are under SCCS/PVCS control, files are checked out of the library under the name of the user who started the application rather than the client who made the request. This makes it appear as if all work is performed by a single user, and is probably not desirable.

To workaround for this on UNIX, the check-in/check-out daemon must be able to pretend to be any user. You may achieve this using our devserv by changing it to be owned by root and setting the suid bit.

If this is not possible in your configuration, or presents too much risk, there is an alternate solution. The Panther software contains an alternate check-in/check-out daemon, named cfgserv. It, too, must be owned by root and have the suid bit set, but you can eliminate the security risks by running devserv under a dedicated group id and making cfgserv executable only by that group.

cfgserv is located in $SMBASE/util; the source code is located in $SMBASE/link.

SMVARS Settings

You can test an application with the Panther debugger by running it directly on the server. To do so, the server's SMVARS file must set configuration variables SMTERM and SMKEY so that Panther's interacts properly with the terminal's display and keyboard.


Setting Up the Client Environment

Two types of clients can connect to a Panther application: native and workstation clients.

When you create an application using JetMan, the machine name is specified automatically and is then stored as part of the application configuration in broker.bin.

Each type of client has its environment set differently, as described in the following sections.

Workstation Clients

Each workstation client's environment must be set up in two ways:

Setting Access to Libraries

Access to application libraries—client.lib, server.lib, and common.lib—is set through the configuration variable SMFLIBS. You can set SMFLIBS in one of two ways, depending on whether you want to provide shared access to these libraries:

For Windows workstations, SMFLIBS must be set in the initialization file: prol5w32.ini for Panther, mbedit32.ini or mbedit.ini for the menu bar editor, and jifedit32.ini or jifedit.ini for the JIF editor. For UNIX clients, you can set SMFLIBS in the environment, or in the SMVARS or SMSETUP file.

Note: Make sure that, during development, SMFLIBS specifies client libraries before server libraries; if screens in client and server libraries use the same name, this ensures that the client version opens when invoked.

Enabling Client Connections

To establish a workstation client connection, two conditions must be true:

Two Panther configuration variables, SMRBHOST and SMRBPORT, let you specify the network addresses of one or more server machines. For example, you might set the two variables as follows:

SMRBHOST=aspen,marks,sparks
SMRBPORT=37000,37100

Given these settings, the workstation client initially tries to connect to aspen at port 37000; if unable to connect to aspen, it next tries to connect to marks at port 37100. Failing both connections, it tries sparks at port 37100.

Set SMRBHOST and SMRBPORT in one or more of the following initialization files:

For more information about setting SMRBHOST and SMRBCONFIG, refer to the Configuration.

Native Clients

Native clients use the value in SMRBCONFIG to establish their connection to the middleware. Make sure that the client machine's SMRBCONFIG matches the value specified for the machine's local configuration file (refer to page 3-14).

If the client resides on a UNIX machine, its environment must have the LD_LIBRARY_PATH variable (or its equivalent) set to the required JetNet or Oracle Tuxedo libraries.


Middleware Configuration File

A middleware configuration file is required to develop and deploy three-tier applications; it is also required for shared library access in a development environment. This file contains all the information that the middleware requires to provide server access: which machines are configured for servers, the types of servers that are available, network settings that enable workstation client connections, and so on. Panther has its own utilities for creating and editing a configuration file for the JetNet middleware. You can create a minimal JetNet configuration file through the utility rbconfig; you can also create and edit JetNet configuration files through the JetNet manager (page 3-1).

An application using the Oracle Tuxedo middleware adapter can be run with a JetNet configuration file. You can also use Oracle Tuxedo utilities to create and edit a Oracle Tuxedo configuration file.

Warning: A configuration file that is created with Oracle Tuxedo utilities must be used only with the Oracle Tuxedo middleware adapter.

You specify the location of the middleware configuration file through the configuration variable SMRBCONFIG.


Setting IPC Resources

After you install Panther and before you start development, you might need to adjust resource settings for the IPC (interprocess communication) subsystem in your UNIX kernel or Windows registry.

On UNIX, you set IPC resources in the system kernel. You can check the status of resources using the UNIX command ipcs.

On Windows, the Panther installation adds entries to the registry and adds an Windows service to the system. This allows JetNet features to work with the embedded Oracle Tuxedo software. Registry entries can be edited in order to facilitate system management and debugging.

Registry entries are added under this layout:

HKEY_LOCAL_MACHINES\System/CurrentControlSet
Control\Session Manager\Environment
Services\TUXEDO IPC HELPER
Enum\Root\LEGACY_TUXEDO IPC HELPER
HKEY_LOCAL_MACHINE\Software\ORACLE\TUXEDO\6.3
Environment
Security

You can view the Oracle Tuxedo IPC HELPER service via from the Services applet, invoked from the Control Panel. This applet lets you perform tasks such as starting or stopping the service.

You must stop the Oracle Tuxedo IPC HELPER service before you uninstall the Panther application server; otherwise, the service and its DLLs are still available after server deinstallation.

The following sections describe IPC resources for message queues, semaphores, and shared memory. The descriptions include default values; these are usually adequate for most Panther applications unless otherwise indicated.

Messages

Panther uses messages and message queues to transfer data between clients and servers. All instances of a server share a single message request queue, while each client has its own response queue. Individual server instances each get their own reply queues if the server's Enable Service Calls property (in the JetNet configuration file) is set to Yes. If the limits set by message parameters are exceeded, additional server instances and clients cannot start or a blocking condition occurs. If all attempts to send messages by processes are blocked, application deadlock occurs.

UNIX

MSGMNI
Specifies the number of unique message queue identifiers. The default is 50, which may be too low. To calculate the correct value, count one queue per process, including one for each BBL and the DBBL, one for each client and server, and two for each bridge process. If a server's Enable Service Calls property (in the JetNet configuration file) is set to Yes, also count one queue per server instance.

MSGMAP
Specifies the size of the control map that manages message segments. Set this to twice the value of MSGMNI.

MSGMAX
Specifies the maximum message size in bytes, typically between 16K and 32K. Any message that is larger than 75 percent of MSGNB is sent via file transfer.

MSGMNB
Specifies the maximum message queue length in bytes. This parameter determines the amount of data that can be placed on a message queue at any time. It is typically set to the same value or higher as MSGMAX.

MSGSSZ
Determines the size of a message segment. Each message contains contiguous segments large enough for the message text. A size of 32 is typical.

MSGTQL
Specifies the number of outstanding messages. The default is 40 but should be set higher than 200 for a system with a high volume of traffic.

MSGSEG
Specifies the number of message segments in the system. This value multiplied by MSGSSZ should be less than or equal to 128K for most platforms. Refer to your UNIX documentation for more information.

Windows

TUXIPC_MSG_BYTES
Maximum allowed message size. The default is 65536.

TUXIPC_MSG_HDRS
Maximum number of message headers. The default is 8128.

TUXIPC_MSG_QUEUE_BYTES
Maximum message queue size. The default is 65536.

TUXIPC_MSG_QUEUES
Maximum number of message queues. The default is 256.

TUXIPC_MSG_SEG_BYTES
Size of the message segment. The default is 64.

TUXIPC_MSG_SEGS
Number of message segments. The default is 32767.

Semaphores

Each process that attaches itself to a bulletin board acquires a semaphore, which are means of passing flags from process to process. Semaphores can be tuned by the following parameters:

UNIX

SEMMNS
Specifies the maximum number of semaphores in use in the system. The default for most UNIX System V implementations is 60. Check the JetNet configuration file's Max Accessors settings for individual machines (refer to page 3-11).

SEMMNI
Specifies the maximum number of active semaphore sets. The default is 10.

SEMMSL
Specifies the maximum number of semaphores per semaphore set. The default is 25, which should be enough for 200 accessors. Panther will use up to eight sets, so SEMMSL should be set to the total number of accessors divided by eight. It is common for SEMMNS to equal SEMMSL * SEMMNI.

SEMMAP
Specifies the size of the control map used to manage semaphore sets. Set this to the same value as SEMMNS.

SEMMNU
Specifies the number of undo structures in the system. This controls the number of UNIX system processes that attempt to access the bulletin board at the same time. If more than this number try to connect to the bulletin board, a UNIX system error results.

SEMUME
Specifies the maximum number of undo entries per process. Set this to the same value as SEMMNS.

Windows

TUXIPC_SEM
Maximum number of semaphores. The default is 1024.

TUXIPC_SEM_IDS
Maximum number of semaphores set. The default is 1024.

TUXIPC_SEM_UNDO
Maximum number of semaphore undo structures. The default is 1024.

Shared Memory Requirements

UNIX

SHMAX
Specifies the maximum size in bytes of an attached shared memory segment, up to 4194304 (4 megabytes). The default is 524288.

SHMSEG
Specifies the maximum number of shared memory segments that a process can attach to, up to 10. The default is 6.

SHMMNI
Specifies the maximum number of shared memory identifiers in the system. The default is 100.

Windows

TUXIPC_SHM_PROCS
Number of processes per shared memory mappings. The default is 500.

TUXIPC_SHM_SEGS
Number of shared memory segments. The default is 50.