MULTICS TECHNICAL BULLETIN                                MTB-648

To:       MTB Distribution

From:     Gary M. Palter

Date:     21 February 1984

Subject:  Improvements to Subsystem Metering

     This  MTB  presents a  proposal to  enhance the  metering of
interactive subsystems  provided through the  subsystem utilities
(ssu_).   The   enhancements  described  in   this  proposal  are
essential to the mail system performance project which is part of
the MR11 release.

Please direct any comments on this proposal to the author

     by the forum teleconferencing system to the meeting:
          >site>forum_dir>Subsystem_Utilities on System-M

     by electronic mail to:
          Gary M. Palter <GMP@HIS-PHOENIX-MULTICS.ARPA>

     or by the U.S. Postal service to:
          Honeywell Information Systems
          4 Cambridge Center
          Cambridge, Mass.  02142

_________________________________________________________________

Multics  Project  internal  working  documentation.   Not  to  be
distributed outside the project without the consent of the author
or the Director of Multics System Development.


MTB-648                Subsystem Metering                 MTB-648

WHY CHANGE SUBSYSTEM METERING?

     The  MR10.2 Multics  Mail System  has been  measured as 1.46
times slower than the MR10.1 system.   This ratio is based on the
comparison  of the  CPU time  used by each  mail system  to run a
"standard"  script   of  read_mail  and   send_mail  invocations.
However, there  is no evidence  which proves either  way that our
standard script is an accurate reflection  on the use of the mail
system.   In  other  words, we  really  don't know  how  the user
communities will perceive the performance of the new mail system.

     The performance of the mail  system must be improved as much
as possible before the MR11 release.

Gathering the Necessary Data

     In  order  to  improve  the  performance  of  an interactive
subsystem, it is  necessary to know which requests  are used most
often.  Once these requests are  identified, they can be analyzed
in detail  in order to improve  their performance and, therefore,
improve  the  overall  performance  of  the  subsystem.  However,
simply  knowing  which requests  are executed  most often  is not
sufficient.  One  must also know  which of these  frequently used
requests use  the most resources (CPU,  paging, etc).  Otherwise,
one could spend considerable effort optimizing the performance of
a  request  which,  while  used far  more  often  than  any other
request,  contributes  very  little  to  the  total  cost  of the
subsystem (eg:  the self_identify request).

     The subsystem  utilities could easily gather  the data sited
above as  part of the standard  subsystem request loop.  However,
the only  data that the  utilities collect at present  is who has
used a subsystem and how often.

     Therefore, we must change the subsystem metering facility to
record more data.

Security

     The current subsystem metering facility is insecure.

     The  data  segments  maintained  by  the  subsystem metering
facility are kept  in the user-ring with write  access granted to
all users.  Thus,  any user can destroy the  metering data either
accidentally or maliciously.

     Therefore, the metering data must  be moved to an inner ring
to be made more secure.


MTB-648                Subsystem Metering                 MTB-648

AIM

     As  a  consequence of  being  stored in  the  user-ring, the
subsystem metering data can only be recorded by processes running
at  a  specific AIM  authorization (normally  system_low).  Thus,
metering data is needlessly lost.

     Therefore, the  metering data must be  moved to ring-1 where
it  can be  kept in a  multi-class segment to  allow recording by
processes at multiple authorizations.

     However,  care  must  be  excersized when  making  this data
multi-class to  insure that no new  write-down paths are created.
In  the present  design of  the subsystem  metering facility, the
subsystem utilities use the record of how many times the user has
invoked a  given version of  the subsystem to  control whether to
print the message announcing a  new version of the subsystem.  If
this facility  were left intact  with multi-class data,  a rather
large write-down path would be created.

     Therefore, the mechanism used to control when version change
announcements are displayed must be separated from the collection
of metering data.   The simplest way to make  this split would be
to  store  the  data  required  to  control  the  version  change
announcements in the user's value segment.

THE PROPOSAL

     This MTB proposes the creation of two separate facilities --
a   subsystem   metering   facility  and   a   subsystem  version
announcement  facility.   These  facilities  are  designed  to be
upwards-compatible for  existing subsystems.  In  other words, no
subsystem maintainer will be required  to make any changes to the
code of their subsystem in order to use these new facilities.

Subsystem Metering

     The new  subsystem metering facility will  store its data in
