Last updated: 96-06-28
Trademark notices:
Stratus, Continuum, Continuous Processing, StrataNET, FTX, and the
Stratus logo are registered trademarks of Stratus Computer, Inc.
XA, XA/R, StrataLINK, RSN, SINAP, Isis, Isis Distributed, RADIO, and
the SQL/2000 logo are trademarks of Stratus Computer, Inc.
PUBLICATIONS tpf.doc FILE
Copyright (C) 1996 by Stratus Computer, Inc.
Introduction
============
This document describes features that have been added to the Transaction
Processing Facility (TPF) since the following manuals were last revised.
o
o
o
o
(R036)
o
o
o
VOS
VOS
VOS
VOS
PL/I Transaction Processing Facility Reference Manual (R015)
BASIC Transaction Processing Facility Reference Manual (R032)
COBOL Transaction Processing Facility Reference Manual (R034)
FORTRAN Transaction Processing Facility Reference Manual
VOS Pascal Transaction Processing Facility Reference Manual (R038)
VOS C Transaction Processing Facility Reference Manual (R069)
VOS Transaction Processing Facility Guide (R215)
This document describes the following topics.
o
It describes the subroutine s$get_server_queue_info that was
introduced in VOS Release 10.2. The subroutine returns
information about the number of messages in an open one-way or
two-way server queue attached to a specified port.
o
It describes enhancements to the tp_restore command that were
introduced in the following VOS releases: 11.7 and 12.
The tp_restore command restores transaction files.
o
It describes a new error message added to the
s$set_transaction_file subroutine and the set_transaction_file
command. The new message supports the implementation of logprotected files in Release 12.
o
It describes the subroutine s$msg_open_virtual that was
introduced in VOS Release 12.0. The subroutine creates a new
kind of queue called a virtual queue.
o
It describes TPOverseer performance improvements and a new
error message, both of which were introduced in VOS
Release 12.3.0 and Release 13.1.0.
o
o
Release
It describes additional TPF performance improvements for
Releases 12.3.0, 13.1.0, and 13.3.0.
It describes a new error message which was introduced in
13.1.0 and two new error messages which were introduced in VOS
Releases 12.3.0 and 13.3.0
o
It describes changes to the tp_overseer command and five
new TPF-related requests of the analyze_system command for
Releases 12.3.0 and 13.3.0.
Contents
The s$get_server_queue_info Subroutine
Enhancements to the tp_overseer Command
Enhancements to the tp_restore Command
The tp_restore Command
Messages in the tp_restore Output File
Determining Which Log Files to Use in the Restore Process
New Error Code for s$set_transaction_file and set_transaction_file
Virtual Queues
TPOverseer Performance Improvements (13.1.0)
TPOverseer Performance Improvements (13.3.0)
New TPOverseer Error Message (13.1.0)
New TPOverseer Error Messages (13.3.0)
New TPF-Related Requests of the analyze_system Command
The s$get_server_queue_info Subroutine
======================================
Purpose
------The s$get_server_queue_info subroutine returns information
about the number of messages in an open one-way or two-way server
queue attached to a specified port.
PL/I Usage
---------declare port_id
declare 1 queue_info
fixed bin (15);
longmap,
2 version
2 file_organization
2 num_messages
2 num_non_busy_messages
2 highest_num_messages
2 total_num_messages
2 max_messages
declare error_code
fixed
fixed
fixed
fixed
fixed
fixed
fixed
fixed
bin(15),
bin(15),
bin(31),
bin(31),
bin(31),
dec(18),
bin(31);
bin(15);
declare s$get_server_queue_info entry (fixed bin(15),
1 like queue_info,
fixed bin(15));
call s$get_server_queue_info (port_id, queue_info, error_code);
C Usage
------struct decimal_18_tag
{
long int
unsigned long int
};
high;
low;
short int
port_id;
struct $longmap
{
short int
short int
long int
long int
long int
struct decimal_18_tag
long int
}
version;
file_organization;
num_messages;
num_non_busy_messages;
highest_num_messages;
total_num_messages;
max_messages;
queue_info;
short int
error_code;
void s$get_server_queue_info();
s$get_server_queue_info( &port_id,
&queue_info,
&error_code);
Arguments
--------port_id (input)
The identifier of a port attached to a one-way or two-way
server queue.
queue_info (input-output)
Information about the number of messages in the queue.
version (input)
The version number of the queue_info structure. Assign it
the value 1. This is the only input argument in queue_info.
file_organization (output)
The organization of the file. Possible values are shown below.
Value
Organization
5
31
two-way server queue
one-way server queue
num_messages (output)
The number of messages currently in the queue.
For one-way server queues, this is the number of messages
which have not been received by the receiver.
For two-way server queues, this is the number of messages
for which replies have not been received by the requester.
In both cases, num_messages is reset to zero when all
openers of the queue have closed their attached ports.
num_non_busy_messages (output)
The number of messages that have been sent and not yet
received.
For one-way server queues, once a message has been received,
it is no longer in the queue. When a message is received,
num_non_busy_messages is decremented.
For two-way server queues, a message can be in the queue and
can be nonbusy. When a message is received,
num_non_busy_messages is decremented. If
s$msg_cancel_receive is called, num_non_busy_messages is
incremented.
highest_num_messages (output)
The highest number of messages that have been in the queue
at one time. This is the highest value that num_messages
has reached. If the value of num_messages is reduced, the
value of highest_num_messages does not change.
total_num_messages (output)
The total number of messages that have been sent during the
opening of the queue.
max_messages (output)
The maximum number of messages that can be sent to this
queue. This is the same as max_queue_depth. See additional
information in the descriptions of the set_max_queue_depth
command and the s$set_max_queue_depth subroutine in the VOS
Transaction Processing Facility manuals.
error_code (output)
A returned error code. The following table describes the
error codes that may be returned by this subroutine.
Error Code
Description
e$portname_not_found
The specified port has not been
attached.
(1028)
e$invalid_io_operation
(1040)
You are attempting to get server queue
information via a port that is not
attached
to an open one-way or two-way server
queue.
e$wrong_version
(1083)
The caller specified the wrong version
number in queue_info.version. The only
correct number is 1.
Enhancements to the tp_overseer Command
=======================================
The tp_overseer command has two new arguments, -metering and
-max_metering. The -metering argument, which specifies the current
setting, is a cycle field with the following values: none, basic, queue,
or extended. The -max_metering argument, which specifies the maximum
allowable value you can give without restarting the TPOverseer, is a
cycle
field with the following values: queue or extended. The values have the
following meanings.
o The none value indicates that metering is not enabled.
o The basic value enables basic metering, which enables you to
increment
counter-type meters; maintenance of these meters is generally
inexpensive.
o The queue value enables queue metering, which enables you to
gather
queue statistics for actual and pseudo queues. (Pseudo queues
provide
a view of a transaction that often corresponds more closely to a
user's perspective than does an actual queue.) The overhead of
performing queue metering is somewhat more expensive because it
involves reading the system clock; therefore, you may want to
disable
queue metering in performance-critical situations.
o The extended value enables extended metering, which records the
maximum values of queue meters and other per-transaction values
over a
given time interval. You can then display this information by
using
the transaction_meters request of the analyze_system command.
Extended
metering requires no additional clock reading but does require
additional space in the Transaction State Info (TSI) structure.
(The
TSI structure, which exists from the time at which a transaction
is
started until all file records modified within the transaction
physically exist on disk, contains various information about the
transaction and its current state.) Once you specify the maximum
value, you cannot specify a higher value unless you restart the
TPOverseer. The extended value is the default value for the metering
and -max_metering arguments.
Enhancements to the tp_restore Command
======================================
The enhancements described in this section apply to VOS releases 11.7,
11.8, and 12, and later.
An online transaction processing application must be able to recover
its data files when unforeseen events, such as accidents, fire, or
serious
failure, destroy the files. For transaction files, the tp_restore
command
provides this capability.
If you use tp_restore infrequently as a tool to recover damaged or lost
files, you can continue to use it the way you always have. You might
notice the following changes.
to
o
Two new arguments appear in the tp_restore command. Both
arguments are optional and are described in this document.
o
New output messages appear in the tp_restore output file.
document describes these messages.
o
You do not need as many log files as were previously required
This
successfully restore transaction files.
This document
describes
a new strategy for determining the starting log file.
If you use tp_restore frequently to perform serial restores (for example,
to maintain secondary online copies of an application's data files), you
will notice that tp_restore is more flexible. This document describes
the
tp_restore enhancements.
The tp_restore Command
---------------------Purpose
This command uses a transaction log to reconstruct a later state of
a
file from an earlier state.
Display Form
----------------------------- tp_restore ------------------------------path_names:
-restore_dir: >system>tcf_directory
-to_state:
current_date_time
-destination:
-control:
-gather_txns: 50
-continuation: no
Command Line Form
tp_restore {path_names}...
[-restore_dir path_name]
[-to_state date/time]
[-destination path_name]
[-control control_file]
[-gather_txns number]
[-continuation]
Arguments
path_names
[-restore_dir path_name]
[-to_state date/time]
[-destination path_name]
[-control control_file]
These arguments have not changed. See the VOS Transaction
Processing Facility Reference Manuals for information about
these
arguments.
[-continuation]
An argument to start the tp_restore session at the point where
a
previous tp_restore session stopped.
This argument supports
serial
executions of the tp_restore command.
Omit this argument if you are not doing serial executions of
tp_restore.
[-gather_txns number]
An argument to specify how many transactions the tp_restore
command
should process before clearing the user heap.
The value must
be
an integer between 10 and 50, inclusive.
50.
The default value is
In general, use the default value. If a tp_restore process
terminates abnormally because of a shortage of user heap space,
reconstruct the destination directory and then reissue the
tp_restore command, specifying a lower number for this
argument.
Explanation
This section explains the two new arguments. See the
Explanation
section in the VOS Transaction Processing Facility Reference
Manuals for explanations of other arguments. See the VOS
Transaction Processing Facility Guide (R215) for a detailed
explanation on how to use the tp_restore command.
The -gather_txns argument provides the flexibility necessary to
handle large transactions. In most cases, you can allow the
-gather_txns argument to use its default value. For processing
efficiency, the tp_restore command gathers information about
multiple transactions and stores this information in the user
heap area of memory. When it accumulates the number of
transactions specified in the -gather_txns argument, the
tp_restore command applies those transactions to the
appropriate
files and clears the user heap before starting to gather more
transactions.
Depending on the number of transaction files involved in the
transactions, as well as the number of modules, the number of
log
files involved, and the available resources in the user heap,
tp_restore might run out of user heap space before it completes
its information-gathering step. In that case, reconstruct the
destination directory and then reissue the tp_restore command
using a lower value in the -gather_txns argument.
The -continuation argument provides support for serial
executions
of the tp_restore command. Whenever the tp_restore command
executes, it saves information about its stopping point in a
file
named tp_restore_continuation_info in the restore directory.
The
command also adds a message to its .out file naming the
starting
log for the next tp_restore session. To perform serial
tp_restore sessions, use the log file identified in the
previous
session's .out file as the starting log for the next session
and
specify the -continuation argument in the next tp_restore
command.
The -continuation argument causes the tp_restore command to use
the
tp_restore_continuation_info file to determine the starting
point
for each of the data files in the destination directory.
For serial tp_restore sessions, you must use log files with
names
whose numbers sequentially follow the logs used in the previous
tp_restore session, with some overlap. Since the overlap
requirement varies, always start with the log file named in the
previous session's .out file. For example, assume that the log
files used in a tp_restore session were named as follows:
tlf.128-1.0000000003.93-01-27
tlf.128-1.0000000004.93-01-27
tlf.128-1.0000000005.93-01-27
Now assume that the tp_restore .out file included the following
message:
To restore files from module 1 in the next tp_restore
-continuation session, you should start with log
tlf.128-1.0000000003.93-01-27
In that case, the next tp_restore session must include the
first
three files in the following list, and could have any number of
subsequently numbered log files as well. The next tp_restore
session might use the following log files.
tlf.128-1.0000000003.93-01-27
tlf.128-1.0000000004.93-01-27
tlf.128-1.0000000005.93-01-27
tlf.128-1.0000000006.93-01-27
tlf.128-1.0000000007.93-01-27
You should use the same restore directory for all executions of
the tp_restore command in the series. Otherwise, you risk
accessing incorrect continuation information.
If you specify the -continuation argument with a restore
directory that does not contain a tp_restore_continuation_info
file, tp_restore executes as if the -continuation argument were
not specified. If you are in the middle of a series of
tp_restore operations, you DO NOT want this to happen. To
avoid
this problem, create a VOS command macro that executes the
tp_restore command with the -continuation argument. The macro
could check for the existence of the
tp_restore_continuation_info
file and if the file is not found, exit before executing
tp_restore.
You can use the -continuation argument even if some of the
transaction data files in the destination directory were not
included in the previous tp_restore session. However, you must
research the correct starting log file for the newly introduced
transaction file and include the required log files in the
restore directory. Follow the procedures described in
"Determining Which Log Files to Use in the Restore Process" to
research the starting log file for a transaction data file.
When
the destination directory contains a transaction data file that
was not included in the previous tp_restore session, the next
tp_restore session knows that it must read ALL log files in the
restore directory. However, when the transaction data files in
the
restore directory are identical to the files used in the
previous
session, tp_restore starts with the continuation log it
identified in the previous session's .out file.
If you do not specify the -continuation argument or if you are
performing the first tp_restore command in a planned series,
tp_restore looks for certain information in the log files that
ensures a proper starting point for rolling forward
transactions
for each of the files in the destination directory. You
must research which log files to move to the restore directory.
Follow the procedures described in "Determining Which Log Files
to Use in the Restore Process."
Messages in the tp_restore Output File
-------------------------------------This section describes some messages that the tp_restore command might
produce in its output file. Since the tp_restore messages are lengthy
and
mostly self-explanatory, exact message text is not included here. Some
situations that produce messages are as follows:
o
If you specify the -continuation argument but the tp_restore
command cannot find the tp_restore_continuation_info file in
the
restore directory, tp_restore produces a warning message and
executes as if the -continuation argument were set to no. This
situation could cause you to lose the ability to update an
infrequently updated file using serial tp_restore methodology.
To prevent this situation, follow the recommendations in the
Explanation section for creating a macro that executes the
tp_restore command.
o
If the tp_restore command cannot find a log file it needs in
the
restore directory, it produces an error message stating that a
log file is missing. The message tells you the name of the
missing log file. After moving the missing log file into the
restore directory, reissue the tp_restore command. (The
process
terminates before any files in the destination directory are
updated.)
o
If multiple tp_restore commands execute using the same
restore directory, the second tp_restore command terminates and
produces an error message stating "file in use." The message
refers to work files that the tp_restore command uses. Wait
until the first command finishes before issuing the next one.
(The command terminates before any files in the destination
directory are updated.)
o
The tp_restore command generates an information message naming
the starting log file for the next tp_restore session. If you
are doing serial restore sessions, use this information when
preparing the restore directory for the next execution.
o
If the logs in the restore directory do not contain any updates
for one of the files in the destination directory, the
tp_restore
command generates an information message stating that a file
was
not updated because no transactions affected it.
o
If the restore directory does not have the correct starting log
for some files in the destination directory, the tp_restore
command rolls forward transactions into the other files in the
destination directory. It also generates an information
message
telling you that a transaction file was not updated because the
correct starting point was not seen in any logs. The message
identifies the transaction file that was not updated. When
this message is returned, your transaction files are not
synchronized. You have the following options.
Option 1
Research the correct starting log file for the
unrestored transaction files, using the procedures
described in "Determining Which Log Files to Use in
the Restore Process." Move the additional log
files to the restore directory, and rerun tp_restore,
leaving the destination directory unchanged. Use the
-continuation argument if you are performing serial
restores.
If you are dealing with many transaction files or
transaction files that are very large, rerunning
tp_restore for all of the transaction files might be
too time consuming. In that case, perform the steps
in
Option 2, which reduces the runtime required by
tp_restore.
Option 2
The following steps describe how to run a tp_restore
session for an out-of-sync transaction file while
preserving the ability to continue with serial
restores later for the entire set of transaction
files.
a.
Research the correct starting log file for
the
unrestored transaction file, using the
procedures described in "Determining Which
Log
Files to Use in the Restore Process." Copy
the
starting log file and all subsequent log
files
into a temporary restore directory.
b.
Use the save and restore commands to move
the
unrestored transaction file into a temporary
destination directory. You must use the
save
and restore commands for this operation to
obtain the required system information about
the transaction file.
c.
Run tp_restore using the temporary restore
and
destination directories. The -continuation
argument is optional for this run.
d.
Use the save and restore commands to move
the
newly restored transaction file back to the
original destination directory.
e.
Examine the .out file in the temporary
restore
directory for the message that identifies
the
starting log for the next serial tp_restore.
Compare this starting log to the starting
log
identified in the .out file in the permanent
restore directory. The starting log for the
next serial tp_restore session must be the
earlier (older) of these two logs. If
necessary, copy log files from the temporary
restore directory into the permanent restore
directory.
f.
Option 3
You are now ready to continue normally with
serial tp_restore sessions.
If you are not performing serial restores, you can
run
a separate tp_restore session for the unrestored file
in the current destination directory, using the
following steps.
a.
Research the correct starting log file for
the
unrestored transaction file, using the
procedures described in the next section.
Move the missing log files into the restore
directory.
b.
Move the transaction data files that were
successfully rolled forward out of the
destination directory.
c.
Issue the tp_restore command.
Determining Which Log Files to Use in the Restore Process
--------------------------------------------------------The tp_restore command has been enhanced to require fewer log files than
it
formerly required in certain situations. Therefore, the recommended
strategy for determining the starting log file for a tp_restore command
has
changed. Note that you can successfully restore files using more logs
than
necessary; however, when you use extra log files, the tp_restore command
might take longer to execute.
Previously, you determined which log file should be the starting log file
based on the saved transaction file's last modified date. Now, you can
base
your decisions on the saved transaction file's save date. In situations
where files
enhancement
transaction
you
can restore
are saved more frequently than they are updated, this
can eliminate a large number of log files. For example, if a
file is updated monthly but is saved during weekly backups,
that file using log files made just prior to the save.
To determine the starting log file for a nonserial tp_restore command,
perform the following steps.
1.
Find the date/time the transaction data file was saved.
If you
are
restoring multiple files, be sure to find the date/time for the
transaction data file that was saved first (earliest).
2.
Find the log file whose date/time last modified is closest to
the
date found in step 1.
3.
Go back two log files prior to the log file found in step 2.
This
should be your starting log file.
To make step 2 easier, you might want to establish a record-keeping
procedure that keeps track of which log file is active at the time
transaction files are saved. A suggested form with a sample entry is
shown
in Figure 1. In the second column, record the log file name that is the
current target of the transaction_log link in the
>system>transaction_logs
directory when you start the save procedure. To find the log file name,
go
to the transaction_logs directory and execute the list -links command.
Transaction File Saved
---------------------1.
2.
3.
file1
Active transaction_log
at Start of Save
---------------------tlf.1-19.0000069219.93-04-05
Minus 2 Logs
to Restore
-----------....69217...
Figure 1. Active Log Files During Transaction File Saves
New Error Code for s$set_transaction_file and set_transaction_file
==================================================================
The following new error message was added to the s$set_transaction_file
subroutine and the set_transaction_file command in VOS Release 12. The
message supports the implementation of log-protected files, described in
the Release 12 Software Release Bulletin (R119-08). Log protection and
transaction protection are mutually exclusive file attributes.
e$invalid_log_protected_op
(7149)
file.
Invalid operation on a log protected
object. The file is a log-protected
It cannot also be a transaction-
protected
file.
Virtual Queues
==============
VOS now supports a new type of direct queue called a virtual queue.
This type of queue can improve performance by up to 50% and is
compatible with the existing direct queues. You specify this queue
type by using the s$msg_open_virtual subroutine (described later in
this section) to open it. Virtual queues support a maximum message
size of 32,767 bytes. The following restrictions apply to virtual
queues.
o The maximum queue depth is 1.
o Messages are handled on a first-in, first-out (FIFO) basis;
message
priority is ignored.
o All processes using the virtual queue must be on the same module
as
the queue.
o Virtual queues do not support tasking.
The s$msg_open_virtual Subroutine
-----------------------------The s$msg_open_virtual subroutine is used to open a virtual queue.
PL/I Usage
---------declare port_id
declare io_type
declare 01
declare
fixed bin(15);
fixed bin(15);
virtual_info
,
02 version
fixed bin(15),
02 maximum_msg_size
fixed bin(15),
02 msg_header_version fixed bin(15),
02 reserved
(13)fixed bin(15);
error_code
fixed bin(15);
declare s$msg_open_virtual entry
call s$msg_open_virtual
error_code);
( fixed bin(15), fixed bin(15),
1 like virtual_info, fixed bin(15));
( port_id, io_type, virtual_info,
C Usage
------short int
short int
port_id;
io_type;
struct virtual_info_tag{
short int
version;
short int
maximum_msg_size;
short int
msg_header_version;
short int
reserved[13];
}
virtual_info;
short int
error_code;
void s$msg_open_virtual(short int*, short int*,
struct virtual_info_tag*, short int*);
s$msg_open_virtual( &port_id, &io_type, &virtual_info, &error_code);
COBOL Usage
----------01 port_id
01 io_type
comp-4.
comp-4.
01
virtual_info
.
02 version
comp-4.
02 maximum_msg_size comp-4.
02 msg_header_version comp-4.
02 reserved
comp-4 occurs 13.
01
error_code
comp-4.
call 's$msg_open_virtual' using port_id, io_type, virtual_info,
error_code.
Pascal Usage
-----------type virtual_info_type = record
version: short;
maximum_msg_size: short;
msg_header_version: short;
reserved: array[1..13] of short;
end;
var
port_id:
io_type:
virtual_info:
error_code:
short;
short;
virtual_info_type;
short;
procedure s$msg_open_virtual( port_id: short; io_type: short;
var virtual_info: virtual_info_type;
var error_code: short);
external;
s$msg_open_virtual( port_id, io_type, virtual_info, error_code);
Arguments
--------port_id (input)
Identifies a port attached to a virtual queue.
io_type (input)
The type of I/O for which you are opening the queue. The possible
values are as follows:
I/O Type
--------requester
server
Value
-----5
6
virtual_info (input)
Information about the queue to be opened. The values of the
arguments in the virtual_info structure are as follows:
version
The version number of the virtual_info structure.
Requesters and servers use the same version number.
This value must be 1 or 2.
maximum_msg_size
The maximum number of bytes in a request or reply
message. The value must be between 0 and 32,767,
inclusive. All openers of the queue must specify the
same value. Since each call to s$msg_open_virtual
allocates a buffer of the specified size in wired
memory, you should specify the smallest value possible
for maximum_msg_size.
msg_header_version
The version of the message header structure expected by
a server process. The value is 0 (no header) for servers;
requesters ignore this argument.
reserved
Reserved for future use.
error_code (output)
A returned error code.
Explanation
To create a virtual queue, use the command create_file or the
subroutine s$create_file to create a sequential file. That
file will become a virtual queue when you use
s$msg_open_virtual to open it. Servers must have write access
to the file; requesters must have non-null access.
A virtual queue must be on the same module as the server(s).
server must open a virtual queue before any requester can do
so.
A
A virtual queue can contain only one message at a time for each
port attached to the queue. A virtual queue cannot be
transaction-protected. That is, it cannot be used to
communicate between requesters and servers after a transaction
has been started by a call to s$start_transaction but before
the transaction has been committed or aborted.
Precautions When Closing Virtual Queues
When a requester calls s$msg_send to place a message in the
virtual queue, the message is initially written into the
requester's memory buffer. When a server's buffer becomes
available, the operating system copies the message into that
buffer. If the server closes the queue before the copy has
taken place, the last message sent may be lost. Consequently,
the requester should use s$msg_send to send a final dummy
"closing" message before closing the queue. A requester can
have only one message in its buffer at a time, so s$msg_send
will not return with a zero error code until the last "real"
message has been copied into a server's buffer. At that time,
the requester can safely close the queue.
Related Information
For related information, refer to the documentation of the
s$msg_open_direct subroutine in the VOS Transaction Processing
Facility manuals.
TPOverseer Performance Improvements (12.3 and 13.1.0)
=====================================================
Beginning in VOS Release 13.1.0, TPOverseer performance has been improved
to reduce or eliminate processing delays during transaction log switches.
Heavy users of the TPF should observe the following:
o little or no delay in operations during log switches
o much faster log switches
o fewer peaks in disk activity that could contribute to poor
response time
TPF Performance Improvements (12.3.0 and 13.3.0)
================================================
This section describes the TPF performance improvements for VOS Releases
12.3.0 and 13.3.0.
Some TPF users use the allow_deadlocks lock-arbitration parameter to
improve performance on heavily loaded systems experiencing poor
throughput.
In cases where such performance problems are related to excessive
pre-emptive transaction aborts, the use of allow_deadlocks eliminates
most
such aborts and allows complete control at the application level.
Although many TPF users have used this approach successfully, it can
cause
very undesirable side effects because the application is completely
responsible for preventing deadlock situations (since allow_deadlocks
inhibits pre-emptive aborts). A list of possible side effects follows.
o If a deadlock occurs, the application often does not detect the
situation until after significant delays occur.
o A deadlock situation can continually recur, causing extreme delays
for
all transactions requiring a lock held by a deadlocked
transaction.
o An application developer has no effective tools to help isolate
the
cause of the deadlock.
TPF for VOS Releases 12.3.0 and 13.3.0 addresses the preceding problems
as
follows:
o The minimum wait period always transpires
before a transaction is aborted, thus eliminating the performance
degradation that occurs when you do not set allow_deadlocks (the
default behavior).
In previous VOS releases, lock arbitration could cause excessive
transaction aborts. Consider the case in which two equally
deserving
transactions contend for the same lock. The transaction desiring
the
lock waits for the transaction holding the lock to complete. The
transaction waits for a minimum of five seconds and until the
implicit
or explicit wait time specified by the I/O call that resulted in
the
need to acquire the lock. (You can modify the five-second minimum
by
setting the new iotv$max_tp_wait_time variable via the
command. Stratus Customer Service personnel should see the Stratus
internal document SED-1884 for more information about this
variable.)
If the wait period passes and the lock is not released, and the
transaction holding the lock started after (that is, is younger)
the
transaction desiring it, the older transaction pre-emptively
aborts
the younger transaction. This behavior prevents deadlocks. Note
that
this behavior does not occur if you set allow_deadlocks.
The actual waiting is done by user-level I/O processing. Whenever
a
lock that some transaction is waiting for is released, all
processes
waiting for a lock in that file awaken and retry the I/O
operation,
which, in turn, tries again to acquire the lock. Often, the lock
will
then be available and the transaction can proceed. However, in
situations in which a younger transaction is still holding the
lock,
the older transaction aborts the younger transaction.
This algorithm works well when relatively few processes or
transactions are contending for records in the same file. However,
when many locks are in contention, the TPOverseer constantly
awakens
processes when other locks in the file are being released. As a
result, a lock will be retried (and the transaction holding it
will
abort), often without a sufficient wait period.
o Stratus has extended the lock-conflict logging capability
available
via the analyze_system command. In previous VOS releases, the
following values of the variable file_io$log_lock_conflicts (which
is of type short) allowed you to log certain occurrences of lock
conflicts.
- The default value 0 specifies that no logging should occur.
- The value 1 logs situations in which a log conflict could
lead to
an abort (for example, a conflict involving a transaction
desiring
a lock currently held by another transaction with a lower
priority).
- The value 2 logs all lock conflicts.
The types of conflict logging provided when you specify the value
1 or
2 provides detailed information about a system's behavior. Since
many
lock conflicts can occur even in normally running systems, the
amount
of logging required is very large and can itself affect
performance
adversely. Typically, you should turn on logging for a very
limited
time period and then analyze the log output.
Beginning in VOS Releases 12.3.0 and 13.3.0, you can use the
following
additional values of file_io$log_lock_conflicts during normal
system
operation. These values log transaction aborts resulting from
certain types of unusual lock conflicts. The variable
file_io$lock_conflict_time (which is of type long) represents an
elapsed time that is used in this determination. This variable's
default is five seconds, but it generally should have the same
time
setting as the variable iotv$max_tp_wait_time, which is the time a
transaction will wait for a lock before aborting a younger
transaction with equal priority that is holding the lock.
- The value 3 logs apparent deadlocks. Specifically, it logs
aborts
that occurred in situations in which the aborted transaction
continually held the required lock an undue amount of time
(that
is, a period of time that is greater than the value specified
for
file_io$lock_conflict_time).
- The value 4 logs suspicious aborts. Specifically, it logs
aborts
that occurred in situations in which possibly more than one
transaction held the lock an undue amount of time or in which
the
transaction was aborted because it started much later than
the
transaction desiring the lock. In the latter situation, the
set_tp_parameters command allows you to set the time value
that is
used to determine whether to abort. (See the VOS Transaction
Processing Facility manuals for more information about
set_tp_parameters.)
- The value 5 logs all lock-conflict aborts. This value is
similar
in behavior to the value 1 but is abort-oriented rather than
conflict-oriented. As with the value 1, you should not use
this
value during normal operation.
The logging performed when you specify the value 4 includes the
logging performed when you specify the value 3. The values of TP
parameters affect the circumstances under which transactions are
aborted, and, in turn, affect the logging resulting from
specifying
the value 3, 4, or 5. For example, if you specify the -ignore_time
argument, no aborts due to start-time differences will occur. If
you
also specify the -allow_deadlocks argument, no aborts will occur
for
equal-priority transactions.
Note that log messages are no longer written to the monitor
terminal,
only to the file (master_disk)>system>syserr_log.date.
o Stratus has extended the transaction-metering capability in the
analyze_system command so that users can monitor the number of
pre-emptive transaction aborts and reasons for the aborts as well
as
related information. Also, the command now meters the amount of
time a
user process holds read locks and the time the TPOverseer takes to
release write locks. See "New TPF-Related Requests of the
analyze_system Command" later in this .doc file for more
information.
New TPOverseer Error Message (13.1.0)
=====================================
Beginning in VOS Release 13.1.0, the TPOverseer returns a message in the
file (master_disk)>system>syserr_log.<date> when it stops accepting new
transactions in order to finish processing backlogged transactions.
Previously, the TPOverseer did not return a message under these
circumstances, which sometimes confused users.
The text of the new message follows.
Forcing flush -- idle needed
You can avoid seeing this message and obtain better throughput
performance
in the future if you increase the size of the transaction work area
(TWA),
the transaction log file (TLF), or both. The default size for both is
500
blocks. If your TPF application processes a large number of
transactions,
you should consider setting the size of the TWA and TLF to a minimum of
5000 blocks each. If you continue to see the new message, increase the
size of the TWA and TLF until you no longer see the message.
New TPOverseer Error Messages (12.3.0 and 13.3.0)
=================================================
The TPOverseer enters one of two error messages in the file
(master_disk)>system>syserr_log.date when it stops accepting new
transactions in order to finish processing backlogged transactions.
Previously, the TPOverseer did not display an error message under these
circumstances.
If your transaction log file (TLF) is too small, the TPOverseer enters
the
following error message.
TLF too small, Forcing flush -- idle needed
If your transaction work area (TWA) is too small, the TPOverseer enters
the
following error message.
TWA too small, Speed flush selected
To avoid these error messages and obtain better throughput performance in
the future, increase the size of the TWA, the TLF, or both. The default
size for each is 500 blocks. If your TPF application processes a large
number of transactions, you should consider setting the size of the TWA
and
TLF to a minimum of 5000 blocks each. If you continue to see one of
these
error messages, increase the size of the TWA and TLF until you no longer
see the message.
New TPF-Related Requests of the analyze_system Command
======================================================
This section documents five new TPF-related analyze_system requests.
o
o
o
o
o
dump_tpo
dump_transaction
list_transactions
tpq_meters
transaction_meters
Note that these requests existed in previous VOS releases but are being
documented for the first time in this .doc file.
The dump_tpo Request
-------------------Purpose
This request displays information about the TPOverseer's internal data
structures.
Display Form
----------------------------- dump_tpo -----------------------------structure:
all
-match:
-hash_tables: no
-brief:
yes
Command-Line Form
dump_tpo structure
[-match match_string]
[-hash_tables]
[-no_brief]
Arguments
structure
<CYCLE>
Specifies the internal data structure to be dumped. The default
value
all dumps all three structures: tp_state_info, gn, and g. The
tp_state_info structure is a part of VOS and thus can be referenced
regardless of the current process. The gn and g structures are
global
structures internal to the TPOverseer. To display information in
these structures, the current process must be the TPOverseer
process.
(To change the current process to the TPOverseer process, specify
the
who request, followed by the process request. See "Examples" later
in
this section for an example.)
-match match_string
Displays only the lines containing a match with the specified
string.
-hash_tables
<CYCLE>
Displays the various hash tables contained in the structures. These
hash tables include the following:
o the shorthand and module hash tables in the g structure
o the page, afte, and mod_page hash tables in the gn structure
o the tio and gtid hash tables in the tp_state_info structure
This argument produces lengthy output, so you should avoid
specifying
it unless you have a specific reason to examine these tables. By
default, the request does not display the hash tables contained in
the
structures.
-no_brief
<CYCLE>
Specifies detailed information about the structures. By default, the
request displays concise information about the structures.
Explanation
This request displays values related to the TPOverseer.
Examples
The following examples illustrate the use of the dump_tpo request. (In
the
examples, note that monospace bold represents user input.) In the first
example, the -no_brief argument is specified to show detailed information
about the structures. Note that the last line of the output indicates
that
the TPOverseer is not the current process.
as: dump_tpo -no_brief
tp_overseer_running:
TRUE
tp_overseer_alive:
TRUE
Structure tp_state_info @ 40C01030
tp_version_no:
1356
tp_file_version_no:
5
tp_o/r_wait_event:
40C07990
tp_o/r_signal_event:
40C07A00
file_change_lockp:
40C025E0
tp_overseer_pid:
01088026
tp_overseer_no_space:
FALSE tp_overseer_dying:
FALSE
tp_overseer_working:
FALSE tp_overseer_notified:
FALSE
tlf_nearly_full:
FALSE tlf_too_long_since_idle: FALSE
tlf_too_long_since_switch: TRUE
tpo_work_list:
40C01070: 00000001 40C01070 00000001
40C01070
num_odd_log_tsi:
0
num_odd_log_gbl_tsi:
0
num_even_log_tsi:
1
num_even_log_gbl_tsi:
0
current_view:
1
num_committing_gbl_tsi (0): 0
num_committing_gbl_tsi (1): 0
num_local_committing_tsi (0): 1
num_local_committing_tsi (1): 0
num_local_committing_gbl_tsi (0): 0
num_local_committing_gbl_tsi (1): 0
TSI list header:
40C01088: 40D79FE0 40D79FE0 4144C4C0
4144C4C0
TSI free list num_entries: 5
KWL list header:
40C010B0: 40FE8EC0 40FE8EC0 40FE8EC0
40FE8EC0
KWL free list num_entries: 1
FLI list header:
40C010D8: 40FFC4A0 40FFC4A0 40FF6EB0
40FF6EB0
FLI free list num_entries: 3
RRL list header:
40C01100: 40FCC600 40FCC600 40FED6E0
40FED6E0
RRL free list num_entries: 44
RWL list header:
40C01128: 4144AE70 4144AE70 40FF2FF0
40FF2FF0
RWL free list num_entries: 4
KRL list header:
40C01150: 40DDE7C0 40DDE7C0 40FD4AF0
40FD4AF0
KRL free list num_entries: 4
GTID list header:
40C01178: 00000001 40C01178 00000001
40C01178
GTID free list num_entries: 0
num_precommitted_txns:
0
precommitted_gtid_list:
40C025A4: 00000001 40C025A4 00000001
40C025A4
Structure tp_default_parameters @ 005FEB76
priority:
0
flags:
none
dump_tpo: Further information available only with TPOverseer as
current
process.
In the second example, the who request is specified to find the
TPOverseer's process number. Once the process number is found, the
process
request is specified to set the TPOverseer process as the analyzed
process.
Finally, the dump_tpo request is specified to display information about
the
TPOverseer's internal structures (note that the request also displays the
g
and gn structures).
as: who
PROC
PTEP
1 00342AA0
3 40BA5170
USER NAME
CPU12.Idle (Idle_12)
Cache_Manager_Post.System (Cache_Manager_Post), on
CPU14
4 40BA8490
5 40BAB400
6 40BB3790
7 40BB5010
...
36 40CB03A0
38 40E41640
39 40E47380
...
Cache_Manager_Timer.System (Cache_Manager_Timer)
Cache_Manager_Locker.System (Cache_Manager_Locker)
CPU0.Idle (Idle_0)
CPU2.Idle (Idle_2)
Paging_Daemon.System (Paging_Daemon0)
Overseer.System (TPOverseer), on CPU8
Overseer.System (LinkServer1)
as: process 38
Using process on CPU10.
Current process is 38, ptep 40E41640, Overseer.System (TPOverseer)
Process is running on CPU 10 right now; no stack addr known.
as:
dump_tpo
tp_overseer_running:
TRUE
tp_overseer_alive:
TRUE
Structure tp_state_info @ 40C01030
tp_version_no:
1356
tp_file_version_no:
5
tp_o/r_wait_event:
40C07990
tp_o/r_signal_event:
40C07A00
file_change_lockp:
40C025E0
tp_overseer_pid:
01088026
tp_overseer_no_space:
FALSE tp_overseer_dying:
FALSE
tp_overseer_working:
FALSE tp_overseer_notified:
FALSE
tlf_nearly_full:
FALSE tlf_too_long_since_idle: FALSE
tlf_too_long_since_switch: TRUE
tpo_work_list:
40C01070: 00000001 40C01070 00000001
40C01070
num_odd_log_tsi:
0
num_odd_log_gbl_tsi:
0
num_even_log_tsi:
3
num_even_log_gbl_tsi:
0
current_view:
0
num_committing_gbl_tsi (0): 0
num_committing_gbl_tsi (1): 0
num_local_committing_tsi (0): 0
num_local_committing_tsi (1): 3
num_local_committing_gbl_tsi (0): 0
num_local_committing_gbl_tsi (1): 0
num_precommitted_txns:
0
precommitted_gtid_list:
40C025A4: 00000001 40C025A4 00000001
40C025A4
Structure tp_default_parameters @ 005FEB76
priority:
0
flags:
none
Structure g @ 00E2D888
my_process_id:
01088026
flags:
idle_written,semi_idle_written
next_run_time:
0000000C2FA332FD
last_free_time:
0000000C2F99A137
next_network_time:
FFFFFFFFFFFFFFFF
next_flush_time:
0000000000000000
next_flush_try_time:
0000000C2F9E00DC
next_idle_time:
0000000C31F60AB1
next_idle_flush_time:
0000000000000000
next_flush_section_time:
0000000000000000
wait_lists:
driver_list:
00E2D8E0: 00000001 00E2D8E0 00000001
00E2D8E0
flush_list:
00E2D8F0: 00000001 00E2D8F0 00000001
00E2D8F0
physical_wait_list:
00E2D910: 00000001 00E2D910 00000001
00E2D910
module_wait_list:
00E2D920: 00000001 00E2D920 00000001
00E2D920
tlf_output_info:
tlf_number:
299878
high_offset:
8339973
high_offset_tried:
high_offset_flushed:
high_offset_idled:
log_record.max_len:
log_record.recp:
free_shorthand:
00E73E48
shorthand_hashp:
8339885
8339885
3451
24576
00E955F0
00E2D95C: 00E73E9C 00E73E9C 00E73E48
00E42620
Structure gn @ 00E2A558
twa_portep:
40DC6E10
twa_aftep:
40DC6EE0
twa_fip:
40DC7000
n_indexes:
28
num_pages:
2000
num_free_pages:
2000
cur_section_infop:
00000001
cur_file_infop:
00000001
next_to_twa_time:
0000000000000000
to_twa_list:
00E2A578: 00000001 00E2A578
00E2A578
next_log_in_twa_time:
0000000000000000
log_in_twa_list:
00E2A590: 00000001 00E2A590
00E2A590
in_twa_list:
00E2A5A0: 00000001 00E2A5A0
00E2A5A0
next_to_file_time:
0000000000000000
to_file_list:
00E2A5B8: 00000001 00E2A5B8
00E2A5B8
next_log_in_file_time:
0000000000000000
log_in_file_list:
00E2A5E0: 00000001 00E2A5E0
00E2A5E0
next_bmex:
5
twa_path:
%s#m1>system>transaction_logs>transaction_work_area
00000001
00000001
00000001
00000001
00000001
The dump_transaction Request
---------------------------Purpose
This request displays information about a specific Transaction State Info
(TSI) structure.
Display Form
-------------------------- dump_transaction ----------------------------address:
-brief: no
Command-Line Form
dump_transaction address
[-brief]
Arguments
address
Required
A standard analyze_system address string representing the TSI's
location. The list_transactions request identifies the address of
the
various TSIs that this argument displays.
-brief
<CYCLE>
Displays the hash, work, and net links and the file_lock_info
structures queued on the lock_list links. By default, the request
does not display these links and structures.
Explanation
The dump_transaction request displays a single TSI structure and,
optionally, a list of associated file_lock_info structures.
Examples
In the following example, the dump_transaction request displays a TSI
structure. The transaction has modified two files and is not yet
committed. (In the example, note that monospace bold represents user
input.)
dump_transaction 80D971C0
Transaction_state_info:
Transaction ID:
0000000000000000
Started on module:
est
Started by process:
02018042)
Lock process ID:
02018042)
State:
Priority:
Arbitration flags:
Transaction flags:
start_log_is_set
Commit view:
Num blocks:
gtid_infop:
blocked_flip:
lock_code:
time_val:
wait_info:
extended:
retries:
aborts:
rlocks:
80D971C0
1EB7B1BD02015119
Commit ID:
%s2#m2 (2-1)
at:
96-04-30 13:11:09
66 on module %s2#m2 (2-1) (process ID:
66 on module %s2#m2 (2-1) (process ID:
TID_RUNNING_LOCKED
0
none
file modified, on hash list,
1
12
00000001
00000001
0
10
0
TRUE
0
0
6
wlocks:
meter_state:
meter_state:
Hash_links:
17
4 arrived/started
5 arrived/started
007D6148: 00000001 8019BC58 00000001
Work_links:
007D6158: 00000001 00000001 000A00001
Net_links:
007D6168: 00000001 00000001 000000001
lock_list:
007D61B8: 80D90CE0 80D90CE0 80D967220
8019BC58
00000001
00000001
80D96720
by_afte:
00861838: 80D91740 80D91750 0000000
by_tsi:
00861828: 80D96720 80D96720 00000001
afte_ptr:
afte name:
afte last record:
tp old last record:
tp last record:
tid waiting:
tid blocking:
tp lock type:
tp lock flags:
record_r_list:
80D91460
sys_aud_arc_file
178371818
178371818
178372030
80D90D0C00000001
80D90D0C00000000
reserve write lock
file modified, eof modified
0086186C: 00000001 80D90D24 00000000
record_w_list:
00861880: 80D911A0 80D911A0 80D97680
links:
00864688: 80D97680 80D97680 00000001
80D91510
80D96CD0
80D90D24
80D97680
80D90D38
byte w locked:
existed:
exists:
cur_size:
log_len:
log_offset:
links:
eof+
byte w locked:
existed:
exists:
cur_size:
log_len:
log_offset:
n_indexes:
by_afte:
eof+
0
false
true
102
106
96464752
00864688: 00000001 80D90D38 80D911A0
80D911A0
106
false
true
102
106
96464888
0
00861838: 80D961C0 80D961D0 00000001
801E1630
by_tsi:
00861828: 00000001 80D96CD0 80D90CE0
afte_ptr:
afte name:
afte last record:
tp old last record:
tp last record:
801E1580
sys_aud_file
2020914
2020914
2020914
80D90CE0
tid waiting:
tid blocking:
tp lock type:
tp lock flags:
record_r_list:
links:
1EB685E202015107
1EB685AB020150C3
reserve write lock
file modified
0086186C: 80D947C0 80D947C0 80D90E20 80D90
007D63C8: 80D95720 80D95720 00000001
80D96764
rec r locked:
links:
435564
007D63C8: 80D90E20 80D90E20 80D947C0
rec r locked:
links:
1242088
007D63C8: 00000001 80D96764 80D95720
rec r locked:
record_w_list:
1944454
00861880: 80D8F5C0 80D8F5C0 80D92000
80D947C0
80D95720
80D92000
links:
00864688: 80D90620 80D90620 00000001
80D96778
rec w locked:
existed:
exists:
cur_size:
log_len:
log_offset:
links:
435564
true
false
254
2
96464736
00864688: 80D92040 80D92040 80D8F5C0
80D8F5C0
rec w locked:
...
n_indexes:
locks on index:
r_list (1):
1083187
6
sys_aud_idx_3
00861898: 00000001 80D96790 00000001
w_list (1):
008618AC: 8022E040 8022E040 80D91D60
80D96790
80D91D60
links:
00864788: 80D92620 80D92620 80D8FDE0
key w locked: "
num dups:
max / num add:
max / num del:
offset:
value:
links:
01IJKJIHHHH3519714484632"
1
0 / 0
4 / 1
1
1242088
00864788: 80D91D60 80D91D60 8022E040
80D8FDE0
8022E040
key w locked: "
num dups:
max / num add:
max / num del:
offset:
value:
...
locks on index:
r_list (2):
80D967B8
01IJKKJIEEE3521404261987"
1
0 / 0
4 / 1
1
1944454
sys_aud_idx_4
008618C0: 00000001 80D967B8 00000001
w_list (2):
008618D4: 80D8F2A0 80D8F2A0 8022F8C0
8022F8C0
links:
00864788: 8022DF40 8022DF40 80D96380
80D96380
...
Max / Num modules:
0 / 0
The list_transactions Request
----------------------------Purpose
This request displays information about a specific list of TSIs or about
all TSIs active in the system.
Display Form
------------------------- list_transactions ---------------------------list_addr:
-list:
-started_before:
-state:
all
-brief:
no
Command-Line Form
list_transactions
[list_addr OR -list]
[-started_before date_time_string]
[-state]
[-brief]
Arguments
list_addr
A standard analyze_system address string representing the location
of
links that head a list of TSIs. This argument and the -list
argument
are mutually exclusive.
-list queue_name
Specifies an internal queue.
argument
are mutually exclusive.
This argument and the list_addr
-started_before date_time_string
Displays only TSIs for transactions started before date_time_string,
which is a standard date/time string.
-state
<CYCLE>
Displays those TSIs in the indicated state. The values are all,
aborted, committed, or running. The default value is all.
-brief
<CYCLE>
Displays the hash, work, and net links and the file_lock_info
structures queued on the lock_list links. By default, the request
does not display these links and structures.
Explanation
This request displays a list of TSI structures and, optionally, a list of
each of their associated file_lock_info structures.
Examples
An example of the list_transactions request follows. In this example,
only
two transactions are active. (In the example, note that monospace bold
represents user input.)
list_transactions -brief
tio_hash_head (39)::
80D971C0
Transaction_state_info:
Transaction ID:
0000000000000000
Started on module:
est
Started by process:
02018042)
Lock process ID:
02018042)
State:
Priority:
Arbitration flags:
Transaction flags:
Commit view:
Num blocks:
gtid_infop:
blocked_flip:
lock_code:
time_val:
wait_info:
extended:
meter_state:
meter_state:
Max / Num modules:
3FEA85D8: 80D971C0 80D971C0 80D971C0
Transaction_state_info:
Transaction ID:
1EB2870A00004FBD
Started on module:
est
Started by process:
02018042)
80D971C0
1EB7B20102015127
Commit ID:
%s2#m2 (2-1)
at:
80D971C0
1EB7B20102015127
Commit ID:
%s2#m2 (2-1)
at:
96-04-30 13:12:17
66 on module %s2#m2 (2-1) (process ID:
66 on module %s2#m2 (2-1) (process ID:
TID_RUNNING_LOCKED
0
none
on hash list
1
0
00000001
00000001
0
10
0
FALSE
4 arrived
5 arrived
0 / 0
96-04-30 13:12:17
66 on module %s2#m2 (2-1) (process ID:
State:
Priority:
Arbitration flags:
Transaction flags:
start_log_is_set
Commit view:
Num blocks:
gtid_infop:
blocked_flip:
lock_code:
time_val:
wait_info:
extended:
meter_state:
Max / Num modules:
TID_NET_PHASE_2
0
none
on work list, commit_started,
1
105
00000001
00000001
0
10
0
FALSE
0 arrived/started
0 / 0
The tpq_meters Request
---------------------Purpose
This request displays information about queues and pseudo queues used in
transaction processing.
Display Form
---------------------------- tpq_meters --------------------------------no_header:
no
-reset:
no
-full:
no
-queues:
-data:
-report:
yes
-interval:
-output_path:
Command-Line Form
tpq_meters
[-no_header]
[-reset]
[-full]
[-queues]
[-data]
[-no_report]
[-interval [time_interval]]
[-output_path file_name]
Arguments
-no_header
<CYCLE>
Suppresses the display of header information. By default, the
request
displays header information.
-reset
<CYCLE>
Temporarily resets the queue meters until you exit analyze_system.
By
default, the request does not reset the queue meters.
-full
<CYCLE>
Displays all queues, including those that are currently not active.
By default, the request does not display all queues. This argument
is
meaningful only if you also specify the -interval argument.
-queues
<CYCLE>
Displays actual and/or pseudo queues, based on which of the
following
values you specify.
- If you specify the driver value, the request displays actual
queues.
- If you specify the running value, the request displays pseudo
queues.
- If you specify the all value, the request displays actual and
pseudo queues. This is the default value.
-data
<CYCLE>
Determines the format in which the request displays data when you
also
specify the -interval argument. By default, the argument displays
the
average wait, busy, and total times associated with a queue, plus
the
message arrival count. A list of the formats follows.
- The averages value displays the average wait and busy times
only.
- The all value displays average and total times.
- The counts value displays the counts for arrivals, starts, and
completions, as well as averages.
- The time/counts value displays the total times and the total
counts.
- The time value displays the total wait and busy times, as well
as
the total combined times since you started the tpq_meters
request.
-no_report
<CYCLE>
Specifies that the request should not display data. By default, the
request always displays data. You should specify this argument with
the -reset argument, which typically does not display data; in this
case, the request displays the data before the reset occurs.
-interval [time_interval]
Specifies a value from 1 through 60 indicating the interval at which
the request displays queue values. The time_interval value
represents
seconds and is rounded up to one of the following: 1, 2, 5, 10, 30,
or 60. If you do not specify the optional time_interval value, the
default value is 10. When you specify this argument, the -data
argument determines the display's format.
-output_path file_name
Directs the output from the terminal's screen to file_name. By
default, the request directs output to the terminal's screen.
Explanation
This request displays information about queues and pseudo queues.
Examples
The following example illustrates the use of the tpq_meters request
without
the -interval argument specified.
time
meter
wait_time
busy_time
arrive
start
complete
1:04:41 driver
1
0
2513
2513
1:04:41 idle_wait
0
0
0
0
1:04:41 tlf_flush
324
0
845
845
1:04:41 phy_wait
63
0
845
845
1:04:41 section
0
595
845
845
1:04:41 to_twa
23
120
844
843
1:04:41 log_in_twa
69
464
843
843
1:04:41 in_twa
37
309
843
843
1:04:41 to_file
10305
816
843
833
1:04:41 file_info
10328
52
831
816
349
465
816
816
0
0
0
0
2513
0
845
845
844
843
843
843
831
816
1:04:41 log_infile
816
1:04:41 module_wait
0
1:04:41 running
523
1656
858
858
1:04:41 rmt_running
0
0
0
0
1:04:41 hold_rlocks
3766
1510
870
867
1:04:41 hold_wlocks
3767
3658
870
867
856
0
865
863
The columns in the preceding example have the following meanings.
o The time column shows the number of hours, minutes, and seconds (in
the format hh:mm:ss) over which the statistics have been collected.
o The meter column shows the name of the queue.
o The wait_time column shows the average queue waiting time.
o The busy_time column shows the average queue busy time.
o The arrive, start, and complete columns show the counts of
arrival/start/completion events for each queue.
If you specify the -reset argument, the request will reset the output
shown
in the preceding example; future counts and averages will be calculated
from the time of the reset.
The transaction_meters Request
-----------------------------Purpose
This request displays various TP meters and allows you to reset the TP
metering level.
Display Form
------------------------- transaction_meters ----------------------------set_metering:
-no_header:
no
-reset:
no
-report:
yes
-interval:
-full:
no
-brief:
yes
-max_values:
yes
-lock_info:
no
-detail_aborts: no
-output_path:
Command-Line Form
transaction_meters
[-set_metering]
[-no_header]
[-reset]
[-no_report]
[-interval [time_interval]]
[-full]
[-no_brief]
[-no_max_values]
[-lock_info]
[-detail_aborts]
[-output_path file_name]
Arguments
-set_metering
Changes the current TP metering level.
following values.
<CYCLE>
This argument has the
- The none value indicates that metering is not enabled.
- The basic value enables basic metering.
- The queue value enables queue metering.
- The extended value enables extended metering. You can specify
extended only if the -max_metering argument of the tp_overseer
command was set to extended.
For more information about these values, see ''Changes to the
tp_overseer Command" earlier in this chapter.
-no_header
<CYCLE>
Suppresses the display of header information. By default, the
request
displays header information.
-reset
<CYCLE>
Temporarily resets the queue meters until you exit analyze_system.
By
default, the request does not reset the queue meters.
-no_report
<CYCLE>
Specifies that the request should not display data. By default, the
request always displays data. You should specify this argument with
the -reset argument, which typically does not display data; in this
case, the request displays the data before the reset occurs.
-interval [time_interval]
Specifies a value from 1 through 60 indicating the interval at which
the request displays queue values. The time_interval value
represents
seconds and is rounded up to one of the following: 1, 2, 5, 10, 30,
or
60. If you do not specify the optional time_interval value, the
default value is 10. When you specify this argument, the -data
argument determines the display's format.
-full
<CYCLE>
Displays all meters, including those with a value of 0. By default,
the request does not display all meters. This argument is meaningful
only if you also specify the -interval argument.
-no_brief
<CYCLE>
Displays more detailed information about lock-contention statistics:
notifies, time-outs, retries, and lock aborts. By default, the
request
displays concise information about lock-contention statistics.
-no_max_values
<CYCLE>
Specifies that the request should not display the maximum values of
each of the queue and pseudo-queue statistics. By default, the
request
displays the maximum values of each of the queue and pseudo-queue
statistics. If you also specify the -lock_info argument, the request
displays the maximum number of retries, aborts, read-locks held, and
write-locks held for any single transaction. Note that this argument
displays information only if you are performing extended metering.
-lock_info
<CYCLE>
Displays information about lock-contention statistics involving the
number of waits and retries to acquire locks. By default, the
request
does not display this information.
-detail_aborts
<CYCLE>
Breaks down the display of aborts into further categories. When you
specify the default value of no, the request categorizes aborts as
user requested, lock conflict, remote, or other, which is sufficient
detail in most cases. If you specify a value of yes, the request
displays up to 16 different types of aborts. In general, you should
not specify this argument with the -interval argument, as your
terminal's screen cannot display all of the information.
-output_path file_name
Directs the output from the terminal's screen to file_name. By
default, the request directs output to the terminal's screen.
Explanation
This request displays the values of various TP meters.
Examples
The following example illustrates the use of the transaction_meters
request
with the -interval and -lock_info arguments specified.
Transaction Processing Statistics
metering time: 0031:17:26
10sec
30sec
1min
5min
10min
Started
11
33
70
331
723
Committed
12
34
70
330
719
Completed
12
34
71
330
720
Lock aborts
Readonly txns
Lock Waits
0
0
0
0
0
5
0
0
8
2
8
94
3
13
204
Lock Rewaits
0
2
3
54
113
Retries
1
5
8
95
205
Notifies
1
5
8
94
203
Timeouts
Time Aborts
Wait Aborts
Deadlock Aborts
0
0
0
0
0
0
0
0
0
0
0
0
1
1
1
1
2
2
1
1
Max running
4810
4878
5513
7569
7569
Max hold_rlocks 10s
10s
11s
20s
20s
Max hold_wlocks 13s
14s
14s
23s
23s
Max driver
Max phy_wait
9
2876
20
2876
20
2876
20
2876
20
3193
Max section
2875
2875
2875
2875
3192
Max tlf_flush
719
1215
1370
3016
3016
Max log_infile
3176
3176
3176
3176
3425
Max log_in_twa
3075
3075
3075
3075
4125
Max to_file
14s
14s
14s
14s
15s
Max file_info
12s
12s
12s
13s
13s
Max in_twa
779
1012
1107
2084
2084
Max to_twa
1106
1199
1379
2683
2683
Max retries
1
2
2
8
8
1hr
Total
906
901
903
4
14
233
129
233
231
2
3
1
1
8449
20s
27s
20
3193
3192
3016
3425
4125
15s
13s
2084
2683
8
Max aborts
Max rlocks
Max wlocks
147
0
41
140
0
42
147
0
42
147
1
42
147
1
42
147
1
42