PURPOSE
ubbconfig - TUXEDO System/T ASCII configuration
file
DESCRIPTION
A binary configuration file, called the TUXCONFIG
file, contains information used by tmboot(1) to start the servers and initialize
the bulletin board of a TUXEDO System/T bulletin board
instantiation in an orderly sequence. The binary TUXCONFIG
file cannot be created directly (although an existing TUXCONFIG
file can be dynamically modified through tmconfig(1)).
Initially, a UBBCONFIG file of the format described on
this reference page must be created. That file is parsed and
loaded into the TUXCONFIG file using tmloadcf(1). tmadmin(1) uses
the configuration file (or a copy of it) in its monitoring
activity. tmshutdown(1)
references the configuration file for information needed to shut
the application down.
Definitions
A server is a process that accepts requests and sends replies
for clients and other servers. A client originates requests and
gets replies.
A resource manager is an interface and associated software
providing access to a collection of information and/or processes.
An example of a resource manager is a database management system;
a resource manager instance is a particular instantiation of a
database controlled by a DBMS. A distributed transaction is a
transaction that spans multiple resource manager instances, is
started with tpbegin(), and ended with tpcommit()
or tpabort().
A server group is a resource manager instance and the
collection of servers and/or services providing access to that
resource manager instance on a particular machine. The XA
interface associated with the group is used for transaction
management. If a server does not access a resource manager
instance or doesn't access it as part of a distributed
transaction, it must be in a server group with a null XA
interface. Similarly, clients run in a special client group that
does not have to be specified in the GROUPS section.
The client group is not associated with a resource manager.
A remote domain is defined to be an environment for which this
configuration's TUXEDO System/T bulletin board is not available.
Remote domains are not specified in the UBB configuration file,
but rather through host-specific environment variables that are
specified in host-specific manpages.
Configuration File Format
The format of a UBB configuration file is as follows:
- The file is made up of eight specification sections.
Lines beginning with an asterisk (*) indicate
the beginning of a specification section. Each such line
contains the name of the section immediately following
the *. Allowable section names are: RESOURCES,
MACHINES, GROUPS, NETGROUPS,
NETWORK, SERVERS, SERVICES,
and ROUTING. The RESOURCES and MACHINES
sections must be the first two sections in that order;
the GROUPS section must be ahead of SERVERS,
SERVICES, and ROUTING. The NETGROUPS
section must be ahead of the NETWORK section.
Parameters
(except in the RESOURCES section) are
generally specified by: KEYWORD = value.
This sets KEYWORD to value. Valid keywords
are described below within each section. KEYWORDs
are reserved; they can not be used as values.
Lines beginning with the reserved word, DEFAULT:,
contain parameter specifications that apply to any lines
that follow them in the section in which they appear.
Default specifications can be used in all sections other
than the RESOURCES section. They can appear
more than once in the same section. The format for these
lines is: DEFAULT: [optional KEYWORD=value
pairs] The values set on this line remain in effect
until reset by another DEFAULT: line, or until
the end of the section is reached. These values can also
be overridden on non-DEFAULT: lines by placing
the optional parameter setting on the line. If on a non-DEFAULT:
line, the parameter setting is valid for that line only;
lines that follow revert to the default setting. If DEFAULT:
appears on a line by itself, all previously set defaults
are cleared and their values revert to the system
defaults.
If a value is numeric, standard C notation is
used to denote the base (that is, 0x prefix for base 16
(hexadecimal), 0 prefix for base 8 (octal), and no prefix
for base 10 (decimal)). The range of values acceptable
for a numeric parameter are given under the description
of that parameter.
If a value is an identifier, standard C rules
are used. An identifier must start with an
alphabetic character or underscore and contain only
alphanumeric characters or underscores. The maximum
allowable length of an identifier is 30 (not including
the terminating null). An identifier cannot be the same
as any KEYWORD.
A value that is neither an integer number or an
identifier must be enclosed in double quotes. This value
is called a string. The maximum allowable length
of a string is 78 (not including the terminating null).
Exceptions to this are the CLOPT, BUFTYPE,
OPENINFO, and CLOSEINFO parameters,
which can be 256 characters in length, and the RANGES
parameter, which can be 2048 characters in length (except
in Domain, where it can be up to 1024 characters). In the
RANGES parameter of the ROUTING
section, certain special characters can be escaped inside
a string using a backslash.
``\\'' translates to a single backslash.
``\"'' translates to a double quote.
``\n'' translates to a newline.
``\t'' translates to a tab.
``\f'' translates to a formfeed.
``\O+'' translates to a character whose octal value is O+
where O+ is one, two, or three octal
characters. ``\0'' translates to an embedded
null character. ``\xH+'' or ``\XH+''
translates to a character whose hexadecimal value is H+
where H+ is one or more hexadecimal
characters. ``\y'' (where 'y' is any character
other than one of the previously mentioned characters)
translates to 'y'; this produces a warning.
- --
- Some values are required to be an identifier, as noted
below. Other values that can be either an identifier or a
string are indicated below as a string_value. The
maximum allowable length of a string_value is 78
characters if it is a string (not including the
terminating null) and 30 characters if it is an
identifier.
-
- --
- "#" (pound sign) introduces a
comment. A newline ends a comment.
-
- --
- An identifier or a numeric constant must always be
followed by white space (space, tab, or newline) or a
punctuation character (pound sign, equals sign, asterisk,
colon, comma, backslash, or period).
-
- --
- Blank lines and comments are ignored.
-
- --
- Comments can be freely attached to the end of any line.
-
- --
- Lines are continued by placing at least one tab after the
newline. Comments can not be continued.
The RESOURCES Section
This section provides for user specification of the
system-wide resources, such as the number of servers, and
services which can exist within a service area. Lines in this
section are of the form: KEYWORD value where KEYWORD
is the name of the parameter, and value its associated
value. Valid KEYWORDs are:
- IPCKEY numeric_value
- specifies the numeric key for the well-known address in a
TUXEDO System/T bulletin board. In a single processor
environment, this key ``names'' the bulletin board. In a
multiple processor environment, this key names the
message queue of the DBBL. In addition, this key is used
as a basis for deriving the names of resources other than
the well-known address, such as the names for bulletin
boards throughout a multiprocessor. IPCKEY
must be greater than 32,768 and less than 262,143. This
parameter is required.
- MASTER string_value1[,string_value2]
- specifies the machine on which the master copy of the TUXCONFIG
is found. Also, if the application is being run in MP
mode, MASTER names the machine on which the
DBBL should be run. string_value2 names an
alternate LMID location used during process
relocation and booting. If the primary location is not
available, the DBBL is booted at the alternate location
and the alternate TUXCONFIG file found there
is used. Both LMID values must name machines
found in the MACHINES section and must be less
than or equal to 30 characters in length. This parameter
is required (even in SHM mode).
In an
application that supports multiple release levels of BEA
TUXEDO on different machines, MASTER and BACKUP
must always have a release with a number greater than or
equal to all other machines in the application. This rule
is not enforced during a "Hot Upgrade."
- DOMAINID string_value1
- specifies the domain identification string. If not
specified, the value "" is used.
- UID numeric_value
- specifies the numeric user ID to be associated with the
IPC structures created for the bulletin board. This value
should be a UNIX System user ID on the local system. If
not specified, the value is taken to be the effective
user ID of the user executing tmloadcf(1).
The *RESOURCES value for this parameter can be
overridden in the *MACHINES section on a
per-processor basis.
- GID numeric_value
- specifies the numeric group ID to be associated with the
IPC structures created for the bulletin board. This value
should be a valid UNIX System group ID on the local
system. If GID is not specified, the effective
group ID of the user executing tmloadcf(1)
is used. The *RESOURCES value for this
parameter can be overridden in the *MACHINES
section on a per-processor basis.
- PERM numeric_value
- specifies the numeric permissions associated with the IPC
structures that implement the bulletin board. It is used
to specify the read/write permissions for processes in
the usual UNIX system fashion (that is, with an octal
number such as 0600). If not specified, the permissions
on the IPC structures default to 0666 (read/write access
by same user, same group, and any other). The value can
be between 0001 and 0777, inclusive. The *RESOURCES
value for this parameter can be overridden in the *MACHINES
section on a per-processor basis.
- MAXACCESSERS numeric_value
- specifies the default maximum number of processes that
can have access to a bulletin board on a particular
processor at any one time. System administration
processes, such as the BBL and tmadmin, need
not be accounted for in this figure. This value must be
greater than 0 and less than 32,768. If not specified,
the default value is 50. The *RESOURCES value
for this parameter can be overridden in the *MACHINES
section on a per-processor basis.
- MAXSERVERS numeric_value
- specifies the maximum number of servers to be
accommodated in the server table of the bulletin board.
This value must be greater than 0 and less than 8192. If
not specified, the default value is 50.
- MAXSERVICES numeric_value
- specifies the maximum total number of services to be
accommodated in the services table of the bulletin board.
This value must be greater than 0 and less than 32,768.
If not specified, the default value is 100.
- MAXGROUPS numeric_value
- specifies the maximum number of configured server groups
to be accommodated in the group table of the bulletin
board. This value must be greater than or equal to 100
and less than 8192. If not specified, the default value
is 100.
- MAXNETGROUPS numeric_value
- specifies the maximum number of configured network groups
to be accommodated in the NETWORK section of
the TUXCONFIG file. This value must be greater
than or equal to 1 and less than 8192. If not specified,
the default value is 8.
- MAXMACHINES numeric_value
- specifies the maximum number of configured machines to be
accommodated in the machine tables of the bulletin board.
This value must be greater than or equal to 256 and less
than 8,191. If not specified, the default value is 256.
- MAXQUEUES numeric_value
- specifies the maximum number of server request queues to
be accommodated in the queue table of the bulletin board.
This value must greater than or equal to 1 and less than
8,192. If not specified, the value is set to the
configured value for MAXSERVERS.
Interoperability with releases prior to 5.0 requires that
this value be equal to the configured value for MAXSERVERS.
- MAXACLGROUPS numeric_value
- specifies the maximum number of group identifiers that
can be used for ACL permissions checking. The maximum
group identifier that can be defined is TA_MAXACLGROUPS -
1. This value must be greater than or equal to 1 and less
than or equal to 16K. If not specified, the default value
is 16K.
- MODEL { SHM | MP }
- specifies the configuration type. This parameter is
required and only one of the two settings can be
specified. SHM specifies a one-machine
configuration; only one machine may be specified in the MACHINES
section. MP specifies a multi-machine
configuration; MP must be specified if a
networked application is being defined. Note: to change value
without relinking, servers must be built to support the
models needed (see buildserver(1)).
- LDBAL { Y | N }
- specifies whether or not load balancing should be
performed. If LDBAL is not specified, the
default is Y. It is recommended that if each
service maps to one and only one queue, then LDBAL
should be set to N, since load balancing is
automatic.
- CMTRET { COMPLETE | LOGGED
}
- specifies the initial setting of the TP_COMMIT_CONTROL
characteristic for all client and server processes in a
System/T application. If value is LOGGED,
then the TP_COMMIT_CONTROL characteristic is initialized
to TP_CMT_LOGGED; otherwise, it is initialized to
TP_CMT_COMPLETE. If CMTRET is not specified,
the default is COMPLETE. See the description
of the System/T ATMI function, tpscmt(), for
details on the setting of this characteristic.
- OPTIONS identifier[,identifier . . . ]
- specifies options that are used. If more than one option
is given, they are separated by commas. The following are
the options that can be specified. The identifier LAN
indicates that this is a networked application. The
identifier MIGRATE indicates that server group
migration can be done. If MIGRATE is
specified, LAN should also be specified,
(except for the case where the configuration runs on a
single multiprocessor computer). This parameter is
optional and the default is no options.
- SYSTEM_ACCESS identifier[,identifier]
- specifies the default mode used by System/T libraries
within application processes to gain access to System/T's
internal tables. Valid access types are FASTPATH
or PROTECTED. FASTPATH specifies
that System/T's internal tables should be accessible by
System/T libraries via shared memory for fast access. PROTECTED
specifies that while System/T's internal tables are
accessible by System/T libraries via shared memory, the
shared memory for these tables is not accessible outside
of the System/T libraries. NO_OVERRIDE can be
specified (either alone or in conjunction with FASTPATH
or PROTECTED) to indicate that the mode
selected cannot be overridden by an application process.
If SYSTEM_ACCESS is not specified or if it is
specified with NO_OVERRIDE alone, the default
mode is FASTPATH.
- SECURITY string_value1
- specifies the type of application security to be
enforced. The possible string values are "NONE",
"APP_PW", "USER_AUTH", "ACL",
or "MANDATORY_ACL". This parameter
defaults to "NONE". The value "APP_PW"
indicates that application password security is to be
enforced (clients must provide the application password
during initialization). Setting "APP_PW"
causes tmloadcf to prompt for an application
password. The value "USER_AUTH" is
similar to "APP_PW" but, in
addition, indicates that per-user authentication will be
done during client initialization. The value "ACL"
is similar to "USER_AUTH" but, in
addition, indicates that access control checks will be
done on service names, queue names, and event names. If
an associated ACL is not found for a name, it is assumed
that permission is granted. The value "MANDATORY_ACL"
is similar to "ACL" but permission
is denied if an associated ACL is not found for the name.
- AUTHSVC string_value
- specifies the name of an application authentication
service that is invoked by the system for each client
joining the system. This parameter requires that the SECURITY
identifier be set to "USER_AUTH",
"ACL", or "MANDATORY_ACL".
(For upward compatibility, setting both SECURITY
APP_PW and AUTHSVC implies SECURITY
USER_AUTH.) The parameter value must be 15
characters or less in length. For SECURITY
level "USER_AUTH", the default
service name, if not specified, is "AUTHSVC".
For SECURITY level "ACL"
or "MANDATORY_ACL", the service name
must be "..AUTHSVC". (This will be
silently enforced if the administrator tries to set it to
anything else).
- MAXGTT numeric_value
- specifies the maximum number of simultaneous global
transactions in which a particular machine can be
involved. It must be greater than or equal to 0 and less
than 32768. If not specified, the default is 100. The *RESOURCES
value for this parameter can be overridden in the *MACHINES
section on a per-processor basis.
- MAXCONV numeric_value
- specifies the maximum number of simultaneous
conversations in which processes on a particular machine
can be involved. It must be greater than 0 and less than
32,768. If not specified, the default is 10 if any
conversational servers are defined in the *SERVERS
section and 1 otherwise. The *RESOURCES value
for this parameter can be overridden in the *MACHINES
section on a per-processor basis. The maximum number of
simultaneous conversations per server is 64.
- MAXBUFTYPE numeric_value
- specifies the maximum number of buffer types that can be
accommodated in the buffer type table in the bulletin
board. It must be greater than 0 and less than 32,768. If
not specified, the default value is 16.
- MAXBUFSTYPE numeric_value
- specifies the maximum number of buffer subtypes that can
be accommodated in the buffer subtype table in the
bulletin board. It must be greater than 0 and less than
32,768. If not specified, the default value is 32.
- MAXDRT numeric_value
- specifies the maximum number of configured data dependent
routing criteria entries. It must be greater than or
equal to 0 and less than 32,768. If not specified, the
default is determined from the configured *ROUTING
section entries.
- MAXRFT numeric_value
- specifies the maximum number of data dependent routing
range field table entries. It must be greater than or
equal to 0 and less than 32,768. If not specified, the
default is determined from the configured *ROUTING
section entries.
- MAXRTDATA numeric_value
- specifies the maximum string pool size for data dependent
routing range strings. It must be greater than or equal
to 0 and less than 32,761. If not specified, the default
is determined from the configured *ROUTING
section entries.
- SCANUNIT numeric_value
- is the interval of time (in seconds) between which
periodic scans are done by the BBL to find old
transactions and timed-out blocking calls within service
requests. This value is used as the basic unit of
scanning by the BBL. This value affects the granularity
with which transaction timeout values can be specified on
tpbegin(3c)
and the blocking timeout value specified with the BLOCKTIME
parameter. The SANITYSCAN, BBLQUERY,
DBBLWAIT, and BLOCKTIME parameters
are multipliers of this unit for other timed operations
within the system. It must be a multiple of 5 greater
than 0 and less than or equal to 60 seconds. The default
is 10 seconds.
- SANITYSCAN numeric_value
- sets a multiplier of the basic SCANUNIT
between sanity checks of the system. The value SCANUNIT
must be greater than 0. If this parameter is not
specified, the default value is set so that (SCANUNIT
* SANITYSCAN) is approximately 120 seconds.
Sanity checks include checking servers as well as the
bulletin board data structure itself. Each BBL checks
that all servers on its machine are viable; that is, the
server hasn't terminated abnormally and is not looping.
Processes deemed not viable are either cleaned up or
restarted, depending on the options with which they were
started. Following that, the BBL sends a message (without
reply) to the DBBL to indicate it is okay.
- DBBLWAIT numeric_value
- sets a multiplier of the basic SCANUNIT for
the maximum amount of wall time a DBBL should wait for
replies from all its BBLs before timing out. Every time
the DBBL forwards a request to its BBLs, it waits for all
of them to reply with a positive acknowledgment before
replying to the requester. This option can be used for
noticing dead or insane BBLs in a timely manner. The
value of DBBLWAIT must be greater than 0. If
this parameter is not specified, the default value is set
so that (SCANUNIT * DBBLWAIT) is
the greater of SCANUNIT or 20 seconds.
- BBLQUERY numeric_value
- sets a multiplier of the basic SCANUNIT
between status checks by the DBBL of all BBLs. The DBBL
checks to ensure that all BBLs have reported in within
the BBLQUERY cycle. If a BBL has not been
heard from, the DBBL sends a message to that BBL asking
for status. If no reply is received, the BBL is
partitioned. The value of BBLQUERY must be
greater than 0. If this parameter is not specified, the
default value is set so that (SCANUNIT * BBLQUERY)
is approximately 300 seconds.
- BLOCKTIME numeric_value
- sets a multiplier of the basic SCANUNIT after
which a blocking call (for example, receiving a reply)
times out. The value of BLOCKTIME must be
greater than 0. If this parameter is not specified, the
default value is set so that (SCANUNIT * BLOCKTIME)
is approximately 60 seconds.
- NOTIFY { DIPIN | SIGNAL
| IGNORE }
- specifies the default notification detection method to be
used by the system for unsolicited messages sent to
client processes. This default value can be overridden on
a per-client basis using the appropriate tpinit(3c)
flag value. Note that once unsolicited messages are
detected, they are made available to the application
through the application- defined unsolicited message
handling routine identified via the tpsetunsol()
function ( tpnotify(3c)). The value DIPIN
specifies that dip-in-based notification detection should
be used. This means that the system will only detect
notification messages on behalf of a client process while
within ATMI calls. The point of detection within any
particular ATMI call is not defined by the system and
dip-in detection will not interrupt blocking system
calls. DIPIN is the default notification
detection method. The value SIGNAL specifies
that signal-based notification detection should be used.
This means that the system sends a signal to the target
client process after the notification message has been
made available. The system installs a signal catching
routine on behalf of clients selecting this method of
notification. All signaling of client processes is done
by administrative system processes and not by application
processes. Therefore, only clients running with the same
UNIX System user identifier can be notified using the SIGNAL
method. The value IGNORE specifies that by
default, notification messages are to be ignored by
application clients. This would be appropriate in
applications where only clients that request notification
at tpinit() time should receive unsolicited
messages.
- USIGNAL { SIGUSR1 | SIGUSR2
}
- specifies the signal to be used if SIGNAL-based
notification is used. The legal values for this parameter
are SIGUSR1 and SIGUSR2. SIGUSR2
is the default value for this parameter. USIGNAL
may be specified even if SIGNAL-based
notification is not selected with the NOTIFY
parameter, because callers of tpinit() may
choose signal-based notification.
The MACHINES Section
The MACHINES section specifies the logical names
for physical machines and processing elements within
multiprocessor computers for the configuration. It also specifies
parameters specific to a given machine. The MACHINES
section must contain an entry for each physical processor used by
the application. Entries have the form: ADDRESS required
parameters [optional parameters] where ADDRESS
is the physical name of a processor, that is, the value produced
by the UNIX system uname -n command. The length of the
entire ADDRESS must be 30 characters or less. If the name
is not an identifier, it must be enclosed in double quotes. If
the LAN option is not specified, only one machine name
can appear in this section. One of the required KEYWORDs
is LMID, which is the logical machine string_value
assigned to the physical machine. An LMID string_value
must be unique within the MACHINES section of the
configuration file.
- LMID = string_value
- specifies that string_value is to be used in other
sections as the symbolic name for ADDRESS. This
name cannot contain a comma, and must be 30 characters or
less. This parameter is required. There must be an ADDRESS
line for every processor used in a configuration.
These parameters are required:
- TUXCONFIG = string_value
- This is the absolute pathname of the file or device where
the binary TUXCONFIG file is found on this
machine. The maximum string value length is 64
characters. The administrator need only maintain one TUXCONFIG
file, namely the one that is pointed to by the TUXCONFIG
environment variable on the MASTER machine.
Copies on other machines of this master TUXCONFIG
file are synchronized with the MASTER machine
automatically when the system is booted. This parameter
must be specified for each machine. If TUXOFFSET
is specified, then the TUXEDO file system starts at that
number of blocks from the beginning of the TUXCONFIG
device (see TUXOFFSET below). See ENVFILE
in the *MACHINES section for a discussion of how this
value is used in the environment.
- TUXDIR = string_value
- This is the absolute pathname of the directory where the
TUXEDO System/T software is found on this machine. This
parameter must be specified for each machine and the
pathname should be local to each machine; in other words,
TUXDIR should not be on a remote file system.
If the machines of a multiprocessor application have
different TUXEDO System/T releases installed, check the
discussion of Interoperability in the BEA TUXEDO
Release Notes for the higher-level release to make
sure you will get the functionality you expect. See ENVFILE
in the *MACHINES section for a discussion of how this
value is used in the environment.
- APPDIR = string_value
- The value specified for this parameter is the absolute
pathname of the application directory and is the current
directory for all application and administrative servers
booted on this machine. The absolute pathname can
optionally be followed by a colon-separated list of other
pathnames. In a configuration where SECURITY
is set, each application must have its own distinct APPDIR.
See ENVFILE in the *MACHINES section for a
discussion of how this value is used in the environment.
Optional parameters are:
- UID = number
- specifies the numeric user ID to be associated with the
IPC structures created for the bulletin board. The valid
range is 0-2147483647. If not specified, the default
value is the value specified in the *RESOURCES section.
- GID = number
- specifies the numeric group ID to be associated with the
IPC structures created for the bulletin board. The valid
range is 0-2147483647. If not specified, the default
value is the value specified in the *RESOURCES section.
- PERM = number
- specifies the numeric permissions associated with the IPC
structures that implement the bulletin board. It is used
to specify the read/write permissions for processes in
the usual UNIX system fashion (that is, with an octal
number such as 0600). The value can be between 0001 and
0777, inclusive. If not specified, the default value is
the value specified in the *RESOURCES section.
- MAXACCESSERS = number
- specifies the maximum number of processes that can have
access to the bulletin board on this processor at any one
time. System administration processes, such as the BBL
and tmadmin, need not be accounted for in this
figure, but all application servers and clients and TMS
servers are counted. This value must be greater than 0
and less than 32,768. If not specified, the default value
is the value specified in the *RESOURCES section.
- MAXWSCLIENTS = number
- specifies the number of accesser entries on this
processor to be reserved for workstation clients only.
The parameter is used only when the /Workstation feature
is used. The number specified here takes a portion of the
total accesser slots specified with MAXACCESSERS.
The appropriate setting of this parameter helps to
conserve IPC resources since workstation client access to
the system is multiplexed through a System/T supplied
surrogate, the workstation handler. This value must be
greater than or equal to 0 and less than 32,768. The
default value is 0. It is an error to set this number to
a value greater than MAXACCESSERS.
- MAXACLCACHE = number
- specifies the number of entries in the cache used for ACL
entries when SECURITY is set to "ACL"
or "MANDATORY_ACL". The appropriate
setting of this parameter helps to conserve on shared
memory resources and yet reduce the number of disk access
to do ACL checking. This value must be greater than or
equal to 10 and less than or equal to 30,000. The default
is 100.
- MAXCONV = number
- specifies the maximum number of simultaneous
conversations in which processes on a particular machine
can be involved. It must be greater than 0 and less than
32,768. If not specified, the default value is the value
specified in the *RESOURCES section.
The maximum
number of simultaneous conversations per server is 64.
- MAXPENDINGBYTES = number
- specifies a limit for the amount of space that can be
allocated for messages waiting to be transmitted by the
bridge process. number must be between 100,000 and
MAXLONG.
- MAXGTT = number
- specifies the maximum number of simultaneous global
transactions in which a particular machine can be
involved. It must be greater than or equal to 0 and less
than 32,768. If not specified, the default value is the
value specified in the *RESOURCES section.
- TYPE = string_value
- is used for grouping machines into classes. TYPE
can be set to any string value that is 15 characters or
less. If two machines have the same TYPE
value, data encoding/decoding is bypassed when sending
data between the machines. TYPE can be given
any string value. It is used for comparison. The TYPE
parameter should be used when the application involves a
heterogeneous network of machines or when different
compilers are used on the machines in the network. If not
specified, the default value is the null string, which
matches any other entry that does not have a value
specified.
- CMPLIMIT = string_value1[,string_value2]
- specifies the threshold message size for messages bound
to remote processes (string_value1) and local
processes (string_value2) respectively, at which
automatic data compression will take place. Both values
must be either a non-negative numeric value or the string
"MAXLONG". If not specified, the
default value for this parameter is "MAXLONG,MAXLONG".
- NETLOAD = numeric_value
- specifies the additional load to be added when computing
the cost of sending a service request from this machine
to another machine. It must be greater than or equal to 0
and less than 32,768. If not specified, the default value
is 0.
- SPINCOUNT = numeric_value
- specifies the number of attempts that should be made at
user level to lock the bulletin board before blocking
processes on a UNIX semaphore. This value must be greater
than or equal to 0. A value of 0 indicates that the
spincount built into the delivered binary should be used.
If set, this parameter causes the TMSPINCOUNT
environment variable to be ignored. This varies from
platform to platform. The default value for this
parameter is 0.
- TLOGDEVICE = string_value
- specifies the TUXEDO filesystem that contains the DTP
transaction log (TLOG) for this machine. The TLOG
is stored as a TUXEDO System VTOC table on the device. If
this parameter is not specified, then the machine is
assumed to not have a TLOG. The maximum string
value length is 64 characters.
- TLOGOFFSET = offset
- specifies the numeric offset in pages (from the beginning
of the device) to the start of the TUXEDO filesystem that
contains the DTP transaction log for this machine. The
offset must be greater than or equal to 0 and less than
the number of pages on the device. The default is 0.
- TLOGNAME = string_value
- specifies the name of the DTP transaction log for this
machine. If not specified, the default is ``TLOG''.
If more than one TLOG exists on the same TLOGDEVICE,
they must have unique names. TLOGNAME must be
different from the name of any other table on the
configuration where the TLOG table is created.
It must be 30 characters or less.
- TLOGSIZE = size
- specifies the numeric size, in pages, of the DTP
transaction log for this machine. It must be greater than
0 and less than or equal to 2048, subject to the amount
of available space on the TUXEDO filesystem. If not
specified, the default is 100 pages.
- ULOGPFX = string_value
- specifies the absolute pathname prefix of the path for
the userlog(3c)
error message file on this machine. The value of ULOGPFX
for a given machine is used to create the userlog(3c)
error message file for all servers, clients, and
administrative processes executed on that machine. If
this parameter is not specified, $APPDIR/ULOG
is used. ``mmddyy'' (month, day, year) is
appended to the prefix to get the actual log file name.
- TUXOFFSET = offset
- specifies the numeric offset in pages (from the beginning
of the device) to the start of the TUXEDO filesystem that
contains the TUXCONFIG for this machine. The
offset must be greater than or equal to 0 and less than
the number of pages on the device. The default offset is
0. The value of TUXOFFSET, if non-zero, is
placed in the environment of all servers booted on a
machine. See ENVFILE in the *MACHINES section
for a discussion of how this value is used in the
environment.
- ENVFILE = string_value
- specifies that all clients and servers on the machine are
to be executed with the environment specified in the
named file. If the value specifies an invalid file name,
no values are added to the environment. Lines must be of
the form ident=value where ident
begins with an underscore or alphabetic character, and
contains only underscore or alphanumeric characters.
Within the value, strings of the form ${env}
are expanded when the file is processed using variables
already in the environment. (Forward referencing is not
supported and if a value is not already set, the variable
is replaced with the empty string.) Backslash (\e) may be
used to escape the dollar sign and itself. All other
shell quoting and escape mechanisms are ignored and the
expanded value is placed into the environment.
Client
programs process only the MACHINES ENVFILE
during tpinit().
When booting servers, local servers inherit the
environment of tmboot(1) and remote servers
(not on the MASTER) inherit the environment of
tlisten(1). TUXCONFIG, TUXDIR,
and APPDIR are also put into the environment
when a server is booted based on the information in the
associated *MACHINES entry. An attempt to
reset these three variables to another value will not be
allowed and will result in a warning. tmboot
and tlisten process the machine ENVFILE
before starting the server, allowing for the environment
to indicate necessary pathnames for finding executable
and dynamically loaded files. Once the server is running,
as part of server initialization (before the application
gets control in tpsvrinit()), a server will
read and export variables from both the machine and
server ENVFILE files. If a variable is set in
both the machine and server ENVFILE, the value
in the server ENVFILE will override the value
in the machine ENVFILE.
PATH and LD_LIBRARY_PATH are
treated specially. Before a server is activated, the
machine ENVFILE is scanned to find the first
occurrence of a PATH or LD_LIBRARY_PATH
variable; embedded environment variables within those
variables are not expanded. PATHLD_LIBRARY_PATH
are used to find pathnames for executable and dynamically
loaded files. PATH will always be prefixed
with
${APPDIR}:${TUXDIR}/bin:/bin:
if the value doesn't already begin with this string.
This PATH will be used as a search path for
servers that are specified with a simple or relative
pathname. LD_LIBRARY_PATH will always be
prefixed with
${APPDIR}:${TUXDIR}/lib:/lib:/usr/lib:
if the value doesn't already begin with this string. SHLIB_PATH
is set on HPUX and LIBPATH is set on AIX
instead of LD_LIBRARY_PATH.
The GROUPS Section
This section provides information about server groups. This
section must have at least one server group defined in it (which
can be added via tmconfig(1)
after the TUXCONFIG file has been created). A server
group entry provides a logical name for a collection of servers
and/or services on a machine. The logical name is used as the
value of the SRVGRP parameter in the SERVERS
section to identify a server as part of this group. SRVGRP
is also used in the SERVICES section to identify a
particular instance of a service with its occurrences in the
group. Other GROUPS parameters associate this group
with a specific resource manager instance (for example, the
employee database). Lines within the GROUPS section
have the form:
GROUPNAME required_parameters [optional_parameters]
where GROUPNAME specifies the logical name (string_value)
of the group. The group name must be unique within all group
names in the GROUPS section and LMID values
in the MACHINES section and cannot contain an asterisk
(*), comma, or colon. It must be 30 characters or less.
Required parameters are:
- LMID = string_value1 [, string_value2]
- specifies that this group of servers resides on the
machine symbolically named by string_value1 in the
MACHINES section (or the default value in SHM
mode). Each LMID value must be 30 characters or less. Up
to two logical machine names can be specified. The second
logical name, if given and if server group migration is
enabled, indicates the machine to which the server group
can be migrated.
- GRPNO = number
- specifies the numeric group number associated with this
server group. This number must be greater than 0 and less
than 30000, and must be unique among all entries in the GROUPS
section.
Optional parameters are:
- TMSNAME = string_value
- specifies the name of the transaction manager server a.out
associated with this group. This parameter must be
specified for any group entry whose servers will
participate in distributed transactions (transactions
across multiple resource managers--and possibly
machines--that are started with tpbegin(3c),
and ended with tpcommit(3c)/ tpabort(3c)).
It specifies the file (string_value) to be
executed by tmboot(1)
when booting the server group. The value ``TMS''
is reserved to indicate use of the null XA interface. If
a non-empty value other than ``TMS'' is
specified, then a TLOGDEVICE must be specified
for the machine(s) associated with the LMID
value(s) for this entry. A unique server identifier is
selected automatically for each TM server, and the
servers will be restartable an unlimited number of times.
- TMSCOUNT = number
- specifies the number of transaction manager servers to
start for the associated group, if TMSNAME is
specified. This parameter is optional and the default
value is 3. If specified and the value is non-zero, the
minimum value is 2 and the maximum value is 10. The
servers are set up in an MSSQ set automatically.
- OPENINFO = ``string''
- specifies the resource manager instance-dependent
information needed when opening the resource manager. The
value must be enclosed in double quotes and must be less
than or equal to 256 characters in length. This value is
ignored if TMSNAME is not set or is set to ``TMS''.
The format of the OPENINFO string is dependent
on the requirements of the vendor providing the
underlying resource manager. The information required by
the vendor must be prefixed with ``rm_name:,''
which is the published name of the vendor's transaction
(XA) interface followed immediately by a colon (:). For
TUXEDO System databases, the format is: OPENINFO="TUXEDO/D:fsconfig:dbname:openmode"
where ``TUXEDO/D'' is the published name of
the TUXEDO System/D XA interface, fsconfig is the
name of the FSCONFIG on which the database
resides, dbname is the name of the database, and openmode
is one of ``readonly'' or ``readwrite''.
For NT and NetWare, the colon separator after fsconfig
and dbname must be a semi-colon. For TUXEDO
System/SQL databases, the format is: OPENINFO="TUXEDO/SQL:fsconfig:dbname:openmode"
where "TUXEDO/SQL" is the published name of the
TUXEDO System/SQL XA interface, fsconfig is the
name of the FSCONFIG on which the database
resides, dbname is the name of the database, and openmode
is one of ``readonly'' or ``readwrite''.
For NT and NetWare, the colon separator after fsconfig
and dbname must be a semi-colon. For TUXEDO /Q
databases, the format is: OPENINFO="TUXEDO/QM:qmconfig:qspace"
where "TUXEDO/QM" is the published name of the
TUXEDO /Q XA interface, qmconfig is the name of
the QMCONFIG on which the queue space resides,
and qspace is the name of the queue space. For NT
and NetWare, the colon separator after qmconfig
must be a semi-colon. If TMSNAME is set but
the OPENINFO string is set to the null string
("") or this parameter does not
appear on the entry, it means that a resource manager
exists for the group but does not require any information
for executing an open operation.
- CLOSEINFO = ``string''
- specifies the resource manager instance-dependent
information needed when closing the resource manager. The
value must be enclosed in double quotes and must be less
than or equal to 256 characters in length. This value is
ignored if TMSNAME is not set or is set to ``TMS''.
The format of the CLOSEINFO string is
dependent on the requirements of the vendor providing the
underlying resource manager. The information required by
the vendor must be prefixed with ``rm_name:,''
which is the published name of the vendor's transaction
(XA) interface followed immediately by a colon (:). For
TUXEDO System/SQL databases, a CLOSEINFO
string is not used. If TMSNAME is set but the CLOSEINFO
string is set to the null string ("")
or this parameter does not appear on the entry, it means
that a resource manager exists for the group but does not
require any information for executing a close operation.
The NETGROUPS Section
The NETGROUPS section describes the network groups
available to the application in the LAN environment. Any pair of
machines may be in any number of network groups. Two
communicating nodes use the priority mechanism in order to
determine how to communicate between elements of its group.
Every LMID must be a member of the default network
group, DEFAULTNET. Machines running BEA TUXEDO
releases earlier than Release 6.4 (in which NETGROUPS
became available) can belong only to the DEFAULTNET
network group. The network group number (NETGRPNO) for
DEFAULTNET. is 0 (zero), and may not be changed. The
default priority of DEFAULTNET, however, may be
modified.
The general format for entries in this section is:
NETGROUP required_parameters [ optional_parameters ]
where NETGROUP is the network group name. If NETGROUP
is equal to DEFAULTNET then the entry describes the
default network group.
Required parameters are:
- NETGRPNO = numeric_value
- This is a unique network group number which must be
assigned by the administrator for use in fail-over and
fail-back situations. If this entry describes DEFAULTNET,
then the numeric value must be 0 (zero).
Optional parameters are:
- NETPRIO = numeric_value
- Specifies the priority of this network group. A pair of
machines in multiple network groups of the same priority
will communicate in parallel over the priority band as
long as no network group of a higher priority is
available. If all the network links of a certain priority
band have been torn down by the administrator or by
network conditions, then the next lowest priority band is
used. Retries of the higher priority bands will be
attempted. For more information, see the chapter TUXEDO System
Networks in the BEA TUXEDO Administrator's Guide.
This value must be greater than zero and less than 8192.
If not specified, the default value is 100. Note that this
is the only parameter of the DEFAULTNET which
can be altered.
Note: In Release 6.4, parallel data circuits are
prioritized by network group number (NETGRPNO) within
priority group number. In future releases, a different algorithm
may be used to prioritize parallel data circuits.
The NETWORK Section
The NETWORK section describes the network
configuration for a LAN environment. For each processor on which
a bridge server is located, an entry must be placed in the
network section giving the network address of the bridge process.
An error is generated if this section exists and LAN
is not specified for the OPTIONS parameter of the RESOURCES
section.
The general format for entries in this section is:
LMID required_parameters [optional_parameters]
where LMID is the logical machine where the bridge
process is placed. LMID must have direct access to the
network device to be used (as given in the BRIDGE
parameter).
Required parameters are:
- NADDR = string_value
- Specifies the complete network address to be used by the
bridge process placed on the LMID as its listening
address. The listening address for a bridge is the means
by which it is contacted by other bridge processes
participating in the application. If string_value
has the form ``0xhex-digits'' or ``\\xhex-digits'',
it must contain an even number of valid hex digits. These
forms are translated internally into a character array
containing TCP/IP addresses. The string_value may
also be in either of the following two forms:
"//hostname:port_number"
"//#.#.#.#:port_number"
In the first of these formats, hostname is
resolved to a TCP/IP host address at the time the address
is bound using the locally configured name resolution
facilities accessed via gethostbyname(3c). The "#.#.#.#"
is the dotted decimal format where each #
represents a decimal number in the range 0 to 255. Port_number
is a decimal number in the range 0 to 65535. the
hexadecimal representations of the string specified.
Optional parameters are:
- BRIDGE = string_value
- specifies the device name to be used by the bridge
process placed on that LMID to access the network.
In Release 6.4 (or higher) the BRIDGE
parameter is never required. In prior releases, for
networks that were TLI-based, an absolute pathname for a
device was required as the value of BRIDGE.
The network transport endpoint file path has the form: /dev/provider_name.
For STARLAN this is: /dev/starlan. If your
networking functionality is Sockets-based, this parameter
need not be specified.
- NLSADDR = string_value
- specifies the network address used by the tlisten(1)
process servicing the network on the node identified by
the LMID. The network address used for NLSADDR
is of the same format as that specified for the NADDR
parameter above. If the address has the form ``0xhex-digits''
or ``\\xhex-digits'', it must contain an even
number of valid hex digits. TCP/IP addresses may be in
the "//#.#.#.#:port" format. tmloadcf(1)
prints an error if NLSADDR is missing from any
entry but that for the MASTER LMID, for which
it prints a warning. However, if NLSADDR is
missing from the MASTER LMID entry, tmadmin(1)
will not be able to run in administrator mode on remote
machines; it will be limited to read-only operations.
This also means that the backup site will be unable to to
reboot the master site after failure.
- MINENCRYPTBITS={0|40|128}
- When establishing a network link to this machine, require
at least this minimum level of encryption. "0"
means no encryption, while "40" and
"128" specify the encryption key length (in
bits). If this minimum level of encryption cannot be met,
link establishment will fail. The default value is
"0".
- MAXENCRYPTBITS={0|40|128}
- When establishing a network link, negotiate encryption up
to this level. "0" means no encryption, while
"40" and "128" specify the encryption
length (in bits). The default value is "128".
- NETGROUP = string_value
- string_value is the network group associated with
this network entry. If unspecified, then the default, DEFAULTNET,
is assumed. The NETGROUP parameter, if not set
to DEFAULTNET, must have previously appeared
as a group name in the NETGROUPS section of
the file. All network entries with a NETGROUP
of DEFAULTNET are represented in the T_MACHINE
class of the TM_MIB, while NETWORK
entries associated with any other NETGROUP are
represented in the T_NETMAP class of the TM_MIB
to interoperate with previous releases.
The SERVERS Section
This section provides information on the initial conditions
for servers started in the system. The notion of a server as a
process that continually runs and waits for a server group's
service requests to process, may or may not apply to a particular
remote environment. For many environments, the operating system
or perhaps a remote gateway will be the sole dispatcher of
services; when either of these is the case, only SERVICE
table entries (see next section) and no SERVER table
entries need be specified for remote program entry points; TUXEDO
System/T gateway servers will advertise and queue remote domain
service requests. Host-specific reference pages must indicate
whether or not UBBCONFIG server table entries apply in their
particular environments, and if so, the corresponding semantics.
Lines within the SERVERS section have the form:
AOUT required_parameters [optional_parameters]
where AOUT specifies the file (string_value) to
be executed by tmboot(1).
tmboot executes AOUT on the machine specified
for the server group to which the server belongs. tmboot
searches for the AOUT file on its target machine. Thus, AOUT
must exist in a filesystem on that machine. (Of course, the path
to AOUT can include RFS connections to filesystems on
other machines.) If a relative pathname for a server is given,
the search for AOUT is done first in APPDIR,
then in TUXDIR/bin, then in /bin, and then in
<path> where <path> is the value of the last PATH=
line appearing in the machine environment file, if one exists.
The values for APPDIR and TUXDIR are taken
from the appropriate machine entry in the TUXCONFIG
file. See ENVFILE in the *MACHINES section for a more
detailed discussion.
Required parameters are:
- SRVGRP = string_value
- specifies the name for the group in which the server is
to run. string_value must be the logical name
associated with a server group in the GROUPS
section. It must be 30 characters or less. This
association with an entry in the GROUPS
section means that AOUT is executed on the machine
with the LMID specified for the server group.
It also specifies the GRPNO for the server
group and parameters to pass when the associated resource
manager is opened. All server entries must have a server
group parameter specified.
- SRVID = number
- specifies an integer that uniquely identifies a server
within a group. Identifiers must be between 1 and 30,000.
This parameter must be present on every server entry.
The optional parameters are divided into two categories: boot
options and runtime options. Boot options are used by tmboot(1) when it
executes a server. Once running, a server reads its entry from
the configuration file to determine its runtime options. The
unique server ID is used to find the right entry.
Optional boot parameters are:
- CLOPT = string_value
- specifies servopts(5)
options to be passed to AOUT when booted. If none
is specified, the default is -A. string_value
can be up to 256 characters in length.
- SEQUENCE = number
- specifies when this server should be booted or shut down
relative to other servers. If two servers are given the
same sequence number, it is possible for tmboot
to boot them in parallel and for tmshutdown to
shut them down in parallel. If the SEQUENCE
parameter is not specified, servers are booted in the
order found in the SERVERS section (and shut
down in the reverse order). If a mixture of servers with
and without sequence numbers is given, all servers with
sequence numbers are booted first from low to high
sequence number, then all servers without sequence
numbers are booted in the order they appear in the
configuration file. Sequence numbers must be in the range
between 1 and 9999.
- MIN = number
- specifies the minimum number of occurrences of the server
to be booted by tmboot. If an RQADDR
is specified and MIN is greater than 1, then
the servers will form an MSSQ set. The server identifiers
for the servers will be SRVID up to SRVID
+ MAX - 1. All occurrences of the server will
have the same sequence number, as well as any other
server parameters. If not specified, the default value is
1.
- MAX = number
- specifies the maximum number of occurrences of the server
that may be booted. Initially, tmboot boots MIN
servers; additional servers, up to a maximum of MAX,
may be booted using the -i option to specify
the associated server identifier. If not specified, the
default value is the same as MIN.
Optional runtime parameters are:
- ENVFILE = string_value
- requests the addition of the values in this file to the
environment of the server during its initialization. If a
server is associated with a server group that can be
migrated to a second machine, the ENVFILE must
be in the same location on both machines.
Note that
this file is processed after the server starts.
Therefore, it cannot be used to set the pathnames used to
find executable or dynamically loaded files needed to
execute the server; use the machine ENVFILE
instead. See ENVFILE in the *MACHINES
section for a discussion of how this file is used to
modify the environment.
- CONV = { Y | N }
- specifies whether or not the server is a conversational
server. Connections can only be made to conversational
servers, and rpc requests (via tpacall(3c)
or tpcall(3c))
can only be made to non-conversational servers. The
default value is N.
- RQADDR = string_value
- specifies the symbolic name of the request queue for AOUT.
It must be 30 characters or less. If not specified, a
unique key (GRPNO.SRVID) is chosen for a queue
that AOUT accesses. Specifying the same RQADDR
for more than one server is the way multiple server,
single queue (MSSQ) sets are achieved. If two servers are
given an RQADDR with the same queue name, they
must be in the same server group.
- RQPERM = number
- specifies the numeric permissions on the request queue. number
is specified in the usual UNIX fashion (for example,
0600). If RQPERM is not specified, and a PERM
is specified in the *RESOURCES section, then that value
is used. Otherwise, a value of 0666 is used. relative to APPDIR
(Do not attempt to set a shell variable at the beginning
of the command.) The command name may be optionally
followed by command line arguments. Two additional
arguments are appended to the command line: the GRPNO
and SRVID associated with the restarting
server. string_value is executed in parallel with
restarting the server.
- MAXGEN = number
- If AOUT is restartable, this parameter specifies
that it can be restarted at most number - 1 times
within the period specified by GRACE. The
value must be greater than 0 and less than 256. If not
specified, the default is 1 (which means that the server
can be started once, but not restarted).
- GRACE = number
- If AOUT is restartable, this parameter specifies
that it can have up to MAXGEN lives within the
specified number of seconds. The value must be greater
than or equal to 0 and less than 2147483648. If 0, the AOUT
can be restarted an unlimited number of times. If GRACE
is not specified, the default is 86,400 seconds (24
hours).
- RESTART = { Y | N }
- specifies whether or not AOUT is restartable. The
default is N. If server migration is
specified, RESTART must be set to Y.
Note that a server terminated with a SIGTERM
signal cannot be restarted; it must be rebooted.
- SYSTEM_ACCESS = {FASTPATH | PROTECTED}
- specifies the mode used by System/T libraries within a
server process to gain access to System/T's internal
tables. FASTPATH specifies that System/T's
internal tables should be accessible by System/T
libraries via shared memory for fast access. PROTECTED
specifies that while System/T's internal tables are
accessible by System/T libraries via shared memory, the
shared memory for these tables is not accessible outside
of the System/T libraries. If SYSTEM_ACCESS is
not specified, the default is determined by the setting
of the SYSTEM_ACCESS keyword in the RESOURCES
section.
The SERVICES Section
This section provides information on services used by the
application. Lines within the SERVICES section have
the form:
SVCNM [optional_parameters]
where SVCNM is the (string_value) name of the
service. SVCNM must be 15 characters or fewer in length.
There are no required parameters. Services need not be listed
if no optional parameters are desired. Optional parameters are:
- LOAD = number
- specifies that SVCNM imposes a load on the system
of number. number can be between 1 and
32767 inclusive. If not specified, the default is 50. A
higher number indicates a greater load.
- PRIO = number
- specifies that SVCNM has a dequeueing priority of
the specified number. The value must be greater than 0
and less than or equal to 100, with 100 being the highest
priority. The default is 50.
- SRVGRP = string_value
- This parameter says that any parameters specified apply
to SVCNM within server group string_value.
The use of SRVGRP allows the same service to
have different parameter settings within different server
groups. It must be 30 characters or less.
- BUFTYPE = "type1[:subtype1[,subtype2 .
. . ]][;type2[:subtype3[, . . . ]]] . . .
- is a list of types and subtypes of data buffers accepted
by this service. This parameter can be up to 256
characters in length and a maximum of 32 type/subtype
combinations are allowed. Types of data buffers provided
with TUXEDO System/T are FML (for FML
buffers), VIEW, X_C_TYPE, and X_COMMON
(for FML views), STRING (for
NULL-terminated character arrays), and CARRAY
or X_OCTET (for a character array that is
neither encoded nor decoded during transmission). Of
these types, only VIEW, X_C_TYPE,
and X_COMMON have subtypes. A view subtype
gives the name of the particular view expected by the
service. Application types and subtypes can also be added
(see tuxtypes(5)).
For a TYPE that has subtypes, ``*'' can be
specified for the subtype to indicate that the service
accepts all subtypes for the associated type. A single
service can only interpret a fixed number of buffer
types, namely those found in its buffer type switch (see tuxtypes(5)). If
the BUFTYPE parameter is set to ALL,
that service will accept all buffer types found in its
buffer type switch. Omitting the BUFTYPE
parameter is equivalent to setting it to ALL.
If multiple entries exist for the same service name but
with different SRVGRP parameters, the BUFTYPE
parameter must be the same for all of these entries. A
type name can be 8 characters or less in length and a
subtype name can be 16 characters or less in length. Note
that type and subtype names should not contain semicolon,
colon, comma, or asterisk characters (this will make it
hard to see where type and subtype values end). Some
examples of valid BUFTYPE specifications are: BUFTYPE=FML
implies that the service takes FML buffers. BUFTYPE=VIEW:*
implies that the service takes all FML views.
- ROUTING = string_value
- specifies the name of the routing criterion used for this
service when doing data dependent routing. If not
specified, data dependent routing is not done for this
service. string_value must be 15 characters or
less in length. If multiple entries exist for the same
service name but have different SRVGRP
parameters, the ROUTING parameter must be the
same for all of these entries.
- SVCTIMEOUT = number
- specifies the amount of time, in seconds, that should be
allowed for processing of the indicated service. The
value must be greater than or equal to 0. A value of 0
indicates that the service will not be timed out. A timed
out service will cause the server processing the service
request to be terminated with a SIGKILL
signal. The default value for this parameter is 0.
The following parameters are for DTP applications only:
- AUTOTRAN = { Y | N }
- specifies whether or not a transaction should
automatically be started if a request message is received
that is not already in transaction mode. The default is N.
- TRANTIME = number
- specifies the default timeout value in seconds for a
transaction automatically started for the associated
service. The value must be greater than or equal to 0 and
less than 2147483648. The default is 30 seconds. A value
of 0 implies the maximum timeout value for the machine.
The ROUTING Section
This section provides information for data dependent routing
of service requests using FML buffers and views. The
routing criteria specified here are used only if the default
routing functions, _froute and _vroute, are
being used (see tuxtypes(5)).
Lines within the ROUTING section have the form:
CRITERION_NAME required_parameters
where CRITERION_NAME is the (string_value) name
of the routing entry that was specified on the services entry. CRITERION_NAME
must be 15 characters or less in length.
Required parameters are:
- FIELD = string_value
- specifies the name of the routing field. It must be 30
characters or less. This field is assumed to be an FML
buffer or view field name that is identified in an FML
field table (using the FLDTBLDIR and FIELDTBLS
environment variables) or an FML view table
(using the VIEWDIR and VIEWFILES
environment variables), respectively. This information is
used to get the associated field value for data dependent
routing during the sending of a message. If a field in an
FML32 buffer will be used for routing, it must
have a field number less than or equal to 8191.
- RANGES = "string"
- specifies the ranges and associated server groups for the
routing field. string must be enclosed in double
quotes. string can be up to 2048 characters in
length (except in Domains, where string can be up
to 1024 characters). The format of string is a
comma-separated ordered list of range/group_name pairs
(see EXAMPLE below). A range is either a single value
(signed numeric value or character string in single
quotes), or a range of the form ``lower - upper'' (where
lower and upper are both signed numeric values or
character strings in single quotes). Note that ``lower''
must be less than or equal to ``upper''. To embed a
single quote in a character string value (as in O'Brien,
for example), you must precede it with two backslashes ('O\\'Brien').
The value MIN can be used to indicate the
minimum value for the data type of the associated FIELD
on the machine. The value MAX can be used
to indicate the maximum value for the data type of the
associated FIELD on the machine. Thus,
``MIN - -5'' (MIN to -5) is all
numbers less than or equal to -5 and ``6 - MAX''
(6 to MAX) is all numbers equal to or greater
than 6. The meta-character ``*''
(wild-card) in the position of a range indicates any
values not covered by the other ranges previously seen in
the entry; only one wild-card range is allowed per entry
and it should be last (ranges following it will be
ignored). The routing field can be of any data type
supported in FML. A numeric routing field must
have numeric range values, and a string routing field
must have string range values. String range values for
string, carray, and character field types must be placed
inside a pair of single quotes and can not be preceded by
a sign. Short and long integer values are a string of
digits, optionally preceded by a plus or minus sign.
Floating point numbers are of the form accepted by the C
compiler or atof(): an optional sign, then a
string of digits optionally containing a decimal point,
then an optional e or E, followed by an optional sign or
space, followed by an integer. The group name indicates
the associated group to which the request is routed if
the field matches the range. A group name of ``*''
indicates that the request can go to any group where a
server offers the desired service. Within a range/group
pair, the range is separated from the group name by a ``:''.
- BUFTYPE = "type1[:subtype1[,subtype2
. . . ]][;type2[:subtype3[, . . . ]]] . .
."
- is a list of types and subtypes of data buffers for which
this routing entry is valid. This parameter can be up to
256 characters in length and a maximum of 32 type/subtype
combinations are allowed. The types are restricted to FML,
VIEW, X_C_TYPE, or X_COMMON.
No subtype can be specified for type FML, and
subtypes are required for type VIEW, X_C_TYPE,
and X_COMMON. (``*'' is not allowed.) Note
that subtype names should not contain semicolon, colon,
comma, or asterisk characters. Duplicate type/subtype
pairs can not be specified for the same routing criterion
name; more than one routing entry can have the same
criterion name as long as the type/subtype pairs are
unique. This parameter is required. If multiple buffer
types are specified for a single routing entry, the data
types of the routing field for each buffer type must be
the same.
An example of a routing entry is:
BRNCH FIELD=B_FLD RANGES="0-2:DBG1,3-5:DBG2,6-9:DBG3" BUFTYPE="FML"
which sends buffers with field B_FLD values 0-2 to
server group DBG1, values 3-5 to server group DBG2,
and values 6-9 to DBG3; no other values are allowed.
If the field value is not set (for FML buffers), or
does not match any specific range and a wild-card range has not
been specified, an error is returned to the application.
FILES
The TUXCONFIG and TUXOFFSET environment
variables are used to find the TUXCONFIG configuration
file on the MASTER machine.
EXAMPLE
# The following configuration file defines a 2-site
# configuration with two machine types. Data dependent
# routing is used.
*RESOURCES
IPCKEY 80952 # key for well known address
DOMAINID My_Domain_Name
UID 4196 # user id for ipc structures
GID 601 # group id for ipc structures
PERM 0660 # permissions for ipc access
MAXSERVERS 20 # at most 20 simultaneous servers
MAXSERVICES 40 # offering at most 40 services
MAXGTT 20 # at most 20 simultaneous global transactions
MASTER SITE1
SCANUNIT 10
SANITYSCAN 12
BBLQUERY 180
BLOCKTIME 30
DBBLWAIT 6
NOTIFY DIPIN
OPTIONS LAN,MIGRATE
SECURITY USER_AUTH
AUTHSVC AUTHSVC
MODEL MP # a multiprocessor based bulletin board
LDBAL Y # perform load balancing
#
*MACHINES
mach1 LMID=SITE1 TUXDIR="/usr4/tuxbin"
MAXACCESSERS=25
APPDIR="/usr2/apps/bank"
ENVFILE="/usr2/apps/bank/ENVFILE"
TLOGDEVICE="/usr2/apps/bank/TLOG" TLOGNAME=TLOG
TUXCONFIG="/usr2/apps/bank/tuxconfig" TYPE="3B2"
ULOGPFX="/usr2/apps/bank/ULOG"
SPINCOUNT=5
mach386 LMID=SITE2 TUXDIR="/usr5/tuxbin"
MAXACCESSERS=100
MAXWSCLIENTS=50
APPDIR="/usr4/apps/bank"
ENVFILE="/usr4/apps/bank/ENVFILE"
TLOGDEVICE="/usr4/apps/bank/TLOG" TLOGNAME=TLOG
TUXCONFIG="/usr4/apps/bank/tuxconfig" TYPE="386"
ULOGPFX="/usr4/apps/bank/ULOG"
#
*GROUPS
DEFAULT: TMSNAME=TMS_SQL TMSCOUNT=2
# For NT/NetWare, :bankdb: becomes ;bankdb;
BANKB1 LMID=SITE1 GRPNO=1
OPENINFO="TUXEDO/SQL:/usr2/apps/bank/bankdl1:bankdb:readwrite"
# For NT/NetWare, :bankdb: becomes ;bankdb;
BANKB2 LMID=SITE2 GRPNO=2
OPENINFO="TUXEDO/SQL:/usr4/apps/bank/bankdl2:bankdb:readwrite"
DEFAULT:
AUTHGRP LMID=SITE1 GRPNO=3
#
*NETWORK
SITE1 NADDR="mach1.80952" BRIDGE="/dev/starlan"
NLSADDR="mach1.serve"
#
SITE2 NADDR="mach386.80952" BRIDGE="/dev/starlan"
NLSADDR="mach386.serve"
*SERVERS
#
DEFAULT: RESTART=Y MAXGEN=5 REPLYQ=Y CLOPT="-A"
TLR SRVGRP=BANKB1 SRVID=1 RQADDR=tlr1
CLOPT="-A -- -T 100"
TLR SRVGRP=BANKB1 SRVID=2 RQADDR=tlr1
CLOPT="-A -- -T 200"
TLR SRVGRP=BANKB2 SRVID=3 RQADDR=tlr2
CLOPT="-A -- -T 600"
TLR SRVGRP=BANKB2 SRVID=4 RQADDR=tlr2
CLOPT="-A -- -T 700"
XFER SRVGRP=BANKB1 SRVID=5
XFER SRVGRP=BANKB2 SRVID=6
ACCT SRVGRP=BANKB1 SRVID=7
ACCT SRVGRP=BANKB2 SRVID=8
BAL SRVGRP=BANKB1 SRVID=9
BAL SRVGRP=BANKB2 SRVID=10
BTADD SRVGRP=BANKB1 SRVID=11
BTADD SRVGRP=BANKB2 SRVID=12
AUTHSVR SRVGRP=AUTHGRP SRVID=20
#
*SERVICES
DEFAULT: LOAD=50 AUTOTRAN=N
WITHDRAWAL PRIO=50 ROUTING=ACCOUNT_ID
DEPOSIT PRIO=50 ROUTING=ACCOUNT_ID
TRANSFER PRIO=50 ROUTING=ACCOUNT_ID
INQUIRY PRIO=50 ROUTING=ACCOUNT_ID
CLOSE_ACCT PRIO=40 ROUTING=ACCOUNT_ID
OPEN_ACCT PRIO=40 ROUTING=BRANCH_ID
BR_ADD PRIO=20 ROUTING=BRANCH_ID
TLR_ADD PRIO=20 ROUTING=BRANCH_ID
ABAL PRIO=30 ROUTING=b_id
TBAL PRIO=30 ROUTING=b_id
ABAL_BID PRIO=30 ROUTING=b_id
TBAL_BID PRIO=30 ROUTING=b_id SVCTIMEOUT=300
#
#
*ROUTING
ACCOUNT_ID FIELD=ACCOUNT_ID BUFTYPE="FML"
RANGES="MIN - 9999:*,10000-59999:BANKB1,60000-109999:BANKB2,*:*"
BRANCH_ID FIELD=BRANCH_ID BUFTYPE="FML"
RANGES="MIN - 0:*,1-5:BANKB1,6-10:BANKB2,*:*"
b_id FIELD=b_id BUFTYPE="VIEW:aud"
RANGES="MIN - 0:*,1-5:BANKB1,6-10:BANKB2,*:*"
INTEROPERABILITY
In an interoperating application, the master site must be
running the latest release available. Parameter values for PMID
(machine ADDRESS), LMID, TLOGNAME, group
names, RQADDR, service names, and ROUTING
(routing criterion names) must be valid C identifiers (that are
not UBBCONFIG keywords) when interoperating with System/T.
NETWORK ADDRESSES
Suppose the local machine on which the bridge is being run is
using TCP/IP addressing and is named backus.company.com,
with address 155.2.193.18. Further suppose that the
port number at which the bridge should accept requests is 2334.
Assume that port number 2334 has been added to the
network services database under the name bankapp-naddr.
The address specified by the -l option could be
represented in the following ways:
//155.2.193.18:bankapp-naddr
//155.2.193.18:2334
//backus.company.com:bankapp-naddr
//backus.company.com:2334
0x0002091E9B02C112
The last of these representations is hexadecimal format. The 0002
is the first part of a TCP/IP address. The 091E is the
port number 2334 translated into a hexadecimal number.
After that each element of the IP address 155.2.193.12
is translated into a hexadecimal number. Thus the 155
becomes 9B, 2 becomes 02 and so
on.
SEE ALSO
buildserver(1),
tmadmin(1),
tmboot(1),
tmshutdown(1),
tmloadcf(1),
tmunloadcf(1),
tpinit(3c),
buffer(3),
protocol(3I),
servopts(5), BEA TUXEDO Administrator's Guide
BEA TUXEDO Programmer's
Guide