Managing Files and Databases

This section explains how to assign ownership of the BEA TUXEDO System files to the responsible administrator, and how to set up your disk to accommodate those files.

Assigning File Ownership on UNIX Systems

If you are installing BEA TUXEDO on a UNIX System, we strongly recommend that you create a separate user account for the BEA TUXEDO system administrator and give ownership of the BEA TUXEDO System files to that account.

Allocating Space

A running BEA TUXEDO application needs disk space for system files and for the application's database(s). You won't use this space until you begin to develop or run your BEA TUXEDO application, but it is important to plan for it before installing the software. To help explain what is involved here, we need to describe how the BEA TUXEDO System handles files.

The BEA TUXEDO System Disk Management Interface

The BEA TUXEDO System has a facility, the Disk Management Interface (DMI), which manages logical files within a single disk device or set of devices. Among other things, it stores binary configuration tables and the transaction log.

The BEA TUXEDO disk management software supports the notion of a BEA TUXEDO file system distinct from any operating system file system. (For the rest of this discussion, we're going to use the term OS file system to cover any operating system file system.)

Administrative access to the DMI to create, initialize, or destroy entries in the BEA TUXEDO file system is through tmadmin administrative commands.

There are two ways the logical files managed by the DMI can be stored physically. Physical storage can be on an OS file system. Alternatively, disk space outside the control of all OS file systems can be set aside for BEA TUXEDO; files reside on device special files in that space and are managed directly by the DMI. 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 that a write() is done can not be relied on. In the BEA TUXEDO System, accurate control of the write operation is particularly important for entries in the transaction log. With multiple users, it is also an important element in assuring database consistency.

Arranging for Raw Disk Space

If you decide to use raw disk space for your BEA TUXEDO application, you may find that the hard disk devices on your system 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 in order to set aside some partitions that are not 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 NT platforms, the default behavior is unbuffered I/O; no special arrangements are needed.

How the BEA TUXEDO File System Is Organized

A BEA TUXEDO System 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 BEA TUXEDO tables.

All System Tables on the Same Device?

In a BEA TUXEDO System application, all of 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, TLOG , be stored on a raw disk device. Since the TLOG seldom needs to be larger than 100 blocks and since disk partitions are always substantially larger than that, 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. Figure 1 shows approximately how the contents might appear.

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

Table 1: Size of System/T System Tables

The size for 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 block size assumed by the crdl subcommand of tmadmin is 1000 blocks, which should be adequate for the initial installation.

Space for Application Databases (If You Are Using /D)

If your BEA TUXEDO System application is using TUXEDO System/D as a resource manager, your database tables can be listed in the same UDL and managed by the BEA TUXEDO VTOC. If another resource manager is used, you should check the installation instructions for that product to see how its space requirements affect your BEA TUXEDO planning.

Space for Queue Spaces (If You Are Using /Q)

If your BEA TUXEDO System application is using /Q for store-and-forward queue management, your queue space can be listed in the same UDL and managed by the BEA TUXEDO VTOC.

Space for Application Servers

As you are calculating the space requirements for the BEA TUXEDO System, you should also consider the requirements of the servers that perform the work of the application. These requirements will be specified by the application, and they are over and above the requirements for BEA TUXEDO System itself (unless otherwise specified).

Selecting Directories for BEA TUXEDO Files

During the installation process you will be prompted to make decisions about where, in your filesystem, a number of your BEA TUXEDO directories and files will be installed. To help you plan for this part of the process, this section describes the directories and files about which you will be prompted to make a decision.

• "For All Platforms" should be read by anyone installing BEA TUXEDO.
• "For All Server Platforms Supporting the Web GUI" should be read by anyone installing the Web-based GUI for BEA TUXEDO application administration.

For All Platforms

You will be prompted for a pathname for the base directory of your BEA TUXEDO System software. There is no restriction on the location of this directory, as long as it meets the following requirements:

• The directory must be empty.
• The directory must have read, write, and search (execute) permissions for the BEA TUXEDO administrator.

Throughout the BEA TUXEDO documentation this directory is referred to as "TUXDIR" (formerly "ROOTDIR").

For All Server Platforms Supporting the Web GUI

If (a) you are installing BEA TUXEDO on a server platform, and (b) you have purchased the Web-based graphical user interface (GUI) for application administration, you will be prompted, during the installation process, to accept or replace the default pathnames and filenames used for the Web GUI components. These default pathnames and filenames are based on the value of TUXDIR 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 TUXEDO Web GUI and other Web programs on the same port. To accommodate this situation, BEA TUXEDO lets you choose between accepting the defaults and assigning your own pathnames and filenames. The rest of this section describes the choices you will be given.

1. A pathname for the HTML files--By default, the HTML files listed below are installed in the directory $TUXDIR/udataobj/webgui. You are prompted to supply your own paths for these files if you prefer to have them installed elsewhere.
   • An HTML template file (webgui.html) that is used by tuxadm as the basis for many screens displayed during a Web GUI session.
   • An HTML file (webguitop.html) that displays legal notices and warnings when the Web GUI is first brought up on the screen.
   • The HTML files that make up the Web GUI documentation are installed in $TUXDIR/doc.

   EXCEPTION: If you are installing BEA TUXEDO on an NT platform and the installation program detects an existing Web server, then a default directory appropriate for that Web server is used, instead.

2. A pathname for the Java and image files--By default, the class files for the Java applet are installed in one of the directories listed below. You are prompted to supply your own paths for these files if you prefer to have them installed elsewhere.
   • $TUXDIR/udataobj/webgui/java, or
   • A subdirectory called java in the HTML directory you specified after the prompt described above in #1.
3. A directory pathname for the CGI program (tuxadm)--Specify one of the following (unless the exception described below applies):
   • $TUXDIR/udataobj/webgui/cgi-bin
   • A sub-directory called "cgi-bin" in the HTML directory you specified after the prompt described above in #1.

   EXCEPTION: If the installation program detects Microsoft's Internet Information Server (IIS) in a standard directory, then tuxadm is installed in a sub-directory called "scripts" in the directory you specified, above, as the pathname for HTML files.

   Note: Do not specify $TUXDIR/bin as your CGI directory. If you do, you risk having some other BEA TUXEDO programs executed accidentally by an uninformed user of the Web browser. You may also introduce a security risk.

4. An alias for the directory pathname for tuxadm. This is the path for the directory in which Web clients will expect to find tuxadm. The default is either /cgi-bin or /scripts.
5. A pathname for the documentation--By default, the documentation is installed in $TUXDIR/doc.

Selecting an Administrative Password

BEA TUXEDO uses an administrative password to protect the machine on which it is installed from administrative requests and operations (such as tmboot) that are not authorized. Whenever administrative communications arrive on this machine through the tlisten and wlisten gateway processes, BEA TUXEDO authenticates them by means of the password.

You assign an administrative password during the installation process (to the machine on which BEA TUXEDO 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 BEA TUXEDO domain to communicate successfully. For this reason, you must use the same password whenever you install BEA TUXEDO on multiple machines for a single domain. As described above, you will be prompted to provide the password during the BEA TUXEDO installation process. If, however, for some reason, 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.

In addition, you may want to enable one machine to communicate with machines from multiple domains. If so, you must make sure that an administrative password for each target domain has been added to the tlisten.pw file on the machine being configured.

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

$TUXDIR/udataobj/tlisten.pw

Make sure the permissions on your tlisten.pw file are set such that the file is readable only by the BEA TUXEDO administrator.

Configuring the UNIX Operating System for BEA TUXEDO

The BEA TUXEDO System uses the UNIX operating system Interprocess Communication (IPC) resources.

Note: Equivalent services are available on operating systems other than the UNIX system. BEA TUXEDO provides an NT Service called TUXEDO IPC Helper, which facilitates inter-process communication. MVS/OpenEdition provides IPC mechanisms that are basically the same as those provided on a UNIX system, but that cannot be configured from within the OpenEdition environment. (See the MVS/OE documentation for instructions on administering these mechanisms.)

IPC resources are configured by three sets of tunable 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 application dependent. Most UNIX systems, however, are shipped with default values that are too low for any BEA TUXEDO application.

The following sections describe the IPC parameters and provide guidelines for configuring them. Because these parameters vary across different versions of UNIX the descriptions below are generic. Check Appendix A for the exact parameter names and defaults for each platform and for information on how to change the parameters. If you change a parameter, you will 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 BEA TUXEDO application is distributed, the minimum IPC resources must be available on every UNIX platform participating in the application.

Semaphores

Every process that participates in a BEA TUXEDO application requires a semaphore. When the application is booted the number of semaphores configured in the operating system is checked, and the boot will fail if the configured number is not high enough.

The following semaphore parameters may need to be adjusted:

SEMMNS

Maximum number of semaphores in the system. The minimum requirement for SEMMNS is

MAXACCESSERS - MAXWSCLIENTS + 13

where MAXACCESSERS is the maximum number of BEA TUXEDO processes on a particular machine (including servers and native clients) and MAXWSCLIENTS is the maximum number of workstation clients. Both of these parameters are specified in the application's UBBCONFIG file. For more information about UBBCONFIG, see the BEA TUXEDO Administrator's Guide or the ubbconfig(5) man page.

SEMMNI

Maximum number of active semaphore sets. See SEMMSL.

SEMMSL

Maximum number of semaphores per semaphore set. SEMMNI and SEMMSL are commonly chosen so that their product equals SEMMNS. The BEA TUXEDO System does not perform semaphore operations on semaphore sets; however, it attempts to allocate as many semaphores per semaphore set as possible.

SEMMAP

Size of the control map used to manage semaphore sets. SEMMAP should be equal to SEMMNI.

SEMMNU

Number of undo structures in the system. Because an undo structure is needed for each process that can access the Bulletin Board, SEMMNU must be at least as large as SEMMNS.

SEMUME

Maximum number of undo entries per undo structure. The value 1 suffices.

Message Queues and Messages

BEA TUXEDO uses 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 MSSQ set (Multiple Servers, Single Queue) 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 an application. Inappropriate values can lead to an inability to boot or 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 above parameter limits results in what is known as a blocking condition. There is a special case for MSGMAX. Messages that exceed 3/4 of MSGMNB, or that are larger than MSGMAX, are placed in a UNIX file. A very small message with the filename in it is then sent to the recipient. This mode of operation is to be avoided, as it results in a severe reduction in performance.

An application deadlock can result if every process is blocked trying to send a message. For example, when clients fill up the message space with requests and servers are all blocked trying to send replies, since no server can read a message, there is a deadlock. Timeouts can break the deadlock sometimes, but no useful work will have been done.

Especially troublesome is a client that sends its requests with the TPNOREPLY flag. In no time, this practice can fill up 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 what has been said above, if clients or servers are blocking on their send operations (requesting services or sending replies), then 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 just 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 (MSSQ), an arriving message wakes up all the idle (blocked) servers on that queue. In the case of a full server request queue, as each request is read by a server, the system wakes up all the blocked clients. Depending on the size of the messages, zero or more clients get to place their messages on the queue. The rest have to go back to sleep. Since 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. There are no magic answers. Tuning is very application dependent. The UNIX ipcs(1) command provides a snapshot of the queues so you can tell if 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

Number of unique message queue identifiers. Each process participating in a BEA TUXEDO application on a particular machine typically needs at least one message queue. This number is reduced if MSSQ sets are used, where multiple server processes share a single queue. For transaction processing, count an additional queue per server group for TMS processes. Thus, the minimum requirement for MSGMNI can be determined by this formula:

MSGMNI = MAXACCESSERS + 7
  + (number of servers with REPLYQ)
  + (number of MSSQ sets)
  - (number of servers in MSSQ sets)

MSGMAX

Maximum message size in bytes. MSGMAX must be big enough to handle any BEA TUXEDO application running on this machine.

MSGMNB

Maximum message queue length in bytes. This number must accommodate the total size of all messages that are on a queue and have not been taken off by the associated process(es). The minimum value for MSGMNB is MSGMAX. Messages longer than 75% of MSGMNB are sent to a file instead of to a message queue--a situation that should be avoided because it severely degrades performance.

MSGMAP

Number of entries in the control map used to manage message segments. MSGMAP should be the same as the number of message segments (MSGSEG), which should be twice the size of MSGMNI.

MSGSSZ

Size of a message segment in bytes. A message can consist of several such segments. The value of MSGSSZ should be such that a multiple of MSGSSZ is equal to the size (including the BEA TUXEDO System header) of the most commonly sent message. This practice will avoid wasting space.

MSGSEG

Number of message segments in the system.

MSGTQL

Total number of outstanding messages that can be stored by the kernel. This is the maximum number of unread messages at any given time.