The WLE (C++) product is a sophisticated software product; it should not be installed without proper planning.
This chapter discusses the following topics:
When you open your WLE software box, you will find the following:
Checking Your Package
If you also have a license for the BEA Administration Console, that package is enabled automatically when the license file is installed.
For a list of the platforms supported for this release of the WLE software, see Appendix A, "WLE (C++) Platform Data Sheets," and Appendix B, "WLE (Java) Platform Data Sheets."
The WLE (C++) software CD contains the following components:
WLE (C++) Software Components
The installation program offers the following options:
The BEA Administration Console is a graphical user interface that enables you to perform most administrative tasks for WLE and BEA TUXEDO applications. This option can be installed only with the WLE (C++) Full System software or on machines that already have the full system software installed.
Note:
For information about how to start up this console after it is installed, refer to Chapter 4, "BEA Administration Console Startup." For information about how to use this console, refer to the online help that is accessible through the console's Help button.
The WLE (C++) software must be installed on each machine that will run a WLE client or server application.
Note:
Do not try to share the WLE (C++) executables across remote file systems; this practice has proven to be unreliable.
The BEA Administration Console must be installed in a file system that supports long file names (that is, those containing more than 14 characters).
For details about the hardware and software prerequisites for all platforms on which the WLE (C++) software is supported, see Appendix A, "WLE (C++) Platform Data Sheets." Check the data sheet for each platform on which you plan to install the WLE (C++) software.
You need the following information and resources before installing the WLE (C++) software on a UNIX system:
Hardware and Software Prerequisites for the WLE (C++) Software
For UNIX Systems
You need the following resources before installing the WLE (C++) software on a Microsoft Windows system:
For Microsoft Windows NT, 95, and 98 Systems
This section explains how to assign ownership of the WLE system files to the system administrator, and how to set up your disk to accommodate those files.
If you are installing the WLE (C++) software on a UNIX system, we strongly recommend that you create a separate user account for the WLE system administrator and give ownership of the WLE system files to that account.
A running WLE client or server application needs disk space for system files and for the application's database(s). You do not use this space until you begin to develop or run your WLE client or server application, but it is important to plan for this space before installing the software. To help explain what is involved, the following sections describe how the WLE system handles files.
The WLE system has a facility, the Disk Management Interface (DMI), that manages logical files within a single disk device or set of devices. Among other things, the DMI stores binary configuration tables and the transaction log.
The WLE disk management software supports the notion of a WLE file system distinct from any operating system file system. (For the remainder of this discussion, the term OS file system is used to refer to any operating system file system.)
Administrative access to the DMI to create, initialize, or destroy entries in the WLE file system is through tmadmin administrative commands.
There are two ways to physically store the logical files managed by the DMI: physical storage can be on an OS file system, and alternatively, disk space outside the control of all OS file systems can be set aside for the WLE system.
Files reside on special device files in that disk space and the DMI manages the files directly. Space outside the OS file system is usually referred to as raw disk space. Not only is I/O faster when done by system calls reading directly from and writing directly to device special files on raw disks, raw disk space is preferred when it is important to know for certain that a physical write() has been done.
With the OS file system, the precise moment at which a write() is done cannot be relied upon. In the WLE system, accurate control of the write operation is particularly important for entries in the transaction log. With multiple users, control of the write operation is also an important element in assuring database consistency.
If you decide to use raw disk space for your WLE client or server application, you may find that the hard disk devices on your machine are fully allocated to file systems such as /(root), /usr, and other UNIX file systems. If that is the case, it is necessary to repartition your hard disk device to set aside some partitions that are not to be used for an OS file system. Information on how to do this can be found in the system administration documentation for your particular platform.
Note:
On Microsoft Windows NT platforms, the default behavior is unbuffered I/O; no special arrangements are needed.
A WLE file system has a Volume Table of Contents (VTOC) that lists files on a set of devices named in the Universal Device List (UDL). The UDL contains information about the location of the physical storage space for the WLE tables.
In a WLE system, all the system files might be stored together on the same raw disk slice or OS file system file. While it is possible to use regular OS file system files for the configuration tables, it is strongly recommended that the transaction log ( Listing 1-1 shows approximately how the content might appear.
Managing Files and Databases
Assigning File Ownership on UNIX Systems
Allocating Disk Space
The WLE System Disk Management Interface
Arranging for Raw Disk Space
How the WLE File System Is Organized
All System Tables on the Same Device?
TLOG) be stored on a raw disk device. Because the TLOG seldom needs to be larger than 100 blocks and because disk partitions are always substantially larger than 100 blocks, it may make sense to use the same device for everything. The pathname of the device needs to be contained in both the TUXCONFIG and the FSCONFIG environment variables.
Listing 1-1
VTOC and UDL Diagram
Output based on setting FSCONFIG=$TUXCONFIG, and invoking tmadmin:
No bulletin board exists. Entering boot mode.
> livtoc
Volume Table of Contents on /usr2/bank/tuxconfig:
0: VTOC: Device 0 Offset 0 Pages 7
1: UDL: Device 0 Offset 7 Pages 28
2: _RESOURCE_SECT: Device 0 Offset 35 Pages 3
3: _MACHINES_SECT: Device 0 Offset 38 Pages 40
4: _GROUPS_SECT: Device 0 Offset 78 Pages 40
5: _SERVERS_SECT: Device 0 Offset 118 Pages 40
6: _SERVICES_SECT: Device 0 Offset 158 Pages 20
7: _ROUTING_SECT: Device 0 Offset 178 Pages 100
8: _NETWORK_SECT: Device 0 Offset 278 Pages 20
9: _MIBPERMS_SECT: Device 0 Offset 298 Pages 2
# If the TLOG is stored on the same device, there will be an
# entry something like:
9: TLOG1: Device 0 Offset 236 Pages 100
> q
The WLE system administrator must ensure that raw disk slices are available, as needed, on each machine participating in a WLE domain. The size of entities in the WLE file system are shown in Table 1-1.
| Entity | 512-byte Pages |
|---|---|
|
VTOC |
1 |
|
TUXCONFIG |
270 |
|
TLOG |
100 (default) |
|
UDL |
28 |
|
TOTAL |
399 |
The size of the TUXCONFIG file is larger if there are more entries in the configuration file (UBBCONFIG). The administrator is encouraged to allocate additional space for dynamic reconfiguration and for growth of the application. The default size assumed by the crdl subcommand of tmadmin is 1000 blocks, which should be adequate for the initial installation.
If your WLE server application is using the BEA TUXEDO system/D as a resource manager, your database tables can be listed in the same UDL and can be managed by the WLE VTOC. If another resource manager is used, you should check the installation instructions for that product to see how its space requirements affect your WLE system planning.
If your WLE application is using the BEA TUXEDO system/Q for store-and-forward queue management, your queue space can be listed in the same UDL and can be managed by the WLE VTOC.
As you are calculating the space requirements for the WLE system, also consider the requirements of the server machines that perform the work of the server application. These requirements are specified by the application, and they are in addition to the requirements for the WLE system itself (unless otherwise specified).
During the installation process, you are prompted to make decisions about where, in your file system, a number of your WLE directories and files are installed. To help you plan for this part of the process, this section describes the directories and files about which you are prompted to make a decision, as follows:
You are prompted for a pathname for the base directory of your WLE software. There is no restriction on the location of this directory, as long as it meets the following requirements:
For All Platforms
Throughout the WLE documentation this directory is referred to as WLEDIR.
If you are installing the WLE (C++) software on a server machine, and you elect to install the BEA Administration Console for system administration, you are prompted, during the installation process, to accept or replace the default pathnames and file names used for the BEA Administration Console components. These default pathnames and file names are based on the value of WLEDIR that you specify.
If you are running a commercial Web server, you may find the default settings inappropriate, especially if your server is handling requests from both the BEA Administration Console and other Web programs on the same port. To accommodate this situation, the WLE software enables you to choose between accepting the defaults and assigning your own pathnames and file names. The remainder of this section describes the choices you are given, as follows:
For All Server Platforms Supporting the BEA Administration Console
\cgi-bin on Microsoft Windows NT systems and WLEDIR/udataobj/webgui/cgi-bin on UNIX systems
Exception: If the installation program detects the Microsoft Internet Information Server (IIS) in a standard directory, tuxadm is installed in a subdirectory called scripts in the directory you specified in step 1 as the pathname for the HTML files.
Note:
Do not specify WLEDIR/bin (for UNIX systems) or WLEDIR\bin (for Microsoft Windows NT systems) as your CGI directory. If you do, you risk having other WLE client or server applications executed accidentally by an uninformed user of the BEA Administration Console. You may also introduce a security risk.
\cgi-bin or \scripts (for Microsoft
Windows NT systems).
The WLE system uses an administrative password to protect the machine on which it is installed from unauthorized administrative requests and operations (such as tmboot). Whenever administrative communications arrive on this machine through the tlisten and wlisten processes, the WLE system authenticates the communications by means of the password.
You assign an administrative password during the installation process (to the machine on which the WLE software is being installed) by entering the password of your choice after the appropriate prompt. The password must be a string of alphanumeric characters in clear-text format. It may contain no more than 80 characters.
A common password is required for two machines in a WLE domain to communicate successfully. For this reason, you must use the same password whenever you install the WLE software on multiple machines for a single domain. As described previously, you are prompted to provide the password during the WLE installation process. If, however, you use a different password for one machine, you must add that password to the tlisten.pw file on each existing machine with which you want that machine to communicate.
For these reasons, you may have more than one administrative password in your tlisten.pw file. A single password file may contain no more than 20 passwords, with one password per line.
The administrative password that you enter during installation is collected by the installation script and is stored in:
WLEDIR/udataobj/tlisten.pw (UNIX systems)WLEDIR\udataobj\tlisten.pw (Microsoft Windows NT systems)
Make sure the permissions on your tlisten.pw file are set such that only the WLE system administrator can read the file.
You cannot configure your WLE (C++) system for Microsoft Windows NT until after you install the WLE (C++) software and license. After you complete the installation as described in Chapter 2, "WLE (C++) Installation on Microsoft Windows NT, 95, and 98 Systems," refer to the section "Configuring the WLE System for Microsoft Windows NT" on page 5-2 for instructions on configuring the WLE (C++) system for Microsoft Windows NT.
The WLE software uses the UNIX operating system Interprocess Communications (IPC) resources.
IPC resources are configured by three sets of tuning parameters that control the amount of shared memory (prefix SHM), number of semaphores (prefix SEM), and size of message queues and messages (prefix MSG).
The settings for these parameters are WLE system dependent. Most UNIX systems, however, are shipped with default values that are too low for WLE systems.
The following sections describe the IPC parameters and provide guidelines for configuring them. Because these parameters vary across different versions of UNIX, the following descriptions are generic. For the exact parameter names, default settings, settings used for the University Sample applications for each platform, and information about how to change the parameters, see Appendix A, "WLE (C++) Platform Data Sheets."
If you change a parameter, you need to rebuild the kernel and reboot the operating system using the standard administrative tools. Consult your operating system administrator or the system administrator's guide for your platform for details.
If your WLE client or server application is distributed, the minimum IPC resources must be available on every UNIX platform participating in the application.
Every process that participates in a WLE system requires a semaphore. When the system boots, the number of semaphores configured in the operating system is checked, and the boot fails if the configured number is not high enough.
The following semaphore parameters may need to be adjusted:
MAXACCESSERS - MAXWSCLIENTS + 13
WLE client and server applications use UNIX messages and message queues for client/server communication. Examples of such messages are service requests, service replies, conversational messages, unsolicited notification messages, administrative messages, and transaction control messages.
Every Multiple Servers, Single Queue (MSSQ) set of servers, and every individual server has a message queue for receiving requests. Every client has its own queue for receiving replies. Servers that specify the REPLYQ parameter also get individual reply queues.
The adjustment of kernel message parameters is important to the proper tuning of the WLE system. Inappropriate values can lead to an inability to boot or to severe performance degradation.
There are various message queue parameters. They limit various characteristics of the queue space, including the total number of outstanding messages (MSGTQL), the total number of bytes that can be on one queue (MSGMNB), the size limit of an individual message (MSGMAX), the total number of message segments that can be outstanding at one time (MSGSEG), and the size of each segment (MSGSSZ).
Exceeding any of the parameter limits described previously results in what is known as a blocking condition. There is a special case for MSGMAX. Messages that exceed 75 percent of MSGMNB, or that are larger than MSGMAX, are placed in a UNIX file. A very small message with the file name in it is then sent to the recipient. Avoid this mode of operation, because it results in a severe reduction in performance.
An application deadlock can result if every process is blocked when it tries to send a message. For example, when client applications fill the message space with requests, and server applications are all blocked when they try to send replies, because no server application can read a message, there is a deadlock. Timeouts can sometimes break the deadlock, but no useful work will have been done.
Especially troublesome is a client application that sends its requests with the TPNOREPLY flag. This practice can fill either individual queues or the system message space, depending on the size of the messages. Such applications may have to implement their own flow control to limit the number of outstanding messages.
To summarize, if client applications or server applications are blocking on their send operations (that is, requesting services or sending replies), there is potential for trouble. It is usually no problem, though, for a single server request queue to always be full, as long as there is space in the system for more messages on other queues.
There are performance implications to queue blocking conditions, both on the sending side and the receiving side. The UNIX operating system, when waking up blocked processes, wakes up all the processes blocked on a particular event, even if only one can proceed. The other processes go back to sleep. This process scheduling overhead can be expensive.
For example, on an empty server request queue where there is more than one server application (that is, MSSQ), an arriving message wakes up all the idle, or blocked, server applications on that queue. In the case of a full server request queue, as each request is read by a server application, the system wakes up all the blocked clients. Depending on the size of the messages, zero or more clients are allowed to place their messages on the queue. The remainder of the clients have to go back to sleep. Because there may be hundreds of clients in the system, the mass wakeup of all of these clients every time a service request is processed can severely degrade performance.
A properly tuned system rarely fills its queues. Enough slack should be left in the queues to handle the natural variability of the message flow. No exact settings can be recommended. Tuning is very system dependent. The UNIX ipcs(1) command provides a snapshot of the queues so you can tell whether they are full. You can try the TPNOBLOCK flag when sending requests. That way, clients can tell when queues are full, and they can slow down a bit. It might help to increase the scheduling priority of the servers whose request queues are full.
The following message parameters may need to be adjusted:
MSGMNI = MAXACCESSERS + 7
+ (number of servers with REPLYQ)
+ (number of MSSQ sets)
- (number of servers in MSSQ sets)
In the WLE environment, shared memory is used for the Bulletin Board and for the control table of the IIOP Server Listener. An application also may choose to use shared memory for its own purposes.
The following shared memory parameters may need to be adjusted:
Experience with WLE (C++) systems has shown that some other UNIX tuning parameters may need to be set to higher values. The settings are dependent on the application and do not apply to all applications.
ULIMIT
NOFILES
MAXUP
NPROC
NREGION
NUMTIM
NUMTIM to at least 256.
NUMTRW
NUMTRW to at least 256.
When the WLE (C++) software has been installed and an application configuration file (UBBCONFIG file) is available, the tmloadcf command can be used to calculate the IPC resources needed to support the application. For more information, see the tmloadcf(1) reference page in the BEA TUXEDO Reference and the section "Verifying IPC Requirements" on page 5-17.