[Top]
[Previous Page] [Next Page] [Bottom]
Configuring each BEA TUXEDO application is a central task of the administrator. By configuring a file, you are describing your application using a set of parameters that the software interprets to create a runnable application.
This chapter discusses the following topics:
Note:
For related information about the DMCONFIG
domain configuration file, see
An application consists of four basic parts:
This section discusses the configuration file.
UBBCONFIG
file is
an ASCII version of the configuration file, created and edited with any editor. Except for
sample configuration files distributed with the BEA TUXEDO sample applications, no UBBCONFIG
file is provided. You must
create a UBBCONFIG
file
for each new application. The syntax used for entries in the file is described in the ubbconfig
(5) reference page in
Section 5 of the BEA TUXEDO Reference Manual. Note:
The BEA TUXEDO software provides the ubbshm
, ubbmp
,
and ubbsimple
sample UBBCONFIG
files, as part of the bankapp
and simpapp
applications. Portions of
these UBBCONFIG
sample
files are also shown in this document.
TUXCONFIG
file is
a binary version of the configuration file, created from the ASCII version by the tmloadcf
(1) command. When tmloadcf
is executed, the
environment variable TUXCONFIG
must be set to the full path name 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). At its maximum, a configuration file can consist of eight sections. At its minimum, it must contain three required sections:
RESOURCES
, in which
all system parameters are defined MACHINES
, in which all
the machines in your application are specified GROUPS
, in which all
groups, names, and IDs are defined for your application. The file must also contain a minimum of nine parameters. There are 80 different
parameters, and in all sections but the first, there can be multiple entries, each with
its own selection of parameters. In all sections other than RESOURCES
, the first section, you
can use a DEFAULT
parameter to specify parameters that repeat from one entry to the next.
This section explains how to set RESOURCES
parameters that control the application as a whole. Some of these parameters serve as
system-wide defaults and can be overridden on a per-machine basis in the MACHINES
section.
The RESOURCES
section
is a required section and must appear as the first section in the configuration file.
Information in this section includes the following:
IPCKEY
)
MASTER
)
for boot and shutdown UID
, GID
,
and PERM
) SECURITY
, AUTHSVC
)
MAXACCESSERS
, MAXSERVERS
, and MAXSERVICES
) MODEL
),
which indicates a single machine or multiple machines application LDBAL
)
MAXBUFTYPE
and MAXBUFSTYPE
)
SCANUNIT
, SANITYSCAN
) BLOCKTIME
)
MAXCONV
) NOTIFY
,
USIGNAL
) Some of these parameters serve as system-wide defaults (UID
, GID
, PERM
, MAXACCESSERS
, and MAXCONV
) and can be overridden on a
per-machine basis. For more information about the ubbconfig(5) reference page, see Section
5 of the BEA TUXEDO Reference Manual.
The following table provides sample parameters and values in the RESOURCES
section of a configuration
file for a BEA TUXEDO application.
RESOURCES IPCKEY 39211 UID 0 GID 1 PERM 0660 MAXACCESSERS 75 MAXSERVERS 40 MAXSERVICES 55 MASTER SITE1, SITE2 MODEL MP OPTIONS LAN, MIGRATE SECURITY APP_PW AUTHSVC "AUTHSVC" NOTIFY DIPIN SYSTEM_ACCESS PROTECTED, NO_OVERRIDE LDBAL Y
You set the address of shared memory using the IPCKEY
parameter. This parameter is
used by the BEA TUXEDO system to allocate application IPC resources such that they may be
located easily by new processes joining the application. This key and its variations are
used internally to allocate the Bulletin Board, message queues, and semaphores that must
be available to new application processes. In a single processor mode, this key names the
Bulletin Board; in a multiprocessor mode, this key names the message queue of the DBBL.
The IPCKEY parameter has the following characteristics:
IPCKEY
. RESOURCES
section, the IPCKEY
is
39211 for the sample BEA TUXEDO application. You must specify a master machine for all configurations (MASTER
). The master machine controls
the booting and administration of the entire application. This machine is specified as a
Logical Machine Identifier (LMID
).
This is an alphanumeric name chosen by the administrator. (LMID
s are discussed further in the
section
Two LMID
s are
specified if migration of the master site is to be allowed. If it is necessary to bring
down the master site without shutting down the application, it is necessary to specify the
backup master site.
The MASTER parameter has the following characteristics:
LMID
s are required
for migration to back up the master machine. RESOURCES
section, the master site is SITE1
;
the backup site is SITE2
.
Among the architectural decisions needed for a BEA TUXEDO application are the following:
The MODEL
parameter
specifies whether an application runs on a single processor. It is set to SHM
for uniprocessors and also for
multiprocessors with global shared memory. A MODEL
value of MP
is used for multiprocessors that do not have global shared memory, as well as for
networked applications. This is a required parameter.
The OPTIONS
parameter
is a comma-separated list of application configuration options. Two available options are LAN
(indicating a networked
configuration) and MIGRATE
(indicating that application server migration is allowed).
The MODEL and OPTIONS parameters have the following characteristics.
Note: No OPTIONS
are specified for the SHM
model.
You can provide basic access to a BEA TUXEDO application using three parameters: UID
, GID
, and PERM
:
UID
- the user ID of
the administrator. The value is a numeric value corresponding to the UNIX system user ID
of the person who boots and shuts down the system. GID
- the numeric Group
ID of the administrator. PERM
- an octal number
that specifies the permissions to assign to the IPC resources created when the application
is booted. This provides the first level of security to protect the BEA TUXEDO system IPC
structures against unauthorized access. The default is 0666, which gives read/write access
to all. These values should be specified for production applications. Note: If the UID
and GID
are not specified, they default to the IDs of the person who runs the tmloadcf
(1) command on the
configuration, unless they are overridden in the MACHINES
section.
The UID, GID, and PERM parameters have the following characteristics.
Note: You can overwrite values on remote machines.
Because most IPC and Shared Memory Bulletin Board tables are statically allocated for speedy processing, it is important to tune them correctly. If they are sized too generously, memory and IPC resources are consumed to excess; if they are set too small, the process fails when the limits are eclipsed.
The following tunable parameters related to IPC sizing are currently available in the RESOURCES
section:
MAXACCESSERS
-the
maximum number of overall processes allowed to be attached to the BEA TUXEDO system at one
site. It is not the sum of all processes, but is equal to the number at the site that has
the most processes. The default is 50. (You can overwrite MAXACCESSERS
on a per-machine basis
in the MACHINES
section.) MAXSERVERS
-the maximum
number of server processes in the application, including all the administrative servers
(for example, BBL and TMS). It is the sum of the server processes at all sites. The
default is 50. MAXSERVICES
-the
maximum number of different services that can be advertised in the application. It is the
sum of all services in the system. The default is 100. (When setting this value, consider
the defaults to be a quantity reserved for system resources.) The cost incurred by increasing MAXACCESSERS
is one additional semaphore per site per accesser. There is a small fixed semaphore
overhead for system processes in addition to that added by the MAXACCESSERS
value. The cost of
increasing MAXSERVERS
and MAXSERVICES
is a
small amount of shared memory that is kept for each server, service, and client entry,
respectively. The general idea for these parameters is to allow for future growth of the
application. It is more important to scrutinize MAXACCESSERS
.
Note: Two additional parameters, MAXGTT
and MAXCONV
, affect shared memory.
The MAXACCESSERS, MAXSERVERS, and MAXSERVICES parameters have the following characteristics.
You can control whether a load balancing algorithm is used on the BEA TUXEDO system as a whole. Using load balancing, a load factor is applied to each service within the system, and you can track the total load on every server. Every service request is sent to the qualified server that is least loaded.
This algorithm, although effective, is expensive and should be used only if it is
needed. It is needed only when a service is offered by servers that use more than one
queue. Services offered by only one server, or by servers in an MSSQ
(multiple server single queue)
set do not need load balancing. Their LDBAL
parameter should be set to N
.
In other cases, you may want to set LDBAL
to Y
.
If LDBAL
is set to N
and multiple queues offer the same
service, the first available queue is selected.
If LDBAL
is set to Y
and the application is networked,
the TMNETLOAD
environment variable can be used to give preference to local sites.
The LDBAL parameter has the following characteristics:
LDBAL
is set to Y
, the server assigned will be load
balanced. LDBAL
is set to Y
, you can use TMNETLOAD
for local preference. LDBAL
is set to N
, the server assigned will be the
first available server. N
. LDBAL
incurs
overhead, use it only when necessary. MSSQ
server set. You can control the number of buffer types and subtypes allowed in the application with
the MAXBUFTYPE
and MAXBUFSTYPE
parameters,
respectively. The current default for MAXBUFTYPE
is 16. Unless you are creating many user-defined buffer types, you can omit MAXBUFTYPE
. However, if you intend
to use many different VIEW
subtypes, you may want to set MAXBUFSTYPE
to exceed its current default of 32.
The MAXBUFTYPE and MAXBUFSTYPES parameters have the following characteristics.
You can set the number of times the administrative server (BBL) will periodically check the sanity of servers local to its machine. In addition, you can set the number of timeout periods for blocking messages, transactions, and other system activities.
You use the SCANUNIT
parameter to control the granularity of such checks and timeouts. Its value (in seconds)
can be a positive multiple of 5. Its default is 10.
You use the SANITYSCAN
parameter to specify how many SCANUNIT
s
elapse between sanity checks of the servers. It must not be set so that SANITYSCAN
* SCANUNIT
exceeds 300; its current
default is set so that SANITYSCAN
* SCANUNIT
is
approximately 120 seconds.
A SCANUNIT
of 10 and
a BLOCKTIME
of 3 allows
30 seconds before the client application times out. The BLOCKTIME
default is set so that BLOCKTIME
* SCANUNIT
is approximately 60
seconds. The value of BLOCKTIME
is the total of the following times:
The SCANUNIT, SANITYSCAN, and BLOCKTIME parameters have the following characteristics.
You can specify the maximum number of conversations on a machine with the MAXCONV
parameter.
The MAXCONV parameter has the following characteristics:
SERVERS
section is 10; otherwise,
the default is 1. MACHINES
section. You can set the following three levels of security:
PERM
parameter-sets
the first or lowest-level permission to write to the application queues. SECURITY
parameter-sets the second-level permission. This requires that the client supplies a
password when joining the application. This password is checked against the password
supplied by the administrator when the TUXCONFIG
file is generated from the UBBCONFIG
file. AUTHSVC
parameter-sets
the third-level permission. This sends the client's request to join the application to an
authentication service. This level requires the second level of SECURITY
to be present. The
authentication service may be the default supplied by the BEA TUXEDO system or it may be a
service, such as a Kerberos service, supplied by another vendor. The SECURITY and AUTHSVC parameters have the following characteristics.
You can set the default method for clients to receive unsolicited messages using the NOTIFY
parameter. The client,
however, can override this choice in the TPINIT
structure when tpinit
() is called.
Following are three possible methods:
IGNORE
-clients should
ignore unsolicited messages. DIPIN
-clients should
receive unsolicited messages only when they call tpchkunsol
() or when they make an ATMI call. SIGNAL
-clients should
receive unsolicited messages by having the system generate a signal that has the signal
handler call the function, that is, set with tpsetunsol
(). Two types of signals can be generated: SIGUSR1
and SIGUSR2
.
The USIGNAL
parameter
allows the administrator to choose the type of signal. The default is SIGUSR2
. In applications that choose
notification by signals, any MS-DOS client workstations are switched automatically to DIPIN
.
The NOTIFY and USIGNAL parameters have the following characteristics.
You can shield system tables kept in shared memory from application clients and/or
servers using the SYSTEM_ACCESS
parameter. This option is useful when applications are being developed because faulty
application code can inadvertently corrupt shared memory with a bad pointer. When the
application is fully debugged and tested, this option could then be changed to allow for
faster responses. Following are the options for this parameter:
PROTECTED
-BEA TUXEDO
libraries compiled with application code will not attach to shared memory while executing
system code. FASTPATH
-BEA TUXEDO
libraries will attach to shared memory at all times. NO_OVERRIDE
-the
selected option cannot be changed either by the client in the TPINIT
structure of the tpinit
() call or in the SERVERS
section for servers. The PROTECTED, FASTPATH, and NO_OVERRIDE parameters have the following characteristics.
Note: An example: SYSTEM_ACCESS
PROTECTED, NO_OVERRIDE
This section explains how to define parameters for each processor, or machine, on which your application runs.
Every machine in an application must have a MACHINES
section entry in the configuration file and it must be
the second section in the file. The MACHINES
section contains the following information specific to each machine in the application:
LMID
) TUXCONFIG
) TUXDIR
) APPDIR
) ULOGPFX
) ENVFILE
) The only required parameters for the MACHINES
section are LMID
, TUXCONFIG
,
TUXDIR
, and APPDIR
.
Note: For a particular machine, you can override the UID
, GID
, PERM
, MAXACCESSERS
, and MAXCONV
values that were specified
in the RESOURCES
section.
The following table provides a sample of parameters and their values in the MACHINES
section of the
configuration file.
The following example provides a sample MACHINES section of a configuration file:
MACHINES gumby LMID=SITE1 TUXDIR="/tuxdir" APPDIR="/home/apps/mortgage" TUXCONFIG="/home/apps/mortgage/tuxconfig" ENVFILE="/home/apps/mortgage/ENVFILE" ULOGPFX="/home/apps/mortgage/logs/ULOG" MAXACCESSERS=100 MAXCONV=15
You can customize the MACHINES section by performing the following steps:
TUXDIR.
APPDIR.
ENVFILE
,
TUXCONFIG
, and ULOGPFX.
You initially define the address in the address portion, which is the basis for a MACHINES
section entry. All other
parameters in the entry describe the machine specified by the address. You must set the
address to the value printed by calling uname -n
on
UNIX systems
. On Windows NT systems, see the Computer Name value in the
Network Control Panel.
The LMID
parameter is
mandatory and specifies a logical name used to designate the computer whose address has
just been provided. It may be any alphanumeric value, and must be unique among other
machines in the application.
The address and machine ID and the LMID parameter have the following characteristics:
<address> LMID=<logical_machine_name>
LMID
parameter is LMID=<logical_machine_name>
.
LMID
is the
logical machine name for a physical processor. LMID
is alphanumeric
and must be unique within the MACHINES
section. You identify the configuration file location and file name of a machine with TUXCONFIG
, a required parameter. The
TUXCONFIG
parameter is
enclosed in double quotes and represents the full path name up to 64 characters. The path
specified must be the same as the environment variable, TUXCONFIG
; otherwise, the tmloadcf
(1) will
not compile the binary file.
The TUXCONFIG parameter has the following characteristics:
TUXCONFIG
parameter is TUXCONFIG="<tuxconfig>"
.
TUXCONFIG
for convention purposes) for the machine. TUXCONFIG
can be up to 64 characters. TUXCONFIG
must match the TUXCONFIG
environment variable. Each machine in an application must have a copy of the BEA TUXEDO system software and
application software. You identify the location of system software with the TUXDIR
parameter. You identify the
location of the application servers with the APPDIR
parameter. Both parameters are mandatory. The APPDIR
parameter becomes the current
working directory of all server processes. The BEA TUXEDO software looks in the TUXDIR/bin
and APPDIR
for executables.
The TUXDIR and APPDIR parameters have the following characteristics.
The application log file contains warning and informational messages, as well as error
messages that describe the nature of any ATMI error with a return code of TPESYSTEM
or TPEOS
(that is, underlying system
errors). The user can use this log to track application-related errors. By default, the
file is named ULOG.
mmddyy
where mmddyy
is
the month, date, and 2-digit year. By default, the file is written into the APPDIR
.
You can override the default directory and prefix by specifying the ULOGPFX
parameter that is the
absolute path name of the application log file, without the date. For example, it may be
set to APPDIR/logs/ULOG
so that logs collect in a particular directory. In a networked application, a central log
can be maintained by specifying a remote directory that is mounted on all machines.
The ULOGPFX parameter has the following characteristics:
ULOGPFX
parameter is a string enclosed in double quotes: ULOGPFX="<ULOGPFX>"
. TPESYSTEM
and TPEOS
errors. ULOGPFX
defaults
to <APPDIR>/ULOG
.
ULOGPFX=
``/usr/appdir/logs/ULOG
'' ULOGPFX=
``/mnt/usr/appdir/logs/BANKLOG
'' With the ENVFILE
parameter, you can specify a file that contains environment variable settings for all
processes to be booted by the BEA TUXEDO system. The system sets TUXDIR
and APPDIR
for each process, so they
should not be specified in this file. You can specify settings for the following because
they affect an application's operation:
FIELDTBLS
, FLDTBLDIR
VIEWFILES
, VIEWDIR
TMCMPLIMIT
TMNETLOAD
The ENVFILE
parameter
has the following characteristics:
ENVFILE
parameter is a string enclosed in double quotes: ENVFILE="<envfile>"
. ENVFILE
is the file
containing environment variable settings for all processes booted by the BEA TUXEDO
system. (The UBBCONFIG
file issues warnings in a similar way, that is, using fully qualified path names.) FIELDTBLS
, FLDTBLDIR
, and so on, but do not set
TUXDIR
and APPDIR
. ENVFILE
parameter
is optional and all settings must be hard coded. No evaluations such as FLDTBLDIR=$APPDIR
are allowed. VARIABLE=
string.
You can override the following system-wide parameters for a specific machine:
UID
GID
PERM
MAXACCESSERS
MAXCONV
MAXGTT
Note: Each parameter, except MAXGTT
, is described in the RESOURCES
section.
You can use GROUPS
to
designate logically grouped sets of servers, which can later be used to access resource
managers, and facilitate server group migration. The GROUPS
section of the configuration
file contains the definition of server groups. You must define at least one server group
for a machine to have application servers running on it. If no group is defined for a
machine, the group can still be part of the application and you can run the administrative
command tmadmin
(1) from
that site.
For nontransactional, nondistributed systems, groups are relatively simple. You only need to define the basic mapping of group name to group number and logical machine of each group. Additional flexibility is available to support distributed transactional systems.
The group name is the basis for a GROUPS
section entry and is an alphanumeric name by which the group is identified. It is given a
mandatory, unique group number (GRPNO
).
Each group must reside wholly on one logical machine (LMID
). The LMID
is also mandatory.
This section explains the SERVERS
section parameters that you need to define to configure server processes.
The SERVERS
section
of the configuration file contains information specific to a server process. While this
section is not required, an application without this section has no application servers
and little functionality. Each entry in this section represents a server process to be
booted in the application. Server-specific information includes the following:
SRVGRP
, SRVID
)
CLOPT
)
SEQUENCE
, MIN
, MAX
) ENVFILE
)
RQADDR
,
RQPERM
, REPLYQ
, RPPERM
) RESTART
,
RCMD
, MAXGEN
, GRACE
) CONV
) SYSTEM_ACCESS
) Command-line options supported by the BEA TUXEDO system are described on the servopts
(5) reference page
in the BEA TUXEDO Reference Manual.
The following table provides a sample of parameters and their values in the SERVERS
section of the configuration
file.
The following example provides a sample SERVERS section of a configuration file.
SERVERS DEFAULT: RESTART=Y MAXGEN=5 GRACE=3600 REPLYQ=N CLOPT="-A" ENVFILE="/usr/home/envfile" SYSTEM_ACCESS=PROTECTED RINGUP1 SRVGRP=GROUP1 SRVID=1 MIN=3 RQADDR="ring1" RINGUP2 SRVGRP=GROUP1 SRVID=4 MIN =3 RQADDR="ring2"
Note: Omitted from this sample are SEQUENCE
(the order of booting is 1
to 6), REPLYQ
and RPPERM
(the server does not receive
replies), RCMD
(no
special commands are desired on restart), and CONV
(servers are not conversational). Defaults are applied to all
servers unless a different setting is specified for a specific server.
You initially define the server name entry in the SERVERS
section entry, which is the
name of an executable file built with buildserver
(1). You must provide
each server with a group identifier (SRVGRP
).
This is set to the name specified in the beginning of a GROUPS
section entry. You must also
provide each server process in a given group with a unique numeric identifier (SRVID
). Every server must specify a SRVGRP
and SRVID
. Because the entries describe
machines to be booted and not just applications, it is possible that in some cases the
same server name will be displayed in many entries.
The Server Name, SRVGRP
,
and SRVID
parameters
have the following characteristics.
The server may need to obtain information from the command line. The CLOPT
parameter allows you to
specify command-line options that can change some defaults in the server, or pass
user-defined options to the tpsvrinit()
function.
The standard main()
of a server parses one set of options ending with the argument --, and passes the
remaining options to tpsvrinit()
.
The default for CLOPT
is
-A, which tells the server to advertise all the services built into it with buildserver
(1). The following table
provides a partial list of the available options.
Note: You can find other standard main()
options in the servopts
(5) reference page in the
BEA TUXEDO Reference Manual.
CLOPT="servopts
-- application_opts"
. main()
and tpsvrinit()
use server command-line options. servopts
(5)
options are passed to main()
.
tpsvrinit()
. BANKAPP
example is CLOPT="-A -- -T 10"
. Note: In the BANKAPP
example, the server is given the option to advertise all
services (-A) and tellerID of 10 so it can update a specific teller record with each
operation. The use of this option, especially the options passed to tpsvrinit()
, require communication
between the system administrator and the application programmer.
You can specify the sequence of servers to be booted with the SEQUENCE
parameter, which specifies
a number in the range of 1 to 10,000. A server given a smaller SEQUENCE
value is booted before a
server with a larger value. If no servers specify SEQUENCE
, servers are booted in the
order of their appearance within the SERVERS
section. If there is a mixture of sequenced and unsequenced servers, the sequenced servers
are booted first. Servers are shut down in reverse order of the way they were booted.
The SEQUENCE
parameter is optional. It may be helpful in a large application in which control over the
order is important.
You can boot multiple servers using the MIN
parameter, which is a shorthand method of booting. The servers
all share the same server options. If you specify RQADDR
, the servers will form an MSSQ
set. The default for MIN
is 1.
You specify the maximum number of servers that can be booted with the MAX
parameter. The tmboot
(1) command boots up to MIN
servers at run time. Additional
servers can be booted up to MAX
.
The default is MIN
.
The MIN
and MAX
parameters are helpful in large
applications to keep the size of the configuration file manageable. Allowances for MAX
values must be made in the IPC
resources.
The SEQUENCE, MIN, and MAX
parameters have the following characteristics.
You use the ENVFILE
parameter in the MACHINES
section to specify environment settings. You can also specify the same parameter for a
specific server process; the semantics are the same. If both the MACHINES
section ENVFILE
and the SERVERS
section ENVFILE
are specified, both go into
effect. For any overlapping variable defined in both the MACHINES
and SERVERS
sections, the setting in the
SERVERS
section
prevails.
The parameter that defines the server environment file has the following characteristics:
ENVFILE
parameter in the MACHINES
section, but for one server
only. SERVERS
section ENVFILE
overrides the setting in the MACHINES
section ENVFILE
. Server Queue information controls the creation and access of server message queues. On
a BEA TUXEDO system, you can create multiple server single queue (MSSQ
) sets using the RQADDR
parameter. For any given
server, you can set this parameter to an alphanumeric value. Those servers that offer the
same set of services can consolidate their services under one message queue, providing
automatic load balancing. You can do this by specifying the same value for all members of
the MSSQ
set.
The MSSQ
set is
similar to a situation at a bank. If you have four tellers, one line may be formed and
everyone is assured of the most equitable wait in line. Understandably, the loan teller is
not included because some people do not want loans on a given day. Similarly, MSSQ
sets are not allowed if the
participant servers offer different services from one another.
The RQPERM
parameter
allows you to specify the permissions of server request queues, along the lines of the
UNIX system convention (for example, 0666). This allows services to control access to the
request queue.
If the service routines within an MSSQ
server perform service requests, they must receive replies to their requests on a reply
queue. This is done by specifying REPLYQ=Y
.
By default, REPLYQ
is
set to N
. If REPLYQ
is set to Y
, you can also assign permissions
to it with the RPPERM
parameter.
The RQADDR, RQPERM, REPLYQ, and RPPERM parameters have the following characteristics.
A properly debugged server should not terminate on its own. By default, servers that do
terminate while the application is booted will not be restarted by the BEA TUXEDO system.
You can set the RESTART
parameter to Y
if you
want the server to restart. The RCMD
,
MAXGEN
, and GRACE
parameters are relevant to a
server if RESTART=Y
.
The RCMD
parameter
specifies a command to be performed in parallel with restarting a server. This command
must be an executable file. The option allows you to take some action when a server is
being restarted. For example, mail could be sent to the developer of the server or to
someone who is auditing such activity.
The MAXGEN
parameter
represents the total number of lives to which a server is entitled within the
period specified by GRACE
.
The server can then be restarted MAXGEN-1
times during GRACE
seconds. If GRACE
is set
to zero, there is no limit on server restarts. MAXGEN
defaults to 1 and may not exceed 256. GRACE
must be greater than or equal
to zero and must not exceed 2,147,483,647 (231 - 1).
Note: A fully debugged server should not need to be restarted. The RESTART
and associated parameters
should have different settings during the testing phase than they do during production.
The RESTART, RCMD, MAXGEN, and GRACE parameters have the following characteristics.
If a server is a conversational server (that is, it establishes a connection with a
client), the CONV
parameter is required and must be set to Y
. The default is N
, indicating that the server will not be part of a conversation.
The CONV parameter has the following characteristics:
Y
value indicates a
server is conversational; an N
value indicates a server is not conversational. Y
value is required
if the server is to receive conversational requests. N
. The SYSTEM_ACCESS
parameter determines if the server process may attach to shared memory and thus have
access to internal tables outside of system code. During application development, we
recommend that such access be denied (PROTECTED
).
When the application is fully tested, you can change it to FASTPATH
to yield better
performance.
This parameter overrides the value specified in the RESOURCES
section unless the NO_OVERRIDE
value was specified. In
this case, the parameter is ignored. The NO_OVERRIDE
value may not be used in this section.
The SYSTEM_ACCESS parameter has the following characteristics:
PROTECTED
indicates that the server may not attach to shared memory outside of the system code. FASTPATH
indicates that the server will attach to shared memory at all times. NO_OVERRIDE
is
specified in the RESOURCES
section, this parameter is ignored. RESOURCES
value. You indicate specific information about BEA TUXEDO services in your application in the SERVICES
section of the
configuration file. Such information, for nontransactional, nondistributed applications,
is relatively simple. The SERVICES
section includes the following types of information:
SRVGRP
)
BUFTYPE
)
The following example provides a sample SERVICES section of a configuration file.
SERVICES # DEFAULT: LOAD=50 PRIO=50 RINGUP BUFTYPE="VIEW:ringup"
In this example, the default load and priority of a service are 50
; the one service declared is a RINGUP
service that accepts a ringup
VIEW
as its required buffer type.
If you set the RESOURCES
section parameter LDBAL
to Y
, server load
balancing occurs. A LOAD
factor is assigned to each service performed, which keeps track of the total load of
services that each server has performed. Each service request is routed to the server with
the smallest total load. The routing of that request causes the server's total to be
increased by the LOAD
factor of the service requested.
Load information is stored only on the site originating the service request. It would be inefficient for the BEA TUXEDO system to attempt to constantly propagate load information to all sites in a distributed application. When performing load balancing in such an environment, each site knows only about the load it originated and performs load balancing accordingly. This means that each site has different load statistics for a given server (or queue). The server perceived as being the least busy differs across sites.
When load balancing is not activated, and multiple servers offer the same service, the first available queue receives the request.
The LDBAL parameter has the following characteristics:
RESOURCES
LDBAL
parameter is set to Y
. You can exert significant control over the flow of data in an application by assigning
service priorities using the PRIO
parameter. For instance, Server 1 offers Services A, B, and C. Services A and B have a
priority of 50
and
Service C has a priority of 70. A service requested for C will always be dequeued before a
request for A or B. Requests for A and B are dequeued equally with respect to one another.
The system dequeues every tenth request in FIFO
order to prevent a message from waiting indefinitely on the
queue.
Note: A priority can also be changed dynamically with the tpsprio()
call.
The PRIO parameter has the following characteristics:
FIFO
.
You can specify different load, priority, or other service-specific parameters for
different server groups. To do this, you should repeat the service's entry for each group
with different values for the SRVGRP
parameter.
The following example provides a sample SERVICES section of a configuration file.
SERVICES A SRVGRP=GRP1 PRIO=50 LOAD=60 A SRVGRP=GRP2 PRIO=70 LOAD=30
This example assigns different service-specific parameters to two different server
groups. Service A assigns a priority of 50, and a load of 60 in server group GRP1
; and a priority of 70, and a
load of 30 in server group GRP2
.
With the BUFTYPE
parameter, you can tune a service to check buffer types independently of the actual
service code. If you set this parameter, it specifies a list of allowable buffer types for
a service. Its syntax is a semicolon-separated list of types in the format type[:subtype[,subtype]]
. The
subtype may be set to *
to allow all subtypes.
A service can have BUFTYPE
set to ALL
, which means
that this service accepts all buffer types. If this parameter is not specified, the
default is ALL
.
The BUFTYPE parameter has the following characteristics.
Sometimes an unexpected system error occurs that freezes a service or causes it to run out of control while it is processing a request. Though desirable to remove these processes, it is difficult to detect them or their origin. A BEA TUXEDO mechanism terminates these processes based on the time it takes for a service to process a request.
You can configure the time limit by defining the SVCTIMEOUT
parameter in the UBBCONFIG
file or by dynamically
changing the TA_SVCTIMEOUT
attribute in TM_MIB
. By
default, the BEA TUXEDO system does not terminate any service process, so you must set the
SVCTIMEOUT
value (in
seconds) to activate this feature. We recommend that you set the value of SVCTIMEOUT
or TA_SVCTIMEOUT
to at least two to
three times the number of seconds it takes for your longest running service to process a
request. Setting the service timeout this way guarantees that the BEA TUXEDO system
removes only frozen processes. In essence, the service timeout acts like a scavenger for
frozen or out of control application servers.
This section describes the causes and results of Service Timeout errors, along with an explanation of how the BEA TUXEDO system reports such errors. Advice about how to handle errors is also provided.
Service timeouts occur in the following situations:
SVCTIMEOUT
generally when an unknown or unexpected system error freezes the server process, or when
an application coding error causes an infinite loop or recursion. tpreturn
,
tpforward
, TPRETURN
, or TPFORWARD
(application coding
error). tpreturn
,
tpforward
, TPRETURN
, or TPFORWARD
is called (application
coding error). tpreturn
, tpforward
,
TPRETURN
, or TPFORWARD
is called (application
coding error). When a timeout occurs, the BEA TUXEDO system terminates the server process running the
frozen service (but not its child processes, if any). It then returns a TPESVCERR
error, indicating that an
unknown problem occurred during processing. In a conversational service, the conversation
event TPEV_SVCERR
is
returned.
Before Release 6.4 of the BEA TUXEDO system, only the error code TPESVCERR
was returned when a
service timeout occurred. In Release 6.4, however, three new features of Service Timeout
reporting were introduced:
TPED_SVCTIMEOUT
-timeout
error detail that provides more information than tpstrerror
(3c) .SysServiceTimeout
-a
system event ULOG
information about
.SysServiceTimeout
Because the SVCTIMEOUT
value is configurable, it is important for clients to be able to easily distinguish a TPESVCERR
that may be caused by
exceeding the value set for SVCTIMEOUT
,
from those caused by other situations. Although the ULOG
contains this information, it
is difficult for client programs to extract it. To differentiate the service timeout TPESVCERR
from others, a call to tperrordetail
(3c) routine (after a TPESVCERR
has been detected) yields TPED_SVCTIMEOUT
when a service
timeout occurs.
In addition, a system event, .SysServiceTimeout
,
is generated when a service timeout occurs. When the .SysServiceTimeout
event occurrs, it
is reflected in the ULOG
in the following way:
ERROR: .SysServiceTimeout: %TA_SERVERNAME, group %TA_SRVGRP, id %TA_SRVID server killed due to a service timeout
SVCTIMEOUT
parameter in the SERVICES
section of the UBBCONFIG
file, or by modifying the TA_SVCTIMEOUT
attribute of the T_SERVER
or T_SERVICE
class of TM_MIB
. They may also monitor the ULOG
file for service timeout
activity. ULOG
file for service timeout activity, application operators can subscribe to the .SysServiceTimeout
event, which
alerts them when a service timeout occurs. tperrordetail
(3c)
and tpstrerrordetail
(3c)
APIs, and the TPED_SVCTIMEOUT
error
detail code.
They may
want to add one or more subscriptions to the .SysServiceTimeout
system event, which is generated when a service
timeout occurs. The ROUTING
section
of UBBCONFIG
allows the
full definition of the routing criteria named in the SERVICES
section (for BEA TUXEDO
data-dependent routing).
For more information about using these parameters to implement factory-based routing or data-dependent routing, see Chapter 5, "Distributing Applications."
The following table identifies the information required for an entry in the ROUTING
section.
The RANGES
parameter
provides the actual mapping between field value and group name. Its syntax is as follows.
RANGES="[val1[-val2]:group1]
[,val3[-val4]:group2]...[,*:groupn]"
where val1
, val2
, and so on, are values of
that field and groupn
may be either a group name or the wildcard character (*) denoting that any group may be
selected. The * character occupying the place of val
at the end is a Catch-All
choice, that is, it specifies what to do if the data does not fall into any range
that has been specified. val1
is a number when it appears in numeric fields, and is enclosed in single quotes (`) when
it appears in STRING
or CARRAY
fields. The field values MIN
and MAX
(not enclosed in quotes) are
provided to allow machine minimum and maximum data values to be expressed. There
is no limit to the number of ranges that may be specified, but all routing information is
stored in shared memory and incurs a cost there.
Note: Overlapping ranges are allowed, but values that belong to both
ranges map to the first group. For example, if RANGES
is specified as RANGES="0-5:Group1,3-5:Group2"
, then a range value of 4
routes to Group1
.
You can configure network groups in the NETGROUPS
and NETWORK
sections of an application's UBBCONFIG
file.
Note: For specific information about the tasks involved, see
Chapter 6, "Building Networked Applications."The NETGROUPS
section
of the UBBCONFIG
file
describes the network groups available to an application in a LAN environment. There is no
limit to the number of network groups to which a pair of machines may be assigned. The
method of communication to be used by members of different networks in a network group is
determined by the priority mechanism (NETPRIO
).
Every LMID
must be a
member of the default network group (DEFAULTNET
).
The network group number for this group (that is, the value of NETGRPNO
) must be zero. However, you
can modify the default priority of DEFAULTNET
.
Networks defined in releases of the BEA TUXEDO system prior to Release 6.4 are assigned to
the DEFAULTNET
network
group.
The NETGRPNO
, NETPRIO
, NETGROUP
, MAXNETGROUPS
, and MAXPENDINGBYTES
parameters have the
following characteristics.
You can associate network addresses with a network group. The following example illustrates how this capability may be useful.
First State Bank has a network of five machines (A-E). Each machine belongs to two or three of four netgroups that you have defined in the following way:
DEFAULTNET
(the
default network, which is the corporate WAN) MAGENTA_GROUP
(a LAN) BLUE_GROUP
(a LAN) GREEN_GROUP
(a private
LAN that provides high-speed, fiber, point-to-point links between member machines) Every machine belongs to DEFAULTNET
(the corporate WAN). In addition, each machine is associated with either the MAGENTA_GROUP
or the BLUE_GROUP
. Finally, some machines
in the MAGENTA_GROUP
LAN
also belong to the private GREEN_GROUP
.
Figure 3-1 Example of a Network Grouping
The following table shows you which machines have addresses for which groups.
Note: Because the local area networks are not routed among the
locations, machine D (in the BLUE_GROUP
LAN) may contact machine A (in the GREEN_GROUP
LAN) only by using the single address they have in common: the corporate WAN network
address.
To set up the configuration just described, the First State Bank system administrator
defines each group in the NETGROUPS
section of the UBBCONFIG
file, as shown in
Listing 3-1 Sample NETGROUPS and NETWORK Sections
NETGROUPS DEFAULTNET NETGRPNO = 0 NETPRIO = 100 #default BLUE_GROUP NETGRPNO = 9 NETPRIO = 100 MAGENTA_GROUP NETGRPNO = 125 NETPRIO = 200 GREEN_GROUP NETGRPNO = 13 NETPRIO = 200 NETWORK A NETGROUP=DEFAULTNET NADDR="//A_CORPORATE:5723" A NETGROUP=MAGENTA_GROUP NADDR="//A_MAGENTA:5724" A NETGROUP=GREEN_GROUP NADDR="//A_GREEN:5725"
B NETGROUP=DEFAULTNET NADDR="//B_CORPORATE:5723" B NETGROUP=MAGENTA_GROUP NADDR="//B_MAGENTA:5724" B NETGROUP=GREEN_GROUP NADDR="//B_GREEN:5725"
C NETGROUP=DEFAULTNET NADDR="//C_CORPORATE:5723" C NETGROUP=MAGENTA_GROUP NADDR="//C_MAGENTA:5724" D NETGROUP=DEFAULTNET NADDR="//D_CORPORATE:5723" D NETGROUP=BLUE_GROUP NADDR="//D_BLUE:5726"
[Top] [Previous Page] [Next Page] [Bottom]