1 07/26/82 command_usage_count, cuc
  2 
  3 Syntax:  cuc operation {command_names} {-control_args}
  4 
  5 
  6 Function:  provides a record of the number of times commands are used
  7 and the User_ids for each invocation of them.  The commands to be
  8 metered in this way must be listed in a segment named
  9 command_usage_list_.  Usage totals are stored in a segment named
 10 command_usage_totals_.  This command actually performs three
 11 operations:  it prints and clears the meters, adds commands to
 12 command_usage_list_, and deletes commands from command_usage_list_.
 13 
 14 
 15 List of operations:
 16 add
 17    adds commands to the list (command_usage_list_) of commands to be
 18    metered.  Commands added to the list in a single invocation of
 19    the "cuc add" command form a command "group", which can be
 20    manipulated as a whole.
 21 delete, dl
 22    deletes command groups (see above) from the list of commands to
 23    be metered.
 24 print, pr
 25    prints (and clears) the metered data (subject to any restrictions
 26    the specified control_args impose).
 27 
 28 
 29 Arguments:
 30 command_names
 31    are long or short names of commands.  If given with either the print
 32    or delete operation, only one command name from each group to be
 33    printed or deleted need be given, and all the commands in each group
 34    so represented are acted upon.  If no names are given with the print
 35    or delete operation, all command groups are printed/deleted.
 36    Command names (long and/or short) must be given with the add
 37    operation, and all the names added in a single invocation are added
 38    as a single group to the list.  Short names of commands can only be
 39    used with the print and delete operations if they were specified
 40    with the add operation.
 41 
 42 
 43 Control arguments:
 44 -all, -a
 45    prints meters for all the command groups, or deletes all command
 46    groups from the list.  This is the default for the print and delete
 47    operations if no command_names are given.  This control_arg cannot
 48    be used with the add operation.
 49 -brief, -bf
 50    omits column headings from the printout (can only be used with the
 51    print operation).  The default is to print column headings.
 52 -clear, -cl
 53    clears the usage counters and user list when meters are printed (can
 54    only be used with the print operation).  It clears the user list
 55    even if the -total control_arg is also specified.
 56 
 57 
 58 -first N, -ft N
 59    prints only the N greatest users of the specified commands (can only
 60    be used with the print operation).  This control_arg cannot be used
 61    in conjunction with the -total control_arg.
 62 -total, -tt
 63    prints only the total use of the commands in the specified command
 64    groups, when used with the print operation.  When used with the add
 65    operation, meters only the total usage of commands specified.  The
 66    default with both of these operations is to print/meter the users of
 67    the commands as well as total usage.  See "Notes" below.  This
 68    control_arg cannot be used with the delete operation.
 69 
 70 
 71 Access required:  In order to add and delete commands, and to clear
 72 meters, the user must have rw access to the command_usage_list_
 73 segment.  Otherwise, all users should have r access to
 74 command_usage_list_, and rw access to command_usage_totals_.  Both
 75 segments are found using object search rules and most commonly are in
 76 >sss (system_library_standard directory).  If they are not in >sss, a
 77 link in >sss points to them.
 78 
 79 
 80 Notes:  For each group of commands added without the -total control
 81 argument, this command creates a segment named command_name.usage in
 82 >sss (or, if a link is there, wherever the link points).  The user must
 83 put the link in >sss before the first usage of cuc add, since the
 84 metering program creates the command_name.usage segment in the same
 85 directory in which it finds command_usage_list_.  The
 86 command_name.usage segment contains the list of User_ids for those
 87 using the commands in the group.  User_ids are printed in the order of
 88 greatest usage.  When the -first control argument is given, in addition
 89 to printing the user count and name for the N greatest users, this
 90 command prints an additional line giving the user count for "all
 91 others."
 92 
 93 
 94 At sites using the access isolation mechanism (AIM), only the usage of
 95 system_low users is recorded.
 96 
 97 
 98 Examples:  In the following example, assume that no commands are listed
 99 in the command_usage_list_ segment.  The user adds two commands (in two
100 separate command groups) by typing:
101      command_usage_count add set_search_rules ssr
102      cuc add enter_abs_request ear -total
103 The next time a process is created, those commands can be metered by
104 typing:
105      cuc print
106 
107 
108 The following lines are then displayed:
109      USAGE COMMAND USER USER
110      COUNT GROUP COUNT NAME
111          3     set_search_rules
112                ssr
113                              2    Baker.Multics
114                              1    Green.SysMaint
115          1 enter_abs_request
116                ear
117 
118 Note that user count and user name are not provided for the command
119 group added with the -total control_arg.
120 
121 
122 To delete these commands from the list, the user types:
123      cuc delete -all
124 
125 or the equivalent:
126      cuc dl