VOS System Administration: The Accounting Facility

Stratus Technologies
R281M-00

Notice

The information contained in this document is subject to change without notice.

UNLESS EXPRESSLY SET FORTH IN A WRITTEN AGREEMENT SIGNED BY AN AUTHORIZED
REPRESENTATIVE OF STRATUS TECHNOLOGIES, STRATUS MAKES NO WARRANTY OR REPRESENTATION
OF ANY KIND WITH RESPECT TO THE INFORMATION CONTAINED HEREIN, INCLUDING WARRANTY OF
MERCHANTABILITY AND FITNESS FOR A PURPOSE. Stratus Technologies assumes no responsibility or obligation
of any kind for any errors contained herein or in connection with the furnishing, performance, or use of this document.
Software described in Stratus documents (a) is the property of Stratus Technologies International, S. r.l. or the third
party, (b) is furnished only under license, and (c) may be copied or used only as expressly permitted under the terms
of the license.
Stratus documentation describes all supported features of the user interfaces and the application programming
interfaces (API) developed by Stratus. Any undocumented features of these interfaces are intended solely for use by
Stratus personnel and are subject to change without warning.
This document is protected by copyright. All rights are reserved. No part of this document may be copied, reproduced,
or translated, either mechanically or electronically, without the prior written consent of Stratus Technologies.
Stratus, the Stratus logo, Continuum, Continuous Processing, StrataLINK, and StrataNET are registered trademarks of
Stratus Technologies International, S. r.l.
ftServer, ftServer with design, Stratus 24 x 7 with design, The Worlds Most Reliable Server, Selectable Availability,
XA/R, SQL/2000, and The Availability Company are trademarks of Stratus Technologies International, S. r.l.
RSN is a trademark of Lucent Technologies, Inc.
All other trademarks are the property of their respective owners.

Manual Name: VOS System Administration: The Accounting Facility

Part Number: R281M
Revision Number: 00

Stratus Technologies, Inc.

111 Powdermill Road
Maynard, Massachusetts 01754-3409
2001 Stratus Technologies International, S. r.l. All rights reserved.

Contents

1. VOS System Administration: The Accounting Facility

THE ACCOUNTING FACILITY
PROCESSING THE ACCOUNTING LOGS
THE EXTERNAL VARIABLE s$acct_record
ACCOUNTING FACILITY SUBROUTINES
s$acct_processing_init
s$acct_init_summary
s$acct_init_summary_key
s$acct_next_record
s$acct_get_longest_key
s$acct_init_summary_output
s$acct_next_summary_output

1-1
1-1
1-2
1-2
1-5
1-5
1-7
1-7
1-8
1-8
1-9
1-9

Contents

iii

Contents

iv

VOS System Administration: The Accounting Facility (R281M-00)

Chapter 1
VOS System Administration:
The Accounting Facility

1-

This file contains information to supplement the documentation provided in

the chapter entitled The Accounting Facility in the System
Administrators Guide.

THE ACCOUNTING FACILITY

The operating system performs accounting functions by writing records
to a log file at various times during the execution of a process. At
a minimum, records are written at process creation and termination;
you can also choose to write records when files are closed and when
commands are initiated and terminated. In addition, you can enable
port accounting through the accounting_admin command to collect
detailed information about I/O activity on ports.
Process statistics records and process defined records are written
when one of the following system subroutines is called:
s$log_resource_usage( client_user_id, code );
declare
client_user_id
char(65) varying,
code
fixed bin(15);
s$log_process_record( string_length, string, code );
declare
string_len
fixed bin(15),
string
char(N),
code
fixed bin(15);
The first subroutine, s$log_resource_usage, gathers all current
statistics, writes them to the log file, and then resets all counters.
It is used by server processes such as message servers to distribute
charges to users sending requests to them. The second subroutine,
s$log_process_record, writes a user defined record into the log. If
the accounting facility has not been enabled, these subroutines return
the error code e$acct_records_not_logging.
If the information being logged is kept by the operating system in
binary form, the records written about it contain binary information.
The following table lists which operating system subroutine calls are
counted as reads and which as writes by port accounting.
WRITES
READS
-----------------------------------------s$add_item
s$get_item

VOS System Administration: The Accounting Facility