ring-1, multi-class metering segments.   By default, all metering
segments     will     be      stored     in     the     directory
>site>subsystem_usage_dir.    For   private  subsystems,   a  new
entrypoint, ssu_$set_usage_meters_path, will be provided to allow
the subsystem  maintainer to specify a  non-standard location for
his subsystem's metering segment.

     A  new  command,  subsystem_usage_meters,  will  be  used to
create  or delete  these metering  segments.  The  maximum access
class  of  data  to be  recorded  in  a metering  segment  may be
specified     when     the    segment     is     created.     The


MTB-648                Subsystem Metering                 MTB-648

subsystem_usage_meters  command will  also be  able to  reset the
metering segment to its initial state (ie:  empty).

WHAT DATA WILL BE METERED?

     Three different  sets of metering  data will be  recorded in
the metering segment.  The subsystem_usage_meters command will be
able  to selectively  enable/disable recording  of any  or all of
these sets of  data.  With the increase in the  amount of data to
be displayed,  the syntax of  the display_subsystem_usage command
would become incomprehensible.  Rather  than face this situation,
the display_subsystem_usage  command will be retired  in favor of
several distinct options of the subsystem_usage_meters command.

     The first set of metering  data will be per-user data.  This
data  will  correspond exactly  to  the data  which  is currently
recorded by the present facility.  However, as the formats of the
metering segments  are completely different and  the current data
can not  really be trusted,  no conversion of  old style metering
segments will be made.

     The second  set of metering  data will be  per-version data.
There  will be  one "record"  for each  different version  of the
subsystem  which has  been used  at the  site.  This  record will
contain  the version  number, total number  of invocations, total
number  of  users  who  have used  this  version,  and  the total
resource usage data accumlated  for this version.  Resource usage
data is the data  returned by hcs_$get_process_usage and includes
virtual  CPU time,  page faults,  segment faults,  bounds faults,
VTOC reads, and VTOC  writes.  The subsystem_usage_meters command
will display per-invocation averages for the resource usage data.

     The  third set  of metering  data will  be per-request data.
There will be  one "record" for each pairing  of request name and
subsystem  version.  This  record will contain  the request name,
version number,  number of invocations  in which the  request was
defined, number of times the request was invoked, number of times
the request  called ssu_$abort_line, and the  resource usage data
listed     above     for    the     per-version     data.     The
subsystem_usage_meters command will display the average number of
times the  request was used  in an invocation,  the percentage of
invocations of  the request which  aborted, and averages  for the
resource usage data.

     The per-user data mentioned above  will contain a bit map of
which versions the user has invoked to allow the per-version user
counts to be  maintained accurately.  This bit map  limits to 200
the  number  of  distinct versions  which  may be  recorded  in a
metering segment.   This limit should  not be a  problem.  If, in
some  future release,  we find that  this limit is  a problem, it


MTB-648                Subsystem Metering                 MTB-648

will  be  possible  to provide  a  mechanism to  delete  the data
associated with older versions of the subsystem.

WHEN WILL THE DATA BE GATHERED?

     For non-standalone  invocations (ie:  the  normal case), the
subsystem   utilities   will  collect   the  metering   data  and
automatically enter it into the subsystem's metering segment when
the  invocation  is destroyed.   In other  words, if  a subsystem
metering segment has been created  for a subsystem, the subsystem
will  always  be metered.   Any calls  to ssu_$record_usage  in a
non-standalone invocation will be ignored.

     Standalone invocations  will have to  be treated differently
as  they are  often created simply  to record an  invocation of a
subsystem  (eg:  video)  or to simplify  argument processing (eg:
the mail system).  Therefore, metering data will not be collected
automatically for standalone invocations.  Instead, metering data
consisting of  the per-user information and  the per-version user
counts will be added to the  metering segment only when a call to
ssu_$record_usage   or   ssu_$print_blast  (or   its  replacement
described  below) is  made.  Resource  usage is  not recorded for
standalone  invocations  as  the  values  obtained  may  bear  no
relationship  to the  actual resource utilization  of the program
being metered.

     The  metering  facility  will  automatically  add  per-user,
per-version, and per-request records to the metering segment when
needed.   In other  words, no  administrative action  is required
when a new  version of a subsystem is made  available or when new
requests are added to a subsystem.

HOW WILL METERING AFFECT PERFORMANCE?

     The  metering  facility  should have  the  smallest possible
