02/07/86  general_ready, gr

Syntax as a command:  gr {-control_args}


Syntax as an active function:  [gr {-control_args}]


Function: prints a ready message containing specified values in a
specified format.


Control arguments (prefix): You must use these control arguments
   prior to the format ones.  They allow you to override the default
   formats for the contents of the ready message.
-control
   allows you to specify the entire ioa_ control string used to format
   the ready message.  The string is passed to ioa_$nnl without change
   so it must contain specifications for each of the various values to
   be included in the ready message.  The ioa_ control string formats
   for the various values that you can insert into the ready message
   are given below for each type of value (see "List of Format Control
   Arguments").  This control argument overrides any format arguments
   that would normally affect the format of the ready message; however,
   you must still give format keywords to indicate which values are to
   be output and the order in which these values correspond to the ioa_
   control characters in the control string.


-string
   allows you to specify the character string at the beginning of the
   ready message.  The argument following -string is used instead of
   "r" at the beginning of the ready message.  Since it is put into the
   ioa_ control string, you can use "^/", "^R", and "^B" to cause new
   lines, red ribbon shifts, and black ribbon shifts, respectively.


Control arguments (format): The format and content of the ready
   message are controlled by format control arguments.  They include
   control arguments that identify values to be included in the ready
   message, optional precision numbers following some of these control
   arguments that control the number of digits after the decimal point
   in numeric values, and literal character strings that are inserted
   in the ready message.  The format control arguments are combined in
   the order of their appearance in general_ready to form an ioa_
   control string that controls the format of the ready message.

   Processor usage values--
-active_string STR, -astr STR
   expands the active string STR each time the ready message is
   printed.


-inc_rcpu {N}
   incremental real CPU value.
-inc_vcpu {N}
   incremental virtual CPU value.
-total_rcpu {N}
   total real CPU value.
-total_vcpu {N}
   total virtual CPU value.

   where N can be a single numeric digit from 1 to 9, indicating the
   number of digits that should appear to the right of the decimal
   point in the number that is output.  The default is three digits.
   The output format of the value can be described by the ioa_ control
   string "^.Nf", where N is 3 by default.


   Memory usage values--
-inc_mem_units {N}
   incremental units.
-total_mem_units {N}
   total memory units.

   These control arguments are used in the same manner as the ones for
   processor usage values.


   Usage cost values--
-inc_cost {N}
   incremental cost charges.
-total_cost {N}
   cost charges.

   These control arguments are used in the same manner as the ones for
   processor usage values except that the default number of digits
   following the decimal point is two.  The output format of the value
   can be described by the ioa_ control string " $^.Nf" where N is 2
   by default.


   Paging operations values--
-inc_bf
   incremental bounds faults.
-inc_pft
   incremental page faults.
-inc_sf
   incremental segment faults.
-inc_vr
   incremental VTOC reads.
-inc_vw
   incremental VTOC writes.
-total_bf
   bounds faults
-total_pft
   page faults.


-total_sf
   segment faults.
-total_vr
   VTOC reads.
-total_vw
   VTOC writes.

   These control arguments are output by the ioa_ control string "^d",
   where ^d is the number of demand page faults.


  Command processor values--
-level, -lev
   specifies the number of command processor invocations to be included
   in the ready message.  The level numbers are output by the ioa_
   control string "^a", but the printed format can be described by
   "level ^d".  If the command processor level is 1, the printed format
   is the null string.  The number of digits is not settable.
-frame, -fr
   specifies the number of stack frame level numbers to be included in
   the ready message.  The level numbers are output by the ioa_ control
   string "^a", but the printed format can be described by "frame ^d".
   If the command processor level is 1, the printed format is the null
   string.
   If you give both control arguments, the printed format can be
   described by "level ^d,^d".


   Date/time values--
-date
   your default date format.  Type "print_time_defaults date" to
   display the format and "gr -date" to display a sample date value.
-date_time
   your default date/time format.  Type "print_time_defaults date_time"
   to display the format and "gr -date_time" to display a sample
   date/time value.
-day
   two-digit day (dd).
-day_name
   three-character day of the week (www).
-hour
   two-digit hour (hh).


-minute
   two-digit minute (mm)
-month
   two-digit month (mm).
-time, -tm
   your default time format.  Type "print_time_defaults time" to
   display the format and "gr -time" to display a sample value.
-time_format STR, -tfmt STR
   where STR is a time format control string defining a user-specified
   format for any of the various date values (see time_format.gi).


-year
   two-digit year (yy)
-zone
   three-character time zone (zzz).

   These values can be described by the ioa control string "^a" except
   for the -min, -day, and -year control arguments, which use the ioa_
   control string "^a" (without a leading space).  The number of
   digits is not settable.


Control arguments (operation): The following control arguments affect
   the operation of general_ready, but do not change the format of
   ready messages.
-set
   establishes general_ready as the current ready message procedure and
   sets an alarm timer to catch shift changes.  The command processor
   then calls general_ready to print a ready message after each command
   line is complete.  In addition, the ready, ready_on, and ready_off
   system commands determine the operation of general_ready.
-revert
   makes the system ready procedure the current ready message procedure
   and resets any timer alarms to catch shift changes.


-reset
   resets incremental usage values to zero without printing a ready
   message.
-call cmdline
   when used with -set, calls the command processor to execute cmdline
   after the completion of every command line.  The argument cmdline is
   a single argument to general_ready and you must therefore enclose it
   in quotes if it contains any blanks.  A frequent use of -call is
   "-call print_messages -brief"; cmdline is executed even if the
   printing of ready messages has been inhibited by executing
   ready_off.


Notes on operation control arguments: The -set and -revert control
arguments are mutually exclusive.  A general_ready command that
includes -set does not print a ready message; instead it saves the ioa_
control string built from the format and prefix control arguments in
the command and uses this ioa_ string to control the format of ready
messages printed when command lines complete execution or when a ready
command is issued.  A general_ready command that includes -revert
prints a single ready message only if format or prefix control
arguments appear in the command with -revert; otherwise no ready
message is printed.

If you give neither -set nor -revert, general_ready prints one ready
message according to the format and prefix arguments given in the
command.


The program is designed to allow an almost arbitrary format at no
additional cost (relative to the system's ready procedure) other than
the one associated with general_ready, which sets up the ready message.
Once a ready message is specified, the ready, ready_on, and ready_off
commands control the printing of the ready message in the normal
manner.


The command builds up an ioa_ control string (see the Subroutines
manual) from the order of the keywords passed to it.  The keywords
specify which values to output in the ready message.  Virtual CPU usage
and cost can be printed.  Both incremental usage (usage accrued since
the last ready message produced by general_ready) and total usage
(usage accrued during this process) can be in the same ready message
with the precision of the output (the number of decimal places to the
right of the decimal point) you specified.  As a command, you can use
general_ready to either print a single ready message or define the
contents of the ready message printed by the ready command (and after
every command line if you execute ready_on); as an active function, the
return value is the ready message.


The values for total virtual CPU time and total memory units is valid
across new processes.  The value for cost is valid unless a shift
change occurred during a previous process.  When you invoke
general_ready for the first time in a process, the cost of all usage in
that process up to that time is computed at the rates then in effect.

Due to the manner in which ready message procedures and procedures that
set up alarm timers are invoked, such procedures should not be
terminated (by the terminate and terminate_refname commands).  If you
want to terminate general_ready, invoke it with -revert before it is
terminated.


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


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