1-1

PROCESSING THE ACCOUNTING LOGS

s$add_key
s$keyed_position_rewrite
s$keyed_rewrite
s$keyed_write
s$rel_position_rewrite
s$rel_rewrite
s$rel_write
s$seq_position_rewrite
s$seq_rewrite
s$seq_write
s$seq_write_partial
s$write_raw

s$keyed_position_read
s$keyed_read
s$read_raw
s$rel_position_read
s$rel_read
s$seq_position_read
s$seq_read

PROCESSING THE ACCOUNTING LOGS

The runtime library contains a subroutine package you can use to read
accounting logs and produce reports. Some subroutines in the package
read selected records from the selected logs and present them to the
caller in time sequential order (even if more than one module is
selected). While reading the records, they prepare a database from
which one or more summaries can be obtained. Other subroutines in the
package retrieve the summary information.
The operating system also provides the include files necessary to
support the package, and sample programs in BASIC, PL/I, and Pascal
that use the subroutines package.
The following subroutines are used for reading log files:
s$acct_processing_init
s$acct_init_summary
s$acct_init_summary_key
s$acct_next_record
The following subroutines return summary information:
s$acct_get_longest_key
s$acct_init_summary_output
s$acct_next_summary_output
Descriptions of these subroutines appear later in this document.
Note that the external variable s$acct_record.version must be set to 1
prior to calling any of the subroutines in this package.

THE EXTERNAL VARIABLE s$acct_record

Many of these subroutines reference fields in an operating system
external variable called s$acct_record. These fields are noted here;
brief descriptions are given for those fields that are not
self-explanatory. All times in s$acct_record are in seconds.
s$acct_record
record_type

1-2

VOS System Administration: The Accounting Facility (R281M-00)

THE EXTERNAL VARIABLE s$acct_record

A tag indicating the type of record.

are:
1
2
3
4
6
7
8
9
11
12

The possible values

proc start
proc term
proc cleanup
proc stats
file close
command start
command term
file log
proc log
transaction

date_time
The standard date/time this record was logged.
module_name
The name of the module on which the record was logged.
user_name
group_name
terminal_port_path
process_name
process_priority
client_name
The client name given for process statistics records.
client_group
For process statistics records, the group portion of
the client name, if the split_client_name parameter in
the s$acct_processing_init is specified as true.
file_type
For file close records and file log records, the file
type, as returned by s$get_port_attachment.
file_path
For file close records and file log records, the file
path.
command_level
For command start and stop records, the command level.
This indicates how many commands are nested. For
example, if a macro calls a command, the level of the

VOS System Administration: The Accounting Facility

1-3

THE EXTERNAL VARIABLE s$acct_record

macro is 1 and the level of the command is 2.

command
For command start records, the name of the command.
elapsed_time
The amount of real time, in seconds, that has elapsed
since the last record was written for this process (0
for process start records).
cpu_time
The amount of cpu time, in seconds, since the last
record was written.
pf_time
The amount of page fault time, in seconds, since
the last record was written.
disk_reads
disk_writes
page_faults
max_working_set
working_set_usage
max_pages_used
calls_to_other_modules
calls_to_other_systems
transaction_type
task_id
transaction_id
The following fields are filled only if port accounting was
enabled when the logs were created.
read_byte_count
write_byte_count
read_record_count
write_record_count
These fields are arrays indexed by device type, as
returned by s$get_port_attachment.
number_of_device_types
The number of entries in these arrays that are actually

1-4

VOS System Administration: The Accounting Facility (R281M-00)

ACCOUNTING FACILITY SUBROUTINES

relevant.

ACCOUNTING FACILITY SUBROUTINES

The rest of this document contains brief descriptions of the PL/I
versions of these subroutines. Each description illustrates and
discusses both the procedure declaration for the subroutine and the
subroutine call itself.