impact on the performance of a subsystem.

     To  achieve the  above goal,  the number  of times  during a
subsystem invocation that the utilities  will be forced to access
the  metering  segment  must  be  minimized.   By  collecting the
per-request data in per-invocation  storage in the user-ring, the
utilities will only have to  access the metering segment once per
invocation when the invocation  is destroyed.  All data collected
by  the  utilities will  be added  to the  metering segment  in a
single call to the ring-1 ssu_meters_ gate.

     In order to minimize the time requred to actually update the
metering  segment,  hash  tables  will  be  used  to  locate  the
per-user, per-version,  and per-request data records  that are to
be updated.


MTB-648                Subsystem Metering                 MTB-648

Version Change Announcements

     As  mentioned  above,  the  data  needed  by  the  subsystem
utilities  for determining  when to announce  a new  version of a
subsystem will be recorded in the user's value segment.  The data
will be placed  in the value segment's data  space under the name
SUBSYSTEM.version._ where SUBSYSTEM is  the name of the subsystem
as   given    in   the   call    to   ssu_$create_invocation   or
ssu_$standalone_invocation.  (E.g:  read_mail.version._).

     A  new entrypoint,  ssu_$announce_version, will  be added to
replace  ssu_$print_blast.   However,  ssu_$print_blast  will  be
retained  as  an  undocumented interface  for  compatibility with
existing subsystems.

     The  calling sequence  of ssu_$announce_version  will differ
from  that of  ssu_$print_blast for two  reasons.  First, several
parameters  of ssu_$print_blast  will no longer  have any meaning
(eg:   ref_ptr).   Second, ssu_$announce_version  will  accept an
ioa_  control  string  and   optional  arguments  to  format  the
subsystem-specific portion of the version announcement.

     In order  to insure that  users continue to  receive version
announcements,  the  subsystem utilities  will print  the version
announcement once per process if the user's default value segment
does  not exist.   However, the  utilities themselves  will never
create  the  default value  segment.  If  a user  complains about
seeing  a  version  announcement  too many  times,  he  should be
instructed to create his default  value segment in order to allow
the version announcement facility to operate properly.

DOCUMENTATION CHANGES

     The  remainder  of  this  MTB consists  of  the Programmer's
Reference  Manual  writeup  for  subsystem  metering  and version
announcements,     the     Commands     Manual     writeup    for
subsystem_usage_meters, and  the Subroutines Manual  writeups for
ssu_$announce_version,           ssu_$record_usage,           and
ssu_$set_usage_meters_path.


MTB-648                Subsystem Metering                 MTB-648

                           APPENDIX A

                 MULTICS PROGRAMMING ENVIRONMENT

INTERACTIVE SUBSYSTEM PROGRAMMING ENVIRONMENT

Subsystem Invocations

SUBSYSTEM METERING

     The  subsystem  utilities  provide  the  ability  to collect
several  forms   of  metering  data  for   any  given  subsystem.
Collection  and  display  of  this data  is  performed  using the
subsystem_usage_meters command described in the Commands Manual.

     The metering data for a subsystem is recorded in a subsystem
metering  segment.     Metering   segments  are  created  by  the
subsystem_usage_meters command's create operation and are deleted
by the delete operation.  In  addition, a metering segment may be
reinitialized  through  the  use  of  the  subsystem_usage_meters
command's reset operation.

     A subsystem metering segment is a ring-1 multi-class segment
which  may  contain  data  collected  at  several  different  AIM
authorizations.  Therefore,  a user is only  permitted to display
the  metering data  for a given  subsystem either  if his process
authorization is  greater than the  access class of  the metering
segment or if he has the AIM seg privilege enabled.

     By default, the metering segment used by the utilities for a
given      subsystem      resides      in      the      directory
>site>subsystem_usage_dir  and  is   named  SUBSYSTEM.ssum  where
SUBSYSTEM   is  the   subsystem  name   given  in   the  call  to
ssu_$create_invocation   or   ssu_$standalone_invocation.   (E.g:
read_mail.ssum).  The pathname of the metering segment to be used
in a single invocation of  the subsystem may be changed, however,
by calling  ssu_$set_usage_meters_path which is  described in the
Subroutines Manual.

     Three  different  classes of  data  may be  collected  for a
