[Top]
[Previous Page] [Next Page] [Bottom]
To help you identify error conditions quickly and accurately, the BEA TUXEDO system provides you with two log files:
ULOG
)-a log
of messages generated by the BEA TUXEDO system while your application is running. TLOG
)-a
binary file that is not normally read by you (the administrator), but that is used by the
Transaction Manager Server (TMS). A TLOG
is created only on machines involved in BEA TUXEDO global transactions. These two logs are maintained and updated constantly while your application is running.
This chapter discusses the following topics:
The user log (ULOG
)
is a central event logger. All messages generated by the BEA TUXEDO system-error messages,
warning messages, information messages, and debugging messages-are written to this log.
Application clients and servers can also write to the user log.
A new log is created every day and there can be a different log on each machine.
However, a ULOG
can be
shared across machines when a remote file system is being used.
The purpose of the ULOG
is to give you, the administrator, a record of the events on your system from which you
can determine the cause of most BEA TUXEDO system and application failures.
The ULOG
is created
by the BEA TUXEDO system whenever one of the following events occurs:
You can view the ULOG
,
an ASCII file, with any text editor.
When a message is written to the ULOG
through the tperrno
global variable, application clients and servers are notified, as follows:
tperrno
is set to TPESYSTEM
after returning from an
ATMI call, you can conclude that: tperrno
is set to TPEOS
after returning from an ATMI
call, you can conclude that: A ULOG
message
consists of two parts: a tag and text. Each part consists of three strings, as shown in
the following table.
Consider the following example of a user log message.
121449.gumby!simpserv.27190: LIBTUX_CAT:262: std main starting
From the message tag we learn:
gumby
. simpserv
process (which has an ID of 27190). From the message text we learn:
LIBTUX
catalog. std
main starting.
For more information about a message, note its catalog name and catalog number. With this information you can look up the message in the BEA TUXEDO System Message Manual, which provides complete descriptions of all system messages.
By default, the user log is called ULOG.mmddyy
(where mmddyy
represents the date in terms of month, day, and year) and it is created in the $APPDIR
directory.
You can place this file in any location, however, by setting the ULOGPFX
parameter in the MACHINES
section.
tlisten
is the
section of the ULOG
in
which error messages for the tlisten
process are recorded. (The tlisten
process provides remote service connections for other machines.) As part of the ULOG
file, a tlisten
log can be viewed with any
text editor.
Each machine, including the master machine, should have a tlisten
process running on it.
Separate tlisten
logs
are maintained in the ULOG
on each machine. However, they can be shared across remote file systems.
The tlisten
log is a
record of tlisten
process failures. It is used, during the boot process, by tmboot
and, while an application is
running, by tmadmin
.
The tlisten
log is
created by the tlisten
process as soon as that process is started. Whenever a tlisten
process failure occurs, an
appropriate message is recorded in the tlisten
log.
Each tlisten
log
message includes the date and time at which the message was added to the log.
By default, the tlisten
log resides in $TUXDIR/udataobj
.
You can store it in another location, however, by entering the following command.
tlisten -Lnew_pathname
For example, if you want your TLOG
file to be named TLLOG
and to reside in the /home/apps/logs
directory, enter the following command.
tlisten -L /home/apps/logs/TLOG
The transaction log (TLOG
)
keeps track of global transactions during the commit phase. A global transaction is
recorded in the TLOG
only when it is in the process of being committed. The TLOG
is used to record the reply
from the global transaction participants at the end of the first phase of a
two-phase-commit protocol. The TLOG
records the decision about whether a global transaction should be committed or rolled
back.
We recommend that you create a TLOG
on each machine that participates in global transactions.
For instructions on creating a TLOG
,
see the section
The TLOG
file is used
only by the Transaction Manager Server (TMS) that coordinates global transactions. It is
not read by the administrator.
The location and size of the TLOG
are specified by four parameters that you set in the MACHINES
section of the UBBCONFIG
file: TLOGDEVICE
, LOGOFFSET
, TLOGNAME
, and TLOGSIZE
. (For descriptions of these
parameters and instructions for assigning values to them, see
The ULOG
is generated
by various BEA TUXEDO system processes; you do not need to create it. The TLOG
, however, is not produced
automatically; you must create it.
This section provides the following instructions:
ULOG
TLOG
s To override the default location for your ULOG
file, specify the desired location as the value of the ULOGPFX
parameter in the MACHINES
section of the UBBCONFIG
file. (By default, the
value of ULOGPFX
is $APPDIR/ULOG
.) The value you assign
becomes the first part of the ULOG
file name.
Listing 13-1 Overriding Default Settings in the
MACHINES
Section of YourUBBCONFIG
File
MACHINES gumby LMID=SITE1 TUXDIR="/usr/tuxedo" APPDIR="/home/apps" TUXCONFIG="/home/apps/tuxconfig" ULOGPFX="/home/apps/logs/ULOG" ...
The following ULOG
was created for SITE1
on
04/13/98.
/home/apps/logs/ULOG.041398
To create a TLOG
, you
must complete the following procedure:
This section provides instructions for each step.
Your first step is to assign values to four parameters in the MACHINES
section of the UBBCONFIG
file: TLOGDEVICE
, TLOGNAME
, TLOGOFFSET
, and TLOGSIZE
.
TLOGDEVICE
TLOGDEVICE
specifies
the device in the BEA TUXEDO file system that contains the transaction log. This can be
the same device used by TUXCONFIG
.
Note: Technically, there is no reason that TLOGDEVICE
cannot be a separate VTOC
file, but there are two reasons why it is not recommended: the TLOG
is generally too small to
justify devoting a raw disk segment to it, and creating TLOGDEVICE
as a UNIX file leads to
expensive delays when synchronous writes to the TLOG
are required.
The TLOG
is stored as
a BEA TUXEDO system VTOC table on the device named in this parameter. If the TLOGDEVICE
parameter is not
specified, there is no default; the BEA TUXEDO system assumes that no TLOG
exists for the machine. If no TLOG
exists for a given machine, the
associated LMID
cannot
be used by server groups that participate in distributed transactions.
After TUXCONFIG
has
been created via tmloadcf
,
you must create a device list entry for the TLOG
on each machine for which TLOGDEVICE
is specified. This is
done using the tmadmin crdl
command. The BBL creates the log automatically the first time the system is booted.
TLOGNAME
TLOGNAME
specifies the
name of the Distributed Transaction Processing (DTP) transaction log for this machine. The
default name is TLOG
. If
more than one transaction log exists on the same TLOGDEVICE
, each transaction log must have a unique name. If a
name is specified, it must not conflict with any other table specified on the
configuration. TLOGOFFSET
TLOGOFFSET
specifies
the offset in pages from the beginning of TLOGDEVICE
to the start of the VTOC that contains the transaction
log for this machine. The number must be greater than or equal to 0 and less than the
number of pages on the device. The default value is 0. TLOGOFFSET
is rarely necessary.
However, if two VTOCs share the same device or if a VTOC is stored on a device (such as a
file system) that is shared with another application, TLOGOFFSET
can be used to indicate a
starting address relative to the address of the device.
TLOGSIZE
TLOGSIZE
specifies the
number of pages for the TLOG
.
The default is 100 pages. Once a global transaction is complete, TLOG
records are no longer needed
and are thrown away. The maximum number of pages that can be specified, subject to the
amount of available space on TLOGDEVICE
,
is 2048 pages. Choosing a value is entirely application-dependent. Listing 13-2 Sample Transaction Log Parameters for a Specified Machine
MACHINES gumby LMID=SITE1 ... TLOGDEVICE="/home/apps/logs/TLOG" TLOGNAME=TLOG TLOGOFFSET=0 TLOGSIZE=100 ...
Next, create an entry in the Universal Device List (UDL) for the TLOGDEVICE
on each machine that
requires a TLOG
. You can
perform this step either before or after TUXCONFIG
has been loaded, but you must do it before the system is
booted.
To create an entry in the UDL for the TLOG
device, complete the following procedure.
tmadmin -c
You do not have to createTLOG
s on any machine other than the master machine. The BEA TUXEDO system createsTLOG
s on nonmaster machines (as long as a UDL exists on those machines) when the application is booted.
crdl -zconfig
-bblocks
-z
config
specifies the full path
name for the device on which the UDL should be created (and where the TLOG
will reside). -b
specifies the
number of blocks to be allocated on the device. config
should
match the value of the TLOGDEVICE
parameter in the MACHINES
section. If config
is not specified, it defaults to the value of FSCONFIG
(a BEA TUXEDO system environment variable). Note: If the TLOGDEVICE
is mirrored between two
machines, Step 3 is not required on the paired machine.
During the boot process, the Bulletin Board Listener (BBL) initializes and opens the TLOG
.
In Step 2, you created a new BEA TUXEDO file system that can be used to hold the TLOG
. Sometimes, however, it is
necessary to add new devices or space to an existing configuration or to check space
usage. You can perform these tasks by running the command.
tmadmin -c
(You can run this command whether or not the system is booted.)
It is possible that the UDL exists on config
but does not have sufficient space for the log. To
allocate space on a new device to an existing BEA TUXEDO file system, enter the following.
crdl -zconfig
-bblocks
new_device
where new_device
specifies the full path name for the new device on which space is to be allocated. This
command creates a new entry on the UDL and makes the space available for any tables that
are created on config.
(For example, this procedure can be used for the TUXCONFIG
file when there is not enough space for a modified
configuration, for allocating a new TLOG
,
or for increasing the size of the TLOG
by deleting an old log and then creating a larger one.) If you are running several
commands using the current configuration, it is possible to set the default configuration
by entering the default
command (d
), as follows:
d -zconfig
If you run this command, you will not need to enter the -z
option after each command.
Under rare circumstances, a device does not start at offset 0. This might happen if space has been allocated on a device (less than the entire device) to a BEA TUXEDO file system, and more space on the same device is available to be allocated. In this case, you can allocate the second entry by entering the following command.
crdl -zconfig
-bblocks
-onew_device_offset
new_device
Here, new_device_offset
specifies the offset of the new space being allocated on the device. (Note that the option
is a lowercase o.
) In
this case, since the first entry on the UDL is allocated at offset 0, TLOGOFFSET
and/or TUXOFFSET
are set to 0, instead of
to the offset of the new device. (The BEA TUXEDO system needs to find the UDL, from which
it can determine the offset of other available space.)
A second (and rarer) reason that a device does not start at offset 0 is that a single raw device is shared. This happens, for example, if a UNIX file system is followed by a BEA TUXEDO file system on the same device. (This situation is risky because the raw device must be writable by the BEA TUXEDO system administrator and it is possible to overwrite the UNIX file system.) If the first entry on the UDL does not start at offset 0 (as in this example), the device offset must be specified everywhere that the device is referenced. To allocate the entry, enter the following command.
crdl -zconfig
-bblocks
-ooffset
-Ooffset
new_device
Here, offset
is the offset of the space to be allocated for the BEA TUXEDO file system (UDL and
tables). Note that the -o
(lowercase o) specifies the offset of the UDL and -O
(uppercase O) specifies the
offset of the new device space being allocated. Any devices that are created subsequently
on this configuration must use both the -o
option with the offset of the first entry, and the -O
option with the offset of the new
entry. (The offset may be 0 if a new device is being specified.) If the first entry on the
UDL is not allocated at offset 0, TLOGOFFSET
and/or TUXOFFSET
must be
set to the offset of the first entry. This is the only case in which TLOGOFFSET
and TUXOFFSET
must be set in the UBBCONFIG
file, and the TUXOFFSET
environment variable must
be set when all BEA TUXEDO application and administrative processes are being run.
To list the current UDL, enter the following command.
lidl -zconfig
where config
was created using the above procedures. If the first entry was created with an offset
other than 0, -o
offset
must be specified in
addition to the configuration device. In verbose mode, this command lists not only the
space initially allocated for each device entry, but also the amount of free space.
It is also possible to generate a list of the tables on the configuration by entering the following command.
livtoc -zconfig
Here config
was creating using the above procedures. If the first entry was created with an offset
other than 0, -o
offset
must be specified in
addition to the configuration device. This command lists the table name, device number,
offset within the device, and number of pages for each table. The first two tables are
always VTOC and UDL. TUXCONFIG
table names are of the form _secname_SECT
,
where secname
is the name of a section in the UBBCONFIG
file. The TLOG
table
name is based on the TLOG
parameter in the UBBCONFIG
file, and defaults to TLOG
.
In the rare case in which two applications share a single BEA TUXEDO file system for the TLOGDEVICE
, the TLOG
parameter must be different for
each application.
Note: A BEA TUXEDO system file system is a file that is managed by BEA
TUXEDO, which may be located on a raw disk or in an operating system file system. A BEA
TUXEDO system file system contains one TUXCONFIG
file and one or more TLOG
files.
Because the table names for the TUXCONFIG
file are fixed, it is not possible for two applications to share the same BEA TUXEDO file
system for the TUXCONFIG
file.
Perform the following steps to create the log.
TUXCONFIG
file. (If you do not, the commands for creating the TLOG
will fail.) tmadmin
session by entering the following command. tmadmin -c
tmadmin
command
prompt (>
), enter the
following. crlog [-m machine]
where the value of machine
is the LMID
of a machine, as specified in TUXCONFIG
.
Note: The -m
option is shown as optional because it can be specified with the default
(d
) command of tmadmin
. If you have not specified a
machine with the d
command, however, the -m
option is required on the crlog
command line.
TLOGs require little maintenance. This section provides instructions for two common maintenance tasks: reinititalizing a TLOG and removing a TLOG:
TLOG
,
enter the following. inlog [-yes] [-m machine]
The value of machine
is the LMID
of a machine, as specified in TUXCONFIG
.
Be careful when using this command: it will reinitialize the log even if there are
outstanding transactions. The result could be inconsistent TLOG
s, possibly causing transactions
to abort.
TLOG
,
enter the following. dslog [-yes] [-m machine]
The value ofmachine
is theLMID
of a machine, as specified inTUXCONFIG
.
If the application is not active or if there are transactions still outstanding in the log, an error will be returned.
Note: The -yes
and -m
options are shown as optional
because they can be specified with the default
(d
) command. If you have
not specified a machine with the d
command, however, the -m
option is required on the inlog
and dslog
command lines.
The BEA TUXEDO log files can help you detect failures in both your application and your system. This section provides instructions for analyzing the data in the logs.
Note: Although application administrators are responsible for analyzing user logs, application programmers may also consult the logs.
It is not unusual for multiple messages to be placed in the user log for a given problem. In general, the earlier messages will better reflect the exact nature of the problem.
Consider the example shown in
Listing 13-3. Notice howLIBTUX_CAT
message 358 identifies the exact nature of the problem causing problems reported in
subsequent messages, namely, that there are not enough UNIX system semaphores to boot the
application.
Listing 13-3 Sample ULOG Messages
151550.gumby!BBL.28041: LIBTUX_CAT:262: std main starting 151550.gumby!BBL.28041: LIBTUX_CAT:358: reached UNIX limit on semaphore ids 151550.gumby!BBL.28041: LIBTUX_CAT:248: fatal: system init function ... 151550.gumby!BBL.28040: CMDTUX_CAT:825: Process BBL at SITE1 failed ... 151550.gumby!BBL.28040: WARNING: No BBL available on site SITE1. Will not attempt to boot server processes on that site.
See the BEA TUXEDO System Message Manual for complete descriptions of user log messages and recommendations for any actions that should be taken to resolve the problems indicated.
Keep the following guidelines in mind as you check the tlisten
messages in your ULOG
:
tlisten
log every time the log is contacted. tlisten
messages in your ULOG
file, one of the following
problems may have occurred: tlisten
process
may not have been started. tlisten
process
may be listening on the wrong network address. To find out whether one of these errors has occurred, check the ULOG
file.
Note: Application administrators are responsible for analyzing the tlisten
messages in the ULOG
, but programmers may also find
it useful to check these messages.
The CMDTUX
catalog in
the BEA TUXEDO System Message Manual contains the following information about tlisten
messages:
Consider the following example of a message in a tlisten
log.
042398; 27909;CMDTUX_CAT: 615 INFO: Terminating tlisten process
This message was recorded on April 23, 1998. Its purpose is simply to provide
information: the tlisten
process is being terminated. No action is required.
Note: This message can be found in the CMDTUX
catalog of the BEA TUXEDO
System Message Manual.
The TLOG
is a binary
file that contains only messages about global transactions that are in the process of
being committed. You should never need to examine this file.
If you do need to view the TLOG
,
you must first convert it to ASCII format so that it is readable. The BEA TUXEDO system
provides two tmadmin
operations for this purpose:
dumptlog
(dl
) downloads (or dumps) the TLOG
(a binary file) to an ASCII
file. loadtlog
uploads (or
loads) an ASCII version of the TLOG
into an existing TLOG
(a
binary file). The dumptlog
and loadtlog
commands are also useful
when you need to move the TLOG
between machines as part of a server group migration or machine migration.
[Top] [Previous Page] [Next Page] [Bottom]