s$acct_processing_init
declare s$acct_processing_init entry( char(256) varying,
fixed bin(31), fixed bin(31), char(66) varying,
fixed bin(15), fixed bin(15), fixed bin(15),
char(32) varying, char(32) varying, char(32) varying,
char(256) varying, char(256) varying,
char(256) varying, char(65) varying, char(32) varying,
fixed bin(15), char(256) varying, char(32) varying );
The s$acct_processing_init subroutine initializes the accounting
package to read records from the accounting log(s) of one or more
modules. You should call this subroutine first. All parameters
are input.
s$acct_processing_init( accounting_dir, start_time, end_time,
modules, port_accounting_required,
port_accounting_relevant, split_client_name,
match_process, match_user, match_group, match_terminal,
match_file, match_command, match_client,
match_client_group, num_summaries, user_record_path,
command_name )
accounting_dir
Either the null string () or a directory name. If
you specify a directory name, the operating system
looks for the accounting files in the specified
directory rather than in the standard accounting
directories for the desired modules. If you specify a
directory name for this parameter, you must specify the
null string for the modules parameter.
start_time
end_time
The time interval over which the log(s) are to be
scanned.
modules
A module star name that defines the module(s) whose
log(s) are to be scanned. If you specify a directory
name for the accounting_dir parameter, you must specify
the null string () for the modules parameter.
port_accounting_required

VOS System Administration: The Accounting Facility

1-5

ACCOUNTING FACILITY SUBROUTINES

port_accounting_relevant
These flags indicate
should consider port
relevant. Specify a
should be considered

whether the log that is processing

accounting required and/or
nonzero value to denote that it
required and/or relevant.

These flags relate to the port accounting option. If you

did not specify the port_accounting option with the
accounting_admin command, then the read_byte_count,
write_byte_count, read_record_count, and write_record_count
values of the s$acct_record external variable will not be
valid. If port accounting is required, then the log that is
processing will issue warnings if that option was not in
effect at any time during the selected time interval. If
port accounting is relevant, then the log processing will
give a warning if the port_accounting option was changed
during the selected time interval.
split_client_name
If this flag is zero, the client names specified in
proc_stats records will be treated as a single string;
otherwise, they will be parsed as USER[.GROUP], and
the group name will be split from the user name.
match_process
match_user
match_group
match_terminal
match_command
match_client
match_client_group
These parameters allow you to select a subset of the
records in the log files: they specify star names that
are checked against the corresponding fields in
s$acct_record. If all of the star names match, then
the particular record is selected for processing.
These values default to *. Path names can be full or
relative, and can contain a star name in any component.
A relative path name that is specified as a pattern
matches any string containing that pattern; for
example, *>stuff matches %a#b>stuff, %b#d>stuff,
%a#b>c>stuff. The parameter match_client_group is
meaningful only if split_client_name is specified as
true (nonzero).
num_summaries
The number of summaries to be produced from the record
selected from the logs. In ensuing calls, summaries
are identified by a number between 1 and num_summaries.
user_record_path
The path name of a file into which user defined records

1-6

VOS System Administration: The Accounting Facility (R281M-00)

ACCOUNTING FACILITY SUBROUTINES

are to be placed. If you specify the null string (),

no file is created, and user defined records in the
logs are ignored.
command_name
This parameter is used when calling s$error.

s$acct_init_summary
declare s$acct_init_summary entry( fixed bin(15), fixed bin(15) );
The s$acct_init_summary subroutine is used to initialize one
summary. You must call it num_summaries times after the
call to s$acct_processing_init, and before any calls to
s$acct_next_record. (The value num_summaries is specified
as a parameter in the call to s$acct_processing_init.) It
must be immediately followed by num_components calls to
s$acct_init_summary_key. All parameters are input.
s$acct_init_summary( which_summary, num_keys )
which_summary
A number that identifies the summary to initialize.
num_keys
The number of keys used to identify a unique entry in
this summary. In ensuing calls, the keys are
identified by a number between 1 and num_keys.

s$acct_init_summary_key
declare s$acct_init_summary_key entry( fixed bin(15),
fixed bin(15), char(*) varying );
The s$acct_init_summary_key subroutine adds one key to the
summary indicated in the preceding s$acct_init_summary call. You
must call it before any calls to s$acct_next_record, and must
call it once for each of the keys in the summary. These calls
must occur in key number order. All parameters are input;
however, you must pass the key parameter by reference.

s$acct_init_summary_key( which_key, max_size, key )

which_key
The key number for this key.
max_size
The maximum number of characters in the key.
key

VOS System Administration: The Accounting Facility

1-7

ACCOUNTING FACILITY SUBROUTINES