subsystem  --  per-version data,  per-user data,  and per-request
data.   The recording  of each  class of  data may  be controlled
independently  through  the  use  of  the  subsystem_usage_meters
command's enable and disable operations.


MTB-648                Subsystem Metering                 MTB-648

     The   per-version  data   supplies  information   about  the
different versions  of the subsystem.  This  data is displayed by
the subsystem_usage_meters  command's display_versions operation.
Per-version data is only collected  for the first 200 versions of
a subsystem.  The  data recorded for each version  of a subsystem
includes
  o  the subsystem version number,
  o  the number of invocations of this version of the subsystem,
  o  the number  of  users  who  have used  this  version  of the
          subsystem, and
  o  the per-invocation average for this version of the subsystem
          of the following:
            o  virtual CPU time,
            o  page faults,
            o  segment faults,
            o  bounds faults,
            o  VTOC reads, and
            o  VTOC writes.

     The per-user  data supplies information  about the different
users  of   the  subsystem.   This  data   is  displayed  by  the
subsystem_usage_meters  command's  display_users  operation.  The
data recorded for each user of a subsystem includes
  o  the user's Person_id,
  o  the total number of times that he has used this subsystem,
  o  the version number of the version  of this subsystem that he
          has used most recently,
  o  the number of  times that he  has used the  above version of
          this subsystem in succession, and
  o  the date/time that he last used this subsystem.

     The   per-request  data   supplies  information   about  the
different  requests  defined  by   a  subsystem.   This  data  is
displayed     by     the     subsystem_usage_meters     command's
display_requests  operation.   The  data   for  each  request  is
recorded on  a per-subsystem version basis  to allow the analysis
of the changes  in the usage and performance  of requests between
releases.   The  data  recorded  for each  request  defined  by a
subsystem for a single version of said subsystem includes
  o  the request name,
  o  the subsystem version number,
  o  the average number  of times this  request was used  in each
          invocation of this version of the subsystem,
  o  the percentage  of  invocations  of  this  request  in  this
          version of  the subsystem which were  aborted by a call
          to ssu_$abort_line,
  o  the per-invocation average for this  request in this version
          of the subsystem of the following:
            o  virtual CPU time,
            o  page faults,
            o  segment faults,
            o  bounds faults,


MTB-648                Subsystem Metering                 MTB-648

            o  VTOC reads, and
            o  VTOC writes.

     Once a subsystem metering  segment is created, the utilities
will automatically collect the appropriate data provided that the
subsystem  invocation is  not a  standalone invocation;  ie:  the
subsystem  maintainer  need not  include  any extra  code  in his
subsystem  to  enable  metering.   For  a  standalone invocation,
however,  the  subsystem  maintainer   must  include  a  call  to
ssu_$record_usage in the subsystem to request that the invocation
be metered.

SUBSYSTEM VERSION ANNOUNCEMENTS

     The  subsystem utilities  provide a  convenient mechanism to
inform users when a new version of a subsystem is made available.
This mechanism  is called a  version announcement.    The version
announcement  consists of  the subsystem name  and version number
and  an  optional   subsystem-specific  message.   The  subsystem
message usually  briefly describes the major  new features of the
new  version  along  with  a reference  to  more  detailed online
documentation.

     A   version    announcement   is   displayed    by   calling
ssu_$announce_version.  This  entrypoint uses data  stored in the
user's default  value segment to  decide whether or  not to print
the version announcement.  Said data  is stored in the data space
of  the value  segment under  the name  SUBSYSTEM.version._ where
SUBSYSTEM   is  the   subsystem  name   given  in   the  call  to
ssu_$create_invocation   or   ssu_$standalone_invocation.   (E.g:
read_mail.version._).

     If the previously used version  of the subsystem as recorded
in   the   value   segment    is   not   the   current   version,
ssu_$announce_version  will print  the version  announcement.  If
the   previously   used   version   is   the   current   version,
ssu_$announce_version will  still print the  version announcement
if  said announcement  has not  been issued  the number  of times
requested by the caller unless said announcement has already been
issued in this process.  After displaying a version announcement,
ssu_$announce_version will  automatically update the  data stored
in the value segment.

     If  the  user's  default   value  segment  does  not  exist,
ssu_$announce_version  will print  the version  announcement once
per  process  regardless  of how  often  the user  has  seen said
announcement.


MTB-648                Subsystem Metering                 MTB-648

