| JetNet/Oracle Tuxedo Guide | |
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 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:
devserv—Available only in development environments (and in applications running reports remotely), file access servers offer shared access to libraries and repositories across the network. You can use this server to facilitate development of both two-tier and three-tier applications.
prodserv—(UNIX only) Identical to proserv with the Panther debugger linked in, you can run a server in debug mode if the server definition specifies this executable and specifies Debug (refer to page 3-23).
Note:
On UNIX, the distributed server executables have the JDB database linked in. To run a server with another database, you must recompile the executable. For information on building executables, refer to Chapter 42, "Building Application Executables," in Application Development Guide.
The distribution provides three application libraries in the Application Libraries
samples/newapp directory which you should copy to your application directory:
common.lib stores application-wide objects such as JIF and JPL modules.
Specify to open these libraries by setting the application variable A machine environment file 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.
SMFLIBS in the environment file of the host machine or in the standard server's environment file proserv.env:
Environment Files
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.
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.
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>
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.
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.
A machine environment file should contain these settings:
UNIX: Windows: ${APPDIR}:${SMBASE}/bin:/bin:${SMBASE}/util
${APPDIR};${SMBASE}\bin;${SMBASE}\util
PATH is set to ${APPDIR}:${SMBASE}/bin:/bin:path, where path is the value of the environment file's last PATH= entry.
LD_LIBRARY_PATH must be set to Motif shared libraries and the DISPLAY environment to the display on which debugging takes place.
Setting where lib is the value of the environment file's last
Note:
On HPUX, use LD_LIBRARY_PATH in the environment file adds to the previously established setting:
APPDIR:${SMBASE}/lib:/lib:/usr/lib:lib
LD_LIBRARY_PATH= entry.
SHLIB_PATH in place of LD_LIBRARY_PATH; on AIX, use LIBPATH.
SMFLIBS is not set in the machine environment file, it must be set for each server individually in its server environment file, and for native clients through the client's setup file (in UNIX) or initialization file (Windows).
SMPATH entry, make sure that the path includes the config directory.
For example, the following entry in a machine environment file ensures that servers on this host have access to files in the UNIX: Windows:
Note:
The path to the application directory is set in the machine's configuration through its Application Directory property (page 3-14). myapps and config directories as well as in the application directory:
SMPATH=/u/myapps|${SMBASE}/config
SMPATH=c:\myapps|${SMBASE}\config
SMPATH must not include the same directory again.
A server environment file should contain these settings:
Server Environment File
proserv.env, set SMFLIBS to server.lib and common.lib so these libraries open at application startup:
SMFLIBS=server.lib|common.lib
progserv.env to the service component library created by the upgrade utility clnt2svr:
SMFLIBS=sv.lib
SMPATH entry, make sure that the path includes the config directory.
Note:
Because a server's application directory is already set through its machine's configuration (page 3-14), SMPATH must not include the same directory again.
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 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 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.
Interfacing with SCCS/PVCS
devserv by changing it to be owned by root and setting the suid bit.
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
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 Each type of client has its environment set differently, as described in the following sections.
Each workstation client's environment must be set up in two ways:
broker.bin.
Workstation Clients
Access to application libraries— Setting Access to 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:
SMFLIBS on each workstation as follows:
host is the server machine on which these libraries reside. For example, the following SMFLIBS=host!client.lib|host!common.lib|host!server.lib
SMFLIBS setting specifies that all application libraries are located on host aspen:
SMFLIBS=aspen!client.lib|aspen!common.lib|aspen!server.lib
SMFLIBS can remain as set in the default distribution. For example:
SMFLIBS=client.lib|common.lib|server.lib
SMFLIBS= server_id!lib_name. If a client library cannot be placed on a shared file system, connect to the middleware on application startup using client_init and execute the Panther library function sm_l_open to open a remote library.
For Windows workstations,
Note:
Make sure that, during development, To establish a workstation client connection, two conditions must be true:
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.
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
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:
Given these settings, the workstation client initially tries to connect to Set SMRBHOST=aspen,marks,sparks
SMRBPORT=37000,37100
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.
SMRBHOST and SMRBPORT in one or more of the following initialization files:
jetman32.ini.
For more information about setting Native clients use the value in SMRBCONFIG to establish their connection to the middleware. Make sure that the client machine's If the client resides on a UNIX machine, its environment must have the SMRBHOST and SMRBCONFIG, refer to the Configuration.
Native Clients
SMRBCONFIG matches the value specified for the machine's local configuration file (refer to page 3-14).
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.
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.
MSGMNI
MSGMAP
MSGMNI.
MSGMAX
MSGNB is sent via file transfer.
MSGMNB
MSGMAX.
MSGSSZ
MSGTQL
MSGSEG
MSGSSZ should be less than or equal to 128K for most platforms. Refer to your UNIX documentation for more information.
TUXIPC_MSG_BYTES
TUXIPC_MSG_HDRS
TUXIPC_MSG_QUEUE_BYTES
TUXIPC_MSG_QUEUES
TUXIPC_MSG_SEG_BYTES
TUXIPC_MSG_SEGS
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:
SEMMNS
SEMMNI
SEMMSL
SEMMSL should be set to the total number of accessors divided by eight. It is common for SEMMNS to equal SEMMSL * SEMMNI.
SEMMAP
SEMMNS.
SEMMNU
SEMUME
SEMMNS.
TUXIPC_SEM
TUXIPC_SEM_IDS
TUXIPC_SEM_UNDO
SHMAX
SHMSEG
SHMMNI
TUXIPC_SHM_PROCS
TUXIPC_SHM_SEGS