02/20/85  metering_util_


Entry points in metering_util_:
   (List is generated by the help command)


The metering_util_ subroutine contains several entry points useful for
collecting hardcore metering data.  In general, hardcore metering data
elements can be categorized as samples, cumulative times, or cumulative
counts (the latter two being cumulative since system initialization).
Samples are snapshots of variables that describe the state of some
system object (e.g, number of processes eligible at this instant).  An
example of a cumulative count is the total number of read I/Os issued
to a particular disk device since system initialization, while an
example of a cumulative time is the total busy time of a particular
disk device while processing read I/Os.  It is easy to compute average
I/O time for a read to a particular device from these last two items.


If a given set of metering data is sampled periodically, then more
interesting, time-varying data can be computed.  For example, the
average I/O time for a read during a certain time interval can be
computed.  That interval is the time between any two samples of the
data; subtracting the earlier cumulative count of I/Os from the later
count yields the incremental count (i.e., the count of I/Os during the
interval).


Multics metering commands are designed for interactive use, with the
interval boundaries defined by the user in real time.  Typically,
metering commands support the following control arguments:
-report
   prints a report of activity since the last interval boundary (or
   since system initialization, if no boundary has been defined).
-reset
   defines an interval boundary for this metering program; all further
   invocations of this command display data reflecting activity since
   this boundary.
-report_reset
   reports and then resets.


Under this scheme, each display of data, establishment of an interval
boundary, etc., is done in a separate invocation of the same metering
program.  This allows the user to establish an interval boundary,
exercise the system in some fashion, and then print data describing the
system performance while it was being exercised.  Additionally, a user
can run any number of metering programs, each with independent interval
boundaries.  These considerations imply that metering data collection
(which is sampling of hardcore data bases) should be global to the
process (in order to exist through multiple invocations of the same
metering command) and be distinguished among different metering
programs.


To use this subroutine, sufficient access to copy all hardcore regions
specified is required.  Access to the phcs_ gate is sufficient.  If all
hardcore regions specified are defined in
>sl1>ring_zero_meters_limits.ascii, then access to metering_gate_ is
sufficient.


:Entry:  define_regions:  02/20/85 metering_util_$define_regions


Function:  This entry is used to define a set of sections of hardcore
data bases which are of interest to the invoker.  Upon return,
sufficient static storage has been allocated to contain two copies of
each hardcore region specified in the call; this storage has also been
initialized to zero.


Syntax:
declare code fixed bin (35); declare unique_index fixed bin; declare
     metering_util_$define_regions entry options (variable);
call metering_util_$define_regions (unique_index, code,
          hardcore_seg_1, begin_region_1, end_region_1, ...  , ...  ,
          ...  hardcore_seg_n, begin_region_n, end_region_n);


Arguments:
unique_index
   is a unique identifier for the set of regions.  This identifier must
   be used in calls to other metering_util_ entry points.  (Output)
code
   is a standard status code.  The code error_table_$wrong_no_of_args
   is returned if the number of arguments remaining is not modulo 3.
   (Output)


The remaining arguments must be in groups of three, as shown in the
calling sequence above.  Each such group defines a hardcore region by
specifying a hardcore segment and a contiguous region within the
segment.  The arguments in each group, in order, are the following:
hardcore_seg_i
   identifies the ring 0 data base.  It may be of the form char (*), in
   which case it is assumed to be the name of a ring 0 segment; or of
   the form ptr aligned, in which case it is assumed to be a pointer to
   the segment.  In the latter case, only the segment number is
   significant.  (Input)


begin_region_i
   identifies the beginning of the region in the ring 0 data base.  It
   may be of the form char (*), in which case it is assumed to be the
   name of an external symbol in hardcore_seg_i; or of the form fixed
   bin, in which case it is assumed to be a word offset into
   hardcore_seg_i.  (Input)
end_region_i
   identifies the end of the region in the ring 0 data base.  It may be
   of the form char (*), in which case it is assumed to be the name of
   an external symbol in hardcore_seg_i that refers to the next word
   beyond the end of the region; or of the form fixed bin, in which
   case it is assumed to be the length of the region in words.  (Input)