______________________                     ______________________

subsystem_usage_meters                     subsystem_usage_meters
______________________                     ______________________

                           APPENDIX B

                            COMMANDS

Name:  subsystem_usage_meters, ssum

     This command is the user and administrative interface to the
metering facilities supplied by the subsystem utilities.  See the
description of interactive subsystem metering in the Programmer's
Reference Manual for additional information.

SYNTAX

     ssum operation ssum_path {-control_args}

ARGUMENTS

operation identifies  the  operation  to  be  performed  by  this
          invocation    of    subsystem_usage_meters.    Detailed
          descriptions of the supported operations follow.

ssum_path is the pathname of the  metering segment which is to be
          processed.  The  suffix ssum is  supplied if necessary.
          If  an entryname  is used  (ie:  the  pathname does not
          contain a ">" or "<"), the metering segment must reside
          in the directory >site>subsystem_usage_dir.

-control_args
          are  control   arguments  specific  to   the  requested
          operation and are described below.

NOTES

     By  default,  the  metering  segment for  a  given subsystem
resides in  the directory >site>subsystem_usage_dir  and is named
SUBSYSTEM.ssum where SUBSYSTEM is the subsystem name given in the
call  to  ssu_$create_invocation  or  ssu_$standalone_invocation.
Thus,  using  just  the  subsystem   name  as  the  ssum_path  is
sufficient for most subsystems.


MTB-648                Subsystem Metering                 MTB-648

______________________                     ______________________

subsystem_usage_meters                     subsystem_usage_meters
______________________                     ______________________

subsystem_usage_meters Operation:  create, cr

     This  operation  creates  the  specified  subsystem metering
segment.

SYNTAX

     ssum create ssum_path {-control_args}

CONTROL ARGUMENTS

-access_class STR, -acc STR
          specifies the maximum access class of data that will be
          recorded  in this  metering segment.   The access class
          specified  by STR  must be  less than  or equal  to the
          user's   maximum  process   authorization.   (Default--
          system_low)

ACCESS REQUIRED

     The user must have sma access  to the directory in which the
metering segment is to be created.

NOTES

     All three classes of  metering -- per-version, per-user, and
per-request -- will be enabled by default in the metering segment
created  by  this  operation.   Use  the  enable  and/or  disable
operations of this  command to change the state  of recording for
the various classes of metering.


MTB-648                Subsystem Metering                 MTB-648

______________________                     ______________________

subsystem_usage_meters                     subsystem_usage_meters
______________________                     ______________________

subsystem_usage_meters Operation:  delete, dl

     This  operation  deletes  the  specified  subsystem metering
segment.

SYNTAX

     ssum delete ssum_path {-control_args}

CONTROL ARGUMENTS

-force, -fc
          deletes the  metering segment without  first asking for
          confirmation.

-no_force, -nfc
          asks  for  confirmation  before  actually  deleting the
          metering segment.  (Default)

ACCESS REQUIRED

     The user  must have sma  access to the  directory containing
the metering segment.

            ________________________________________

subsystem_usage_meters Operation:  enable

     This  operation  enables  the  subsequent  recording  of the
requested  classes of  metering data  in the  specified subsystem
metering segment.

SYNTAX

     ssum enable ssum_path -control_args

CONTROL ARGUMENTS

-all, -a  specifies  that  all  classes  of  metering  are  to be
          enabled.  This  control argument is  mutually exclusive


MTB-648                Subsystem Metering                 MTB-648

______________________                     ______________________

subsystem_usage_meters                     subsystem_usage_meters
______________________                     ______________________

          with  all  other  control  arguments  accepted  by this
          operation.

-requests, -rq
          specifies that the recording  of per-request data is to
          be enabled.

-versions specifies that the recording  of per-version data is to
          be enabled.

-users    specifies that the recording of  per-user data is to be
          enabled.

ACCESS REQUIRED

     The user  must have sma  access to the  directory containing
the metering segment.

NOTES

     Use of this operation will  not disable the recording of any
class  of metering  which is not  specified on  the command line.
The  disable  operation  must   be  used  to  explicitly  disable
recording.

            ________________________________________

subsystem_usage_meters Operation:  disable

     This  operation  disables  the subsequent  recording  of the
requested  classes of  metering data  in the  specified subsystem
metering segment.

SYNTAX

     ssum disable ssum_path -control_args