One of the following entries in the external variable

s$acct_record:
module_name
user_name
group_name
terminal_port_path
process_name
client_name
client_group
file_path
command
Note that only character varying fields in that
specific external variable are allowed.

s$acct_next_record
declare s$acct_next_record entry( fixed bin(15) );

The s$acct_next_record subroutine is used to read in all

records in the accounting log. You must call this
subroutine after the initialization calls
(s$acct_processing_init, s$acct_init_summary, and
s$acct_init_summary_key).
s$acct_next_record( code )
code
The value returned will be either zero or an operating
system error code. The error code e$end_of_file
indicates that all selected records have been read.
Any other error code is unexpected and indicates that
results may be incomplete or invalid.
If code is zero, then the external variable
s$acct_record contains the value for the next selected
record from the log files. The fields for
s$acct_record are defined in the include files
acct_record.incl.LANG.

s$acct_get_longest_key
declare s$acct_get_longest_key entry( fixed bin(15),
fixed bin(15), fixed bin(15) );
The s$acct_get_longest_key subroutine returns the longest
value that has been seen for a given key in a given summary.
You can call it any time after the last call to
s$acct_next_record. The parameters which_summary and
which_key are input, and the parameter longest_key is
output. This subroutine is useful for deciding on the
format for columnar output without actually making a pass

1-8

VOS System Administration: The Accounting Facility (R281M-00)

ACCOUNTING FACILITY SUBROUTINES

through any summaries.

s$acct_get_longest_key( which_summary, which_key, longest_key )

s$acct_init_summary_output
declare s$acct_init_summary_output entry( fixed bin(15),
fixed bin(15), fixed bin(15) );
The s$acct_init_summary_output subroutine sorts a given
summary and initializes it for output. A call to this
subroutine should be followed by calls to
s$acct_next_summary_output. The parameters which_summary
and delete_after are input.
s$acct_init_summary_output( which_summary, delete_after, code )
which_summary
The summary to be prepared.
delete_after
If this parameter value is nonzero, all data structures
for the summary will be freed at some convenient time
after the last call to s$acct_next_summary_output. If
you want to use a summary more than once, specify zero
as the value of this parameter all but the last time.
code
The value returned will be either zero or the operating
system error code e$too_many_entries. If there are
more than 32767 entries in the summary, code will be
nonzero and the extra entries will be arbitrarily
discarded. A message will already have been printed.

s$acct_next_summary_output
declare s$acct_next_summary_output entry( fixed bin(15),
fixed bin(15), fixed bin(15), (*) char(300) varying,
fixed bin(15) );
The subroutine s$acct_next_summary_output is used to
retrieve the next entry from a summary. After calling
s$acct_init_summary_output, call s$acct_next_summary_output
repeatedly until receiving the operating system error code
e$end_of_file. All parameters except max_num_keys are
output parameters. Each entry in the summary is put into
the external variable s$acct_record.
Each entry in the summary is a combination of all records
selected by the combination of keys for that entry that also
match the records selected by the call to
s$acct_processing_init. Records are combined into one entry
according to the following rules:

VOS System Administration: The Accounting Facility

1-9

ACCOUNTING FACILITY SUBROUTINES

1.

Fields that are counts contain the sum for all the
records.

2.

Fields that are maxima contain the maximum for all

the records.

3.

Other fields are taken from the first record

encountered, and probably are not useful.

s$acct_next_summary_output( first_key_change, max_num_keys,

num_keys, keys, code )
first_key_change
The number of the first key in the keys array that has
a different value than in the previous summary entry.
You can use this parameter to produce headings, by
using the first few keys as headings for a group of
related summary entries. This works because key 1 is
the primary key for the sort, key 2 is the secondary
key, and so forth.
max_num_keys
The number of entries allocated in the keys array.
num_keys
The number of keys this call actually puts into the
keys array.
keys
The keys, indexed by key number, for this summary
entry.
code
The value returned is either:

1-10

zero, if another entry is available

the operating system error code e$end_of_file,

if another entry is not available

the operating system error code

e$too_many_entries, if max_num_keys is too
small. However, this should not happen,
because the caller should know how many keys
there are.

VOS System Administration: The Accounting Facility (R281M-00)