BEA TUXEDO System Administration

A System/T application can be as simple as a single client and server operating entirely on one machine. Complexity enters the picture when clients are moved off the main machine (as in the BEA TUXEDO System workstation feature, when service requests are sent to a mainframe computer or when multiple machines are networked together to make a multiprocessor application.

Likewise, the development organization can range from a single person designing, programming and administering a BEA TUXEDO System application singlehandedly to a sizable department.

The Administrator's Role

Without recommending any specific model for a development organization, we see the administrator as the person (or group) responsible for configuring and booting an application and for keeping it in operation.

There is a continuum of strategies for administering a BEA TUXEDO System application that can best be conveyed by the illustration in Figure 1.

Figure 1: A Continuum of BEA TUXEDO Administration Strategies

Administration via the GUI is covered in the BEA TUXEDO Administrator's Guide to the Web-based GUI and in the help screens of the GUI itself. Most of the content of this volume dealts with administration via the UBBCONFIG file and shell commands such as tmadmin(1) and tmloadcf(1). Chapter 10 introduces the subjects of BEA TUXEDO MIBs and administration via /AdminAPI.

It is convenient for documentation purposes to separate application design and programming from administration. Application design because the designer--in our model--is concerned with what the application should achieve while the administrator is concerned with the nuts-and-bolts job of making the application run. Programming is logically separate from administration because it is consistent with the overall design of the BEA TUXEDO System to allow programmers to concentrate on the logic of services and clients while the deployment of the modules is decided by designers and implemented by administrators.

An Administrator's Questions about Design

Things about the application design that an administrator needs to know:

• How many machines will be used?
• Will clients be on machines remote from servers?
• What services does the application offer?
• What resource managers will the application use and where will they be located?
• What ``open'' strings will the resource managers need?
• What setup information is needed for an RDBMS?
• Will transactions be distributed?
• What buffer types are being used?
• Is data distributed across machines?
• Will data dependent routing be done?

This is only a sample. There are probably a couple of dozen more design questions that affect how the administrator configures the application.

It might be worth noting that the only questions in the above list to which programmers need to know the answer are the ones about services and buffer types.

An Administrator's Questions about Programs

The list of things that the administrator needs to know about the application's programs is considerably shorter:

• What are the names of the services?
• Are there any conversational services?
• What resource managers do they access?
• What buffer types do they use?

Again, this is not intended to be an exhaustive list; for example, it may be a question of organizational policy to decide how services are grouped into servers and who is going to be responsible (programmer or administrator) for building servers for the application. Programmers need to use buildserver(1) to link edit their service modules with the main() delivered with System/T in order to conduct unit testing, but when the code is ready to be made part of the whole application, it may make sense to have the administrator be responsible for the final link edit.

The Administrator's Role Diagrammed

On the theory that one picture is worth 10,000 words, we present in Figure 2 a diagram that shows the types of activities involved in administering a System/T application and the rough chronological order in which they take place.

Figure 2: System/T administration

System Resources

Given the broad outlines of an application design, the administrator has to make sure the operating system resources are available to support the application. For UNIX platforms, this includes shared resources (IPC), which govern such things as the maximum size of a message and maximum queue length, and resources governed by kernel parameters. The BEA TUXEDO Installation Guide tells how to find and change IPC parameters and other system tunables and recommends minimums; there is a section called "Message Size and Queue Length" in Chapter 7 of this guide.

If adjustments are made to system parameters, it is likely that the operating system will have to be rebooted.

Installing the Software

This subject is covered in the BEA TUXEDO Installation Guide.

Configuration

Configuration of the BEA TUXEDO System application is a central task of the System/T administrator. The term means describing your application using a set of parameters that are interpreted by the BEA TUXEDO System software to create a runnable OLTP application. In this section we are going to:

• mention the two different forms of a configuration file
• tell you about the most basic configuration in order to help you get used to the concepts and the jargon involved
• show an example of a bare-bones configuration that you can bring up and run

Two Forms, UBBCONFIG and TUXCONFIG

The configuration file exists in two forms:

• an ASCII version referred to as UBBCONFIG. The ASCII version is created and edited with any editor. Except for sample configuration files ( ubbshm, ubbmp and ubbsimple) distributed with the sample applications, bankapp and simpapp, no UBBCONFIG file is provided. One must be created for each new application. The syntax used for entries in the file is described in the ubbconfig(5) page (in the BEA TUXEDO Reference Manual) and in this guide.
• a binary version called TUXCONFIG. This version is created from the ASCII version by the tmloadcf(1) command. When tmloadcf is executed, the environment variable TUXCONFIG must be set to the full pathname of the device or system file where TUXCONFIG is to be loaded. Many parameters in TUXCONFIG can be changed while the application is running by using tmconfig(1).

The Bare Minimum

At its maximum a configuration file can have seven sections. There are 80 different parameters, and in all sections but the first, there can be multiple entries each with its own selection of parameters. It can get mind-boggling in a hurry, although to make life a little easier, in all sections other than RESOURCES, the first section, there is a DEFAULT parameter than can be used to specify parameters that repeat from one entry to the next.

*RESOURCES, the First of Three Required Sections

At its most basic, a configuration file can have as few as three sections and nine parameters.

The first section (and it must appear first in the ASCII file that contains the configuration) is used to establish the basic identity of your application. There are three parameters for which you must provide values:

IPCKEY

carries a numeric key that identifies the shared memory segment where the structures used by your application are located. The value must be greater than 32,768 and less than 262,143. You might find it helpful, especially if you expect to define a network of machines using TCP/IP addressing, to express the IPCKEY in hexadecimal notation.

MASTER

carries the logical machine identifier (LMID) of the machine that will serve as the master node of your application. LMID is a System/T coinage. It is the logical name assigned to a machine by the application--more than likely by the administrator.

MODEL

specifies the type of System/T application you are defining. There are just two valid choices: SHM, which stands for Shared Memory, and MP, which stands for Multiprocessor. In the minimum configuration file we are describing here, SHM is the only reasonable choice. If you specify MP, you will have to supply several other parameters to complete the multiprocessor specification.

There are almost two dozen other parameters in the RESOURCES section, but for the minimum configuration you can leave them blank and tacitly accept the default values.

*MACHINES, the Second of Three Required Sections

The second section of the configuration file is where you identify the machines that will be part of your BEA TUXEDO System application. Naturally enough, the name of the section is the MACHINES section. Entries in this section include only those machines that have the full System/T capability, what we refer to as native sites as opposed to workstation sites that support only System/T client programs.

You must have at least one entry in the MACHINES section. If you are defining a minimum configuration as we are doing in this example, the maximum is also one. Each entry is tagged with the physical name of the machine; in other words, the output of the

uname -n

command. There are four required parameters:

LMID = string_value

LMID is the logical machine identifier assigned to a processor in a System/T application. string_value cannot be more than 30 characters and cannot contain a period or comma. If string_value contains anything other than alphanumeric characters or the underscore, it must be enclosed in double quotes. This applies to all string_values in the configuration file. Since the string_values are often pathnames, it is a good safe practice always to use the double quotes.

TUXCONFIG = string_value

TUXCONFIG is the name used to refer to the binary version of the ASCII configuration file. string_value is an absolute pathname of the file or device where TUXCONFIG is located on the machine being defined. It cannot be more than 64 characters. TUXCONFIG is also the name of an environment variable (set to the same string_value) that is used by the System/T commands, tmloadcf(1) and tmboot(1) to compile the configuration file and boot the application. This internal entry is used by the BEA TUXEDO System software after the application is booted.

TUXDIR = string_value

TUXDIR refers to the directory where the BEA TUXEDO System software is installed on this machine. string_value is an absolute pathname to that directory on the machine being defined by the MACHINES section entry. TUXDIR is also the name of an environment variable required by System/T. In either use, the string_value cannot be longer than 64 characters.

APPDIR = string_value

APPDIR is the present working directory where application and administrative servers are booted. string_value is an absolute pathname to that directory, optionally followed by a colon-separated list of other directory pathnames, on the machine being defined. (On NT machines, the items on the list are separated by semi-colons.) It cannot be longer than 78 characters.

Figure 3 contains an example of a completed MACHINES section entry:

Figure 3: A MACHINES Section Entry

mach1		LMID=simple
		TUXCONFIG="/home/me/simpapp/tuxconfig"
		TUXDIR="/usr/tuxedo"
		APPDIR="/home/me/simpapp"

The values for TUXCONFIG, TUXDIR and APPDIR are placed in the environment of all servers booted on this machine.

*GROUPS, the Third of Three Required Sections

The GROUPS section is used to identify groups of servers that are in your application. What makes a group? The most common factor in grouping servers together is the resource manager (or DBMS) they access. Indeed, all the servers in a group must access the same instance of a resource manager (or none). Which is not to say that you couldn't have more than one group using the same resource manager instance. A group is the smallest unit that can be migrated to an alternate LMID and a group can be booted or shutdown as a unit.

Note: We're stretching a point here in saying that the GROUPS section is required. tmloadcf(1) does not fail if the section is not in the UBBCONFIG file. In Release 4.2 (and above), you can boot a system with only the administrative server BBL present and then dynamically add groups using tmconfig(1). However, before you can have a running application you must have at least one server group.

There must be at least one group defined in your minimum configuration file. An entry in the GROUPS section has a tag that is the logical name assigned to the group by the application. There are two required parameters for each entry:

LMID = string_value

Once again, LMID is the logical machine identifier. Its specification here tells the BEA TUXEDO System that this group runs on the machine associated with the LMID. As in the MACHINES section, string_value must be 30 characters or less. You can include a second string_value (separated from the first by a comma), if you have more than one LMID defined in the MACHINES section and you want to allow for server group migration, but this goes beyond the requirements for a minimum configuration.

GRPNO = number

is used to assign a number (greater than 0 and less than 30,000) to the group being defined. This number must be unique among the group entries in your configuration. It is used internally by the System/T software.

It is worth noting that the servers in a group defined with just these two required parameters would have limited capability. They would not be able, for example, to participate in System/T's distributed transaction processing; that capability is enabled through additional optional parameters in the GROUPS section.

Re-capping the Minimum Configuration

Well, there you have it, the barest-of-the-bare minimum configuration files. You can compile this configuration file with tmloadcf(1) and boot it with tmboot(1).

What you have conveyed to the BEA TUXEDO System software is information about the identity of your application--by providing the address of its shared memory segment in IPCKEY. You have given a logical name to the machine that is the home base of your application (with the LMID in MASTER) and connected the logical machine to a physical machine through the entry in the MACHINES section. In addition, you have supplied the BEA TUXEDO System with pathnames to three key directories (or files), and in the GROUPS section have named a group to which your application servers will belong. When you run tmloadcf to compile this file into the binary TUXCONFIG format, you will get a warning message about a missing server section, which leads to our next topic.

*SERVERS, Another Important Section

There is a slight hitch to the idea of a minimum configuration file: while you can compile successfully with the sections and parameters described above, you have not specified any application servers and while you can boot the configuration, your application wont really do anything until you boot a server. There are two ways to resolve this dilemma:

• include a SERVERS section in your configuration file before you compile TUXCONFIG, or
• use tmconfig(1) after compiling and booting the configuration to add a server entry to TUXCONFIG.

We suggest it is simpler to include a SERVERS section in your ASCII configuration file, and that is what is shown in the example below from simpapp.

Example from simpapp

One of the sample applications delivered with the BEA TUXEDO System is called simpapp. It is a single-processor application that has one client, one server group and one server that offers one service. All the service does is convert a string from lower case to upper. You can examine the source code for simpapp in directory $TUXDIR/apps/simpapp where there is also a README file that describes the steps to build and run the application. There is also a tutorial on simpapp in Chapter 1 of the BEA TUXEDO Application Development Guide. We showed an excerpt from the configuration file for simpapp in Figure 3. Figure 4 shows an adaptation of the complete configuration file. (The file as provided in $TUXDIR/apps/simpapp/ubbsimple uses some additional parameters that we haven't introduced yet.)

Figure 4: Configuration File from simpapp

*RESOURCES
IPCKEY		123456
MASTER		simple
MODEL		SHM
*MACHINES
mach1		LMID=simple
		APPDIR="/home/me/simpapp"
		TUXCONFIG="/home/me/simpapp/tuxconfig"
		TUXDIR="/usr/tuxedo"
*GROUPS
GROUP1 		LMID=simple
		GRPNO=1	
*SERVERS
simpserv		SRVGRP=GROUP1 SRVID=1