CONTROL ARGUMENTS

-all, -a  specifies  that  all  classes  of  metering  are  to be
          disabled.  This control  argument is mutually exclusive


MTB-648                Subsystem Metering                 MTB-648

______________________                     ______________________

subsystem_usage_meters                     subsystem_usage_meters
______________________                     ______________________

          with  all  other  control  arguments  accepted  by this
          operation.

-requests, -rq
          specifies that the recording  of per-request data is to
          be disabled.

-versions specifies that the recording  of per-version data is to
          be disabled.

-users    specifies that the recording of  per-user data is to be
          disabled.

ACCESS REQUIRED

     The user  must have sma  access to the  directory containing
the metering segment.

NOTES

     Use of this  operation will not enable the  recording of any
class  of metering  which is not  specified on  the command line.
The enable operation must be used to explicitly enable recording.

            ________________________________________

subsystem_usage_meters Operation:  reset, rs

     This operation resets the  meters in the specified subsystem
metering  segment to  their initial  (ie:  empty)  state.  Use of
this  operation  is  equivalent  to deleting  and  recreating the
metering segment.

SYNTAX

     ssum reset ssum_path {-control_args}

CONTROL ARGUMENTS

-force, -fc
          specifies  that  the  user  is not  to  be  queried for
          confirmation before the meters are reset.


MTB-648                Subsystem Metering                 MTB-648

______________________                     ______________________

subsystem_usage_meters                     subsystem_usage_meters
______________________                     ______________________

-no_force, -nfc
          specifies   that  the   user  is  to   be  queried  for
          confirmation  before  the  meters  are  actually reset.
          (Default)

ACCESS REQUIRED

     The user  must have sma  access to the  directory containing
the metering segment.

            ________________________________________

subsystem_usage_meters Operation:  display_users, dsu

     This  operation displays  the per-user  data which  has been
recorded in the specified subsystem metering segment.

SYNTAX

     ssum dsu ssum_path {-control_args}

CONTROL ARGUMENTS

-header, -he
          prints  a  header  defining   each  column  of  output.
          (Default)

-no_header, -nhe
          does not print the header.

-reverse, -rv
          prints the entries in reverse order from that selected.

-no_reverse, -nrv
          prints the entries in the selected order.  (Default)

-totals, -tt
          prints  only  the totals  line  described below  in the
          "Notes".   This control  argument is  incompatible with
          -sort and -first.

-sort STR sorts  the individual  entries before  displaying them.
          This  control  argument is  incompatible  with -totals.


MTB-648                Subsystem Metering                 MTB-648

______________________                     ______________________

subsystem_usage_meters                     subsystem_usage_meters
______________________                     ______________________

          See "List of sorting types" below.

-user STR prints  only  those entries  for users  whose Person_id
          matches   STR.    The  star   convention   is  allowed.
          (Default-- all Person_ids)

-version STR
          prints only those entries for users whose most recently
          used  version of  the subsystem matches  STR.  The star
          convention is allowed.  (Default-- all versions)

-first N  prints  only  the  first  N  entries  which  match  the
          selection  criteria;  when combined  with  the -reverse
          control argument, prints only  the last N entries.  The
          entries are sorted, if requested, before application of
          this  control  argument.    This  control  argument  is
          incompatible with -totals.

LIST OF SORTING TYPES

     The individual  user entries may be  sorted according to one
of the following four criteria:

name      sorts by the entry's Person_id.

count     sorts  by the  entry's total number  of invocations for
          this subsystem.

date_time_used, dtu
          sorts by the entry's date/time used for this subsystem.

version   sorts by the entry's most recently used version of this
          subsystem.

ACCESS REQUIRED

     Either the user's process authorization must be greater than
or equal to the access class of the subsystem metering segment or
the user must have enabled the AIM seg privilege.

NOTES

     The  information  displayed for  an  individual user  of the
subsystem includes


MTB-648                Subsystem Metering                 MTB-648

______________________                     ______________________

subsystem_usage_meters                     subsystem_usage_meters
______________________                     ______________________

  o  the user's Person_id,
  o  the total number of times that he has used this subsystem,
  o  the version number of the version  of this subsystem that he
          has used most recently,
  o  the number of  times that he  has used the  above version of
          this subsystem in succession, and
  o  the date/time that he last used this subsystem.

     The totals line reflects only those user entries which match