Notes:  Any errors encountered by this entry point are reported to the
user by means of the sub_err_ subroutine.  Examples of such errors are
invalid segment names or symbol names, or invalid region specification
(e.g., nonpositive length).  Errors of this sort are always programming
errors, and are not external circumstances from which the calling
program can be expected to recover.


:Entry:  fill_buffers:  02/20/85 metering_util_$fill_buffers


Function:  This entry is used to copy the current contents of all
regions defined for the specified unique identifier into the current
buffers for that unique identifier, and to return pointers to the
current and previous buffers for these regions.


Syntax:
declare metering_util_$fill_buffers entry (fixed bin, fixed bin(71),
     char(10), (*) ptr, (*) ptr, fixed bin(35));
call metering_util_$fill_buffers (unique_index, meter_time,
     formatted_time, current_ptrs, previous_ptrs, code);


Arguments:
unique_index
   is the unique identifier returned by metering_util_$define_regions
   (above).  (Input)
meter_time
   is the total metering time in microseconds.  The total metering time
   is defined as the time between the last call to metering_util_$reset
   and this call.  If metering_util_$reset has not been called, the
   total metering time is defined as the time between the last system
   bootload and this call.  (Output)


formatted_time
   is the total metering time in a format suitable for printing.  This
   format is
      HHHH:MM:SS
   where this represents the decomposition of total metering time into
   hours (HH), minutes (MM), and seconds (SS).  (Output)
current_ptrs
   is an array of pointers that, on return, contain pointers to the
   current buffers for the hardcore regions defined in the call to
   metering_util_$define_regions.  The number of elements in this array
   must be equal to the number of hardcore regions defined in the call
   to metering_util$define regions.  The elements of this array are
   pointers to the current buffers for the corresponding hardcore
   regions.  Specifically, current_ptrs (i) contains on return a
   pointer to the current buffer for hardcore_seg_i (defined above).
   (Output)


previous_ptrs
   is an array of pointers which, on return, contain pointers to the
   previous buffers for the hardcore regions defined in the call to
   metering_util_$define_regions.  The number of elements in this array
   must be equal to the number of hardcore regions defined in the call
   to metering_util_$define regions.  The elements of this array are
   pointers to the previous buffers for the corresponding hardcore
   regions.  Specifically, previous_ptrs (i) contains on return a
   pointer to the previous buffer for hardcore_seg_i (defined above).
   (Output)
code
   is a standard status code.  If either the array current_ptrs or the
   array previous_ptrs does not have the proper number of elements (see
   above), the code error_table_$invalid_array_size is returned, and no
   action is performed.  (Output)


:Entry:  reset:  02/20/85 metering_util_$reset


Function:  This entry point is called to reset the metering interval to
the time of this call.  This is done by copying the current buffers
into the previous buffers for all regions defined for the unique index
specified.


Syntax:
declare metering_util_$reset entry (fixed bin, fixed bin(35));
call metering_util_$reset (unique_index, code);


Arguments:
unique_index
   is as above.  (Input)
code
   is as above.  (Output)


                                          -----------------------------------------------------------


Historical Background

This edition of the Multics software materials and documentation is provided and donated
to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. 
as a contribution to computer science knowledge.  
This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology,
Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL
and BULL HN Information Systems Inc. to the development of this operating system. 
Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970),
renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership
of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture 
for managing computer hardware properly and for executing programs. Many subsequent operating systems 
incorporated Multics principles.
Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., 
as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. .

                                          -----------------------------------------------------------

Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without
fee is hereby granted,provided that the below copyright notice and historical background appear in all copies
and that both the copyright notice and historical background and this permission notice appear in supporting
documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining
to distribution of the programs without specific prior written permission.
    Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc.
    Copyright 2006 by BULL HN Information Systems Inc.
    Copyright 2006 by Bull SAS
    All Rights Reserved