Now that you have successfully installed the WLE (C++) software, you must set up your machine and parts of the WLE (C++) software to prepare for developing or installing your application.
This chapter discusses the following topics:
In addition to the BEA Administration Console, the WLE system provides a control panel applet that you can use to configure the WLE machine for Microsoft Windows NT.
This section describes how to use the applet to do the following:
Configuring the WLE System for Microsoft Windows NT
tlisten processes to start automatically by setting the Listener page
To access the control panel applet, proceed as follows:
Accessing the Control Panel Applet
To display the Machines page of the Control Panel, click on the Machine tab.
The Machines Page enables the WLE system administrator to access any machine on the Microsoft Windows Network running Microsoft Windows NT, where the administrator has login privileges. The system administrator can then set environment variables remotely; determine the location of BEA WLE event logging; add, start, or remove tlisten services; and tune IPC resources. To access a remote machine, the administrator locates the machine on a network tree.
If you know a machine's name, but not its work group, proceed as follows:
All subsequent actions on other folders in the control panel applet take place on the selected machine.
To display the Environment Page of the Control Panel, click the Environment tab.
Modifying WLE environment variables is almost identical to modifying Microsoft Windows NT environment variables. The Variable field (see Figure 5-1) contains a list of the most commonly used WLE environment variables.
To modify the variables, proceed as follows:
Figure 5-1 WLE Software for Microsoft Windows NT Environment Control Panel
To display the Logging page (Figure 5-2) of the Control Panel, click on the Logging tab.
You can set the Logging Page to direct WLE system messages to the Microsoft Windows NT Event Log. You can select the Logging option (Microsoft Windows NT Event Log) or the traditional user log (Disk File), or both. If you want traditional user log (ULOG) messages, select the directory into which ULOG messages will be written, as well as the prefix for the file name. The default prefix is ULOG, and the default file name is ULOG.<mmddyy>.
Figure 5-2 WLE Software for Microsoft Windows NT Logging Control Panel
To view Event Log entries, click Start->Programs->Administrative Tools->Event Viewer. The Event Viewer window is displayed.
To display the Listener page (Figure 5-3) of the Control Panel, click on the Listener tab.
You can configure one or more tlisten processes to start automatically when you boot your machine. To configure tlisten processes, proceed as follows:
tlisten services from the Listener page (see Figure 5-3). You can also use the
Microsoft Windows NT control panel to start or stop a tlisten service or to
configure the service to start automatically.
Figure 5-3 WLE Software for Microsoft Windows NT Listener Control Panel
You can use the tlisten process to perform administrative actions in a server application across multiple machines. You must start the tlisten process on each machine before running the server application. Generally, you need one tlisten process for each server application running on the machine.
To display the IPC Resources page (Figure 5-4) of the Control Panel, click on the IPC Resources tab.
The WLE software for Microsoft Windows NT systems provides you with BEA TUXEDO IPC Helper (TUXIPC), an interprocess communication subsystem, that is installed with the product. On most machines, IPC Helper runs as installed; however, you can use the IPC Resources page of the control panel applet to tune the TUXIPC subsystem and maximize performance.
Figure 5-4 WLE Software for Microsoft Windows NT IPC Resources Control Panel
With the IPC Resources control panel, you can set a variety of IPC resources. To define IPC settings for your WLE machine, proceed as follows:
You can view the performance of a running WLE server application on the NT Performance Monitor (Figure 5-5).
To start the Performance Monitor, click
Start->Programs->Administration Tools->Performance Monitor on the NT taskbar. The Performance Monitor screen is displayed.
Figure 5-5 WLE Software for Microsoft Windows NT Performance Monitor
On a UNIX system, before you can invoke WLE system commands, you need to set several environment variables. The Bourne shell script wle.env, located in the base directory you specified at installation time, serves as a model for setting these variables.
The following examples assume that you are using the Bourne shell:
WLEDIR, enter the following:
TUXDIR=/var/opt/WLEDIR; export TUXDIR
PATH=$PATH:$TUXDIR/bin; export PATH
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$TUXDIR/lib; export
LD_LIBRARY_PATH
Each WLE machine has a configuration file, commonly called the UBBCONFIG file, which specifies the system parameters that are dependent on the installation. Typically, the configuration file has a name that begins with ubb and ends with something mnemonic, such as ubbsimple. Usually, you must edit this file before you can boot the application.
As an example, Listing 5-1 shows the configuration file from the University sample applications. This file, To edit the configuration file for your application, replace the strings provided for the following values:
These values are highlighted as boldface text in Listing 5-1, "University Samples UBBCONFIG File," on page 5-15. The values you need to provide are as follows:
Editing a UBBCONFIG File
Ubb_b_nt, is delivered with the WLE software and is located in WLEDIR/samples/corba/university (for UNIX systems) or WLEDIR\samples\corba\university (for Microsoft Windows NT systems).
IPCKEYTUXCONFIG
<machine_name>
APPDIR
TUXDIR
IPCKEY
machine_name
APPDIR = string_value
string_value is the absolute pathname of that directory, optionally followed by a colon-separated list of other directory pathnames, on the machine being defined.
TUXCONFIG = string_value
TUXCONFIG is the binary version of the UBBCONFIG file, produced by tmloadcf(1). The string_value is the absolute pathname of the file or device of the TUXCONFIG file.
TUXDIR = string_value
If you need to look up other values when editing your configuration file, the complete syntax can be found on the ubbconfig(5) reference page in the BEA TUXEDO Reference.
Note: The configuration file must be edited before you use the tmloadcf(1) command to verify the IPC requirements; otherwise, the tmloadcf(1) command fails with syntax errors. For instructions on how to determine IPC requirements, see the section "Verifying IPC Requirements" on page 5-17.
Listing 5-1 University Samples UBBCONFIG File
#----------------------------------------------------------------
#
# ubb_b.nt
#
# NT template configuration file for the university sample
# application
#
# Also, check that the value of TUXDIR is correct.
# (this file contains typical values)
#
# For more information on the contents of this file, refer to the # document "Administration Guide"
#
# BEA Systems Inc. sample code
#
#----------------------------------------------------------------
*RESOURCES
IPCKEY 55432DOMAINID university
MASTER SITE1
MODEL SHM
LDBAL N
#----------------------------------------------------------------
*MACHINES
# Specify the name of your server machine
#EIEIOLMID = SITE1
# Pathname of your copy of this sample application.
# Must match "APPDIR" in "setenv.cmd"
#
"APPDIR = d:\wlework\checkin\basic"# Pathname of the tuxconfig file.
# Must match "TUXCONFIG" in "setenv.cmd"
#TUXCONFIG = "d:\wlework\checkin\basic\resultsb\tuxconfig"# Pathname of the WebLogic Enterprise installation.
# Must match "TUXDIR" in "setenv.cmd"
#TUXDIR = "d:\wledir"MAXWSCLIENTS = 10
#----------------------------------------------------------------
*GROUPS
SYS_GRP
LMID = SITE1
GRPNO = 1
ORA_GRP
LMID = SITE1
GRPNO = 2
#----------------------------------------------------------------
*SERVERS
DEFAULT:
RESTART = Y
MAXGEN = 5
# Start the TUXEDO System Event Broker. This event broker must
# be started before any servers providing the NameManager Service
#
TMSYSEVT
SRVGRP = SYS_GRP
SRVID = 1
# TMFFNAME is a BEA WebLogic Enterprise provided server that
# runs the
# object-transactional management services. This includes the
# NameManager and FactoryFinder services.
# The NameManager service is a BEA WebLogic Enterprise-specific
# service that maintains a mapping of application-supplied
# names to object references.
# Start the NameManager Service (-N option). This name manager
# is being started as a Master (-M option).
#
TMFFNAME
SRVGRP = SYS_GRP
SRVID = 2
CLOPT = "-A -- -N -M"
# Start a slave NameManager Service
#
TMFFNAME
SRVGRP = SYS_GRP
SRVID = 2
CLOPT = "-A -- -N"
# Start the FactoryFinder (-F) service
#
TMFFNAME
SRVGRP = SYS_GRP
SRVID = 3
CLOPT = "-A -- -F"
# Start the IR Server
#
TMIFRSVR
SRVGRP = SYS_GRP
SRVID = 5
# Start the university server
#
univb_server
SRVGRP = ORA_GRP
SRVID = 2
RESTART = N
# Start the listener for IIOP clients
#
# Specify the host name of your server machine as
# well as the port. A typical port number is 2500
#
ISL
SRVGRP = SYS_GRP
SRVID = 6
CLOPT = "-A -- -n //EIEIO:2500"#----------------------------------------------------------------*SERVICES
#----------------------------------------------------------------
The WLE system uses Interprocess Communications (IPC) resources heavily. On many platforms, the default values for the parameters that control the size and quantity of the various IPC resources are below the minimums needed to run even a modest WLE system application. Therefore, you may need to reset some of the parameters. After editing your configuration file, the next step is to determine whether the IPC resources suffice for the application.
To do this, enter the tmloadcf(1) command, specifying your edited configuration file as input:
tmloadcf -cubbconfig
An example of the result for the University samples UBBCONFIG file is shown in Listing 5-2.
Listing 5-2 Output Produced by tmloadcf -c
Ipc sizing (minimum /T values only)...
Fixed Minimums Per Processor
SHMMIN: 1
SHMALL: 1
SEMMAP: SEMMNI
Variable Minimums Per Processor
SEMUME, A SHMMAX
SEMMNU, * *
Node SEMMNS SEMMSL SEMMSL SEMMNI MSGMNI MSGMAP SHMSEG
------ ------ ------ ------ ------ ------ ------ ------
sftuxe 65 8 60 A + 1 28 56 403k
where 1 <= A <= 8.
The number of expected application clients per processor should be added to each MSGMNI value.
This output indicates that to run the University sample application, your system must have SEMUME, SEMMNU, and SEMMNS set to no less than 65. SEMMSL must be at least 8, and SEMMNI and SEMMAP must be at least 4 (assuming A is 3). MSGMNI must be at least 28, and MSGMAP must be at least 56. Finally, the product of SHMMAX and SHMSEG must be at least 403K bytes.
The IPC values are dependent on the client or server application, and the numbers in this example reflect a very small configuration. If other client or server applications that use IPC resources are running on the same machine with a WLE client or server application, the requirements of both applications must be satisfied. Also, every machine participating in an application must have sufficient IPC resources available.
If the current IPC resources are inadequate, you must increase the values of the associated IPC parameters. Additional information is available at these locations:
The Universal Device List (UDL) is like a map of the WLE file system. It is loaded into shared memory when the application is booted. The TLOG refers to a log in which information on transactions is kept until the transaction is completed.
To create the UDL, enter the following command before the application has been booted:
where -z
Note:
In general, the value that you supply for blocks should not be less than the value for Several parameters in the To create an entry in the UDL for the When used in a distributed environment, the WLE system requires the capability to start, shut down, and administer processes on remote machines running WLE servers. The tlisten(1) process provides this facility. Once tlisten is running, tmboot(1), for example, can start WLE servers on remote machines.
The tlisten process is a generic listener process that operates with either of the two network interfaces: Sockets or TLI. It runs as a daemon process, and it can be started in several ways, as follows:
Creating the Universal Device List and TLOG
Creating the UDL
tmadmin -c
crdl -z config -b blocksconfig specifies the full pathname for the device where the UDL should be created and -b blocks specifies the number of blocks to be allocated on the device. The value of config should match the value of the TLOGDEVICE parameter in the MACHINES section of the UBBCONFIG file.
TLOGSIZE. For example, if TLOGSIZE is specified as 200 blocks, specifying -b 500 would not cause a degradation.
Creating the TLOG
MACHINES section of the UBBCONFIG file are used to define a global transaction log (TLOG). The WLE system administrator must manually create the device list entry for the TLOGDEVICE on each machine where a TLOG is needed. The device list entry can be created either before or after TUXCONFIG has been loaded, but it must be done before the machine is booted.
TLOGDEVICE, create the UDL as described previously on each machine that will be involved with global transactions. If the TLOGDEVICE is mirrored between two machines, it is not necessary to create an entry on the paired machine. The Bulletin Board Liaison (BBL) then initializes and opens the TLOG during the boot process.
Starting the tlisten Process on UNIX Systems
In all cases, the same basic invocation syntax is used:
Note:
If your machine uses an environment variable other than LD_LIBRARY_PATH for the shared library path, specify that variable, instead.
TheTUXDIR=WLEDIR; export TUXDIR
LD_LIBRARY_PATH=libpath:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH
$TUXDIR/bin/tlisten -d devname -l nlsaddr -u appuid -l option is required. The -d option is not required. The value for -d represents the network device. The correct values for various platforms are shown in Table 5-1.
The value for -l should be the same as that specified for the NLSADDR parameter in the NETWORK section of the configuration file. For information about determining the value of NLSADDR, see the ubbconfig(5) or tlisten(1) reference page in the BEA TUXEDO Reference, or the Administration Guide.
Use the -u appuid option when the command is part of an installation script run by root. The value of appuid is the UID or login name of the WLE system administrator; the numeric version is the same as the value of the UID parameter in the RESOURCES section of the configuration file. Therefore, even though the tlisten process is started by root, it runs with the effective UID of the owner of the WLE installation. If tlisten is started by the WLE system administrator either manually or as a cron job, the -u option is unnecessary, because the job is already owned by the correct account.
The TYPE parameter in the MACHINES section of the UBBCONFIG file specifies the invocation of the XDR (EXternal Data Representation) encode/decode routines when messages are passed between unlike machines. The term unlike applies even to machines of the same type if the compiler on each machine is different. In such a case, give each machine a unique TYPE string to force the message to go through the encode/decode routines.
The BEA Application Builder online help requires an Internet browser. Install a browser that is Y2K compliant, either a Netscape Communicator browser or an Internet Explorer browser.