the selection  criteria given by  -user and/or -version.   If all
versions  of  the subsystem  are selected,  the totals  line will
consist  of  the total  number  of selected  users and  the total
number of  invocations of the  subsystem by said  users.  If only
some versions of the subsystem are selected, the totals line will
consist of the  total number of selected users,  the total number
of  invocations of  the subsystem  by said  users, and  the total
number of invocations  of said versions of the  subsystem by said
users who most recently used one of the selected versions.

            ________________________________________

subsystem_usage_meters Operation:  display_versions, dsv

     This operation displays the  per-version data which has been
recorded in the given subsystem metering segment.

SYNTAX

     ssum dsv ssum_path {-control_args}

CONTROL ARGUMENTS

-header, -he
          prints  a  header  defining   each  column  of  output.
          (Default)

-no_header, -nhe
          does not print the header.

-totals, -tt
          prints  only  the totals  line  described below  in the
          "Notes".


MTB-648                Subsystem Metering                 MTB-648

______________________                     ______________________

subsystem_usage_meters                     subsystem_usage_meters
______________________                     ______________________

-version STR
          selects  only  those  versions  of  the  subsystem  for
          display  whose  version number  matches STR.   The star
          convention is allowed.  (Default-- all versions)

ACCESS REQUIRED

     Either the user's process authorization must be greater than
or equal to the access class of the subsystem metering segment or
the user must have enabled the AIM seg privilege.

NOTES

     The  information  displayed  for  a  single  version  of the
subsystem includes
  o  the subsystem version number,
  o  the number of invocations of this version of the subsystem,
  o  the number  of  users  who  have used  this  version  of the
          subsystem, and
  o  the per-invocation average for this version of the subsystem
          of the following:
            o  virtual CPU time,
            o  page faults,
            o  segment faults,
            o  bounds faults,
            o  VTOC reads, and
            o  VTOC writes.

     The totals line contains the  same fields as the per-version
detail  lines  described  above.  Furthermore,  the  averages and
totals  in  the  totals line  reflect  only that  data  which was
accumulated for  those versions selected by  the -version control
argument (if any).


MTB-648                Subsystem Metering                 MTB-648

______________________                     ______________________

subsystem_usage_meters                     subsystem_usage_meters
______________________                     ______________________

subsystem_usage_meters Operation:  display_requests, dsrq

     This operation displays the  per-request data which has been
recorded in the given subsystem metering segment.

SYNTAX

     ssum dsrq ssum_path {-control_args}

CONTROL ARGUMENTS

-header, -he
          prints  a  header  defining   each  column  of  output.
          (Default)

-no_header, -nhe
          does not print the header.

-totals, -tt
          prints  only  the totals  line  described below  in the
          "Notes" for each request.

-request STR, -rq STR
          selects  only those  requests defined  by the subsystem
          whose request name matches STR.  The star convention is
          allowed.  (Default-- all requests)

-version STR
          restricts the data displayed  for each selected request
          to  that  collected  only  for  those  versions  of the
          subsystem whose  version number matches  STR.  The star
          convention is allowed.  (Default-- all versions)

ACCESS REQUIRED

     Either the user's process authorization must be greater than
or equal to the access class of the subsystem metering segment or
the user must have enabled the AIM seg privilege.

NOTES

     The data displayed for each selected request consists of the
request's name,  a line of information  for each selected version


MTB-648                Subsystem Metering                 MTB-648

______________________                     ______________________

subsystem_usage_meters                     subsystem_usage_meters
______________________                     ______________________

in which the request is  defined unless -totals is specified, and
a totals line which summarizes the data in the per-version detail
lines.

     The  information  displayed  for  a  given  request  in  the
per-version detail line includes
  o  the subsystem version number,
  o  the average number  of times this  request was used  in each
          invocation of this version of the subsystem,
  o  the percentage  of  invocations  of  this  request  in  this
          version of  the subsystem which were  aborted by a call
          to ssu_$abort_line,
  o  the per-invocation average for this  request in this version
          of the subsystem of the following:
            o  virtual CPU time,
            o  page faults,
            o  segment faults,
            o  bounds faults,
            o  VTOC reads, and
            o  VTOC writes.

     The  totals  line for  a  single request  contains  the same
fields   as  the   per-version  detail   lines  described  above.
Furthermore,  the  averages and  percentages  in the  totals line
reflect only  that data which was  accumulated for those versions
selected by the -version control argument (if any).


MTB-648                Subsystem Metering                 MTB-648

____                                                         ____

ssu_                                                         ssu_
____                                                         ____

                           APPENDIX C

                           SUBROUTINES

Name:  ssu_

Entry:  ssu_$announce_version

     This entrypoint prints a message announcing a new version of
a subsystem  if appropriate.  See the  description of interactive
subsystem  version  announcements in  the  Programmer's Reference
Manual for additional information.

USAGE

     dcl  ssu_$announce_version entry () options (variable);

     call ssu_$announce_version (sci_ptr, threshold, ioa_string,
               optional_arguments);

ARGUMENTS

sci_ptr             (pointer, Input)
          is  a pointer  to the  subsystem control  structure for
          this  invocation as  returned by ssu_$create_invocation
          or ssu_$standalone_invocation.

threshold           (fixed binary, Input)
          is the maximum number of times that the announcement of
          a new version should be printed for a given user.

ioa_string          (character (*), Input, optional)
          is an ioa_  control string which is used  to format the
          subsystem-specific   portion   of   the   new   version
          announcement.  This argument may be either a varying or
          nonvarying  string.  If  this argument  is not present,
          the  announcement  will consist  only of  the subsystem
          name and version.

optional_arguments  (Input, optional)
          are arguments  to be substituted into  the ioa_ control
          string  and  may  only  be  present  if  the ioa_string
          argument is given.  These arguments  may be of any data
          type required by the control string.


MTB-648                Subsystem Metering                 MTB-648

____                                                         ____

ssu_                                                         ssu_
____                                                         ____

Entry:  ssu_$record_usage

     This  entrypoint  records  the  invocation  of  a standalone
subsystem  in the  per-user section  of the  system-wide metering
database for  the subsystem.  See the  description of interactive
subsystem  metering  in  the  Programmer's  Reference  Manual for
additional information.

USAGE

     dcl  ssu_$record_usage entry (pointer);

     call ssu_$record_usage (sci_ptr);

ARGUMENTS

sci_ptr             (Input)
          is  a pointer  to the  subsystem control  structure for
          this       invocation        as       returned       by
          ssu_$standalone_invocation.

NOTES

     For  compatibility  with earlier  releases,  this entrypoint
will also accept three arguments  in which case the last argument
will be assumed to be a status  code and will be set to zero.  In
addition,  any  call  to  this entrypoint  from  a  subsystem not
created as a standalone invocation will be ignored.

            ________________________________________

Entry:  ssu_$set_usage_meters_path

     This entrypoint changes the pathname of the metering segment
to  be  used  by  this  invocation  of  the  subsystem.   See the
description of interactive subsystem metering in the Programmer's
Reference Manual for additional information.

USAGE

     dcl  ssu_$set_usage_meters_path entry (pointer,
               character (*), character (*), fixed binary (35));


MTB-648                Subsystem Metering                 MTB-648

____                                                         ____

ssu_                                                         ssu_
____                                                         ____

     call ssu_$set_usage_meters_path (sci_ptr, ssum_dirname,
               ssum_ename, code);

ARGUMENTS

sci_ptr             (Input)
          is  a pointer  to the  subsystem control  structure for
          this  invocation as  returned by ssu_$create_invocation
          or ssu_$standalone_invocation.

ssum_dirname        (Input)
          is  the absolute  pathanme of  the directory containing
          the metering  segment to be used  by this invocation of
          the subsystem.

ssum_ename          (Input)
          is the entryname of the  metering segment to be used by
          this  invocation.   The  suffix  ssum  is  supplied  if
          necessary.

code                (Output)
          is a standard system status code.

NOTES

     By  default,  the  metering  segment for  a  given subsystem
resides in  the directory >site>subsystem_usage_dir  and is named
SUBSYSTEM.ssum where SUBSYSTEM is the subsystem name given in the
call to ssu_$create_invocation or ssu_$standalone_invocation.

     This  entrypoint  does not  check for  the existence  of the
requested  metering segment.   If the  metering segment  does not
exist,  no  data  will be  recorded  for this  invocation  of the
subsystem.

     In order  to change the  pathname of the  subsystem metering
segment  for  a standalone  invocation,  this entrypoint  must be
invoked before calling the ssu_$record_usage entrypoint.