1 02/07/86 general_ready, gr
2
3 Syntax as a command: gr -control_args
4
5
6 Syntax as an active function: gr -control_args
7
8
9 Function: prints a ready message containing specified values in a
10 specified format.
11
12
13 Control arguments prefix: You must use these control arguments
14 prior to the format ones. They allow you to override the default
15 formats for the contents of the ready message.
16 -control
17 allows you to specify the entire ioa_ control string used to format
18 the ready message. The string is passed to ioa_$nnl without change
19 so it must contain specifications for each of the various values to
20 be included in the ready message. The ioa_ control string formats
21 for the various values that you can insert into the ready message
22 are given below for each type of value see "List of Format Control
23 Arguments". This control argument overrides any format arguments
24 that would normally affect the format of the ready message; however,
25 you must still give format keywords to indicate which values are to
26 be output and the order in which these values correspond to the ioa_
27 control characters in the control string.
28
29
30 -string
31 allows you to specify the character string at the beginning of the
32 ready message. The argument following -string is used instead of
33 "r" at the beginning of the ready message. Since it is put into the
34 ioa_ control string, you can use "^/", "^R", and "^B" to cause new
35 lines, red ribbon shifts, and black ribbon shifts, respectively.
36
37
38 Control arguments format: The format and content of the ready
39 message are controlled by format control arguments. They include
40 control arguments that identify values to be included in the ready
41 message, optional precision numbers following some of these control
42 arguments that control the number of digits after the decimal point
43 in numeric values, and literal character strings that are inserted
44 in the ready message. The format control arguments are combined in
45 the order of their appearance in general_ready to form an ioa_
46 control string that controls the format of the ready message.
47
48 Processor usage values--
49 -active_string STR, -astr STR
50 expands the active string STR each time the ready message is
51 printed.
52
53
54 -inc_rcpu N
55 incremental real CPU value.
56 -inc_vcpu N
57 incremental virtual CPU value.
58 -total_rcpu N
59 total real CPU value.
60 -total_vcpu N
61 total virtual CPU value.
62
63 where N can be a single numeric digit from 1 to 9, indicating the
64 number of digits that should appear to the right of the decimal
65 point in the number that is output. The default is three digits.
66 The output format of the value can be described by the ioa_ control
67 string "^.Nf", where N is 3 by default.
68
69
70 Memory usage values--
71 -inc_mem_units N
72 incremental units.
73 -total_mem_units N
74 total memory units.
75
76 These control arguments are used in the same manner as the ones for
77 processor usage values.
78
79
80 Usage cost values--
81 -inc_cost N
82 incremental cost charges.
83 -total_cost N
84 cost charges.
85
86 These control arguments are used in the same manner as the ones for
87 processor usage values except that the default number of digits
88 following the decimal point is two. The output format of the value
89 can be described by the ioa_ control string " $^.Nf" where N is 2
90 by default.
91
92
93 Paging operations values--
94 -inc_bf
95 incremental bounds faults.
96 -inc_pft
97 incremental page faults.
98 -inc_sf
99 incremental segment faults.
100 -inc_vr
101 incremental VTOC reads.
102 -inc_vw
103 incremental VTOC writes.
104 -total_bf
105 bounds faults
106 -total_pft
107 page faults.
108
109
110 -total_sf
111 segment faults.
112 -total_vr
113 VTOC reads.
114 -total_vw
115 VTOC writes.
116
117 These control arguments are output by the ioa_ control string "^d",
118 where ^d is the number of demand page faults.
119
120
121 Command processor values--
122 -level, -lev
123 specifies the number of command processor invocations to be included
124 in the ready message. The level numbers are output by the ioa_
125 control string "^a", but the printed format can be described by
126 "level ^d". If the command processor level is 1, the printed format
127 is the null string. The number of digits is not settable.
128 -frame, -fr
129 specifies the number of stack frame level numbers to be included in
130 the ready message. The level numbers are output by the ioa_ control
131 string "^a", but the printed format can be described by "frame ^d".
132 If the command processor level is 1, the printed format is the null
133 string.
134 If you give both control arguments, the printed format can be
135 described by "level ^d,^d".
136
137
138 Date/time values--
139 -date
140 your default date format. Type "print_time_defaults date" to
141 display the format and "gr -date" to display a sample date value.
142 -date_time
143 your default date/time format. Type "print_time_defaults date_time"
144 to display the format and "gr -date_time" to display a sample
145 date/time value.
146 -day
147 two-digit day dd.
148 -day_name
149 three-character day of the week www.
150 -hour
151 two-digit hour hh.
152
153
154 -minute
155 two-digit minute mm
156 -month
157 two-digit month mm.
158 -time, -tm
159 your default time format. Type "print_time_defaults time" to
160 display the format and "gr -time" to display a sample value.
161 -time_format STR, -tfmt STR
162 where STR is a time format control string defining a user-specified
163 format for any of the various date values see time_format.gi.
164
165
166 -year
167 two-digit year yy
168 -zone
169 three-character time zone zzz.
170
171 These values can be described by the ioa control string "^a" except
172 for the -min, -day, and -year control arguments, which use the ioa_
173 control string "^a" without a leading space. The number of
174 digits is not settable.
175
176
177 Control arguments operation: The following control arguments affect
178 the operation of general_ready, but do not change the format of
179 ready messages.
180 -set
181 establishes general_ready as the current ready message procedure and
182 sets an alarm timer to catch shift changes. The command processor
183 then calls general_ready to print a ready message after each command
184 line is complete. In addition, the ready, ready_on, and ready_off
185 system commands determine the operation of general_ready.
186 -revert
187 makes the system ready procedure the current ready message procedure
188 and resets any timer alarms to catch shift changes.
189
190
191 -reset
192 resets incremental usage values to zero without printing a ready
193 message.
194 -call cmdline
195 when used with -set, calls the command processor to execute cmdline
196 after the completion of every command line. The argument cmdline is
197 a single argument to general_ready and you must therefore enclose it
198 in quotes if it contains any blanks. A frequent use of -call is
199 "-call print_messages -brief"; cmdline is executed even if the
200 printing of ready messages has been inhibited by executing
201 ready_off.
202
203
204 Notes on operation control arguments: The -set and -revert control
205 arguments are mutually exclusive. A general_ready command that
206 includes -set does not print a ready message; instead it saves the ioa_
207 control string built from the format and prefix control arguments in
208 the command and uses this ioa_ string to control the format of ready
209 messages printed when command lines complete execution or when a ready
210 command is issued. A general_ready command that includes -revert
211 prints a single ready message only if format or prefix control
212 arguments appear in the command with -revert; otherwise no ready
213 message is printed.
214
215 If you give neither -set nor -revert, general_ready prints one ready
216 message according to the format and prefix arguments given in the
217 command.
218
219
220 The program is designed to allow an almost arbitrary format at no
221 additional cost relative to the system's ready procedure other than
222 the one associated with general_ready, which sets up the ready message.
223 Once a ready message is specified, the ready, ready_on, and ready_off
224 commands control the printing of the ready message in the normal
225 manner.
226
227
228 The command builds up an ioa_ control string see the Subroutines
229 manual from the order of the keywords passed to it. The keywords
230 specify which values to output in the ready message. Virtual CPU usage
231 and cost can be printed. Both incremental usage usage accrued since
232 the last ready message produced by general_ready and total usage
233 usage accrued during this process can be in the same ready message
234 with the precision of the output the number of decimal places to the
235 right of the decimal point you specified. As a command, you can use
236 general_ready to either print a single ready message or define the
237 contents of the ready message printed by the ready command and after
238 every command line if you execute ready_on; as an active function, the
239 return value is the ready message.
240
241
242 The values for total virtual CPU time and total memory units is valid
243 across new processes. The value for cost is valid unless a shift
244 change occurred during a previous process. When you invoke
245 general_ready for the first time in a process, the cost of all usage in
246 that process up to that time is computed at the rates then in effect.
247
248 Due to the manner in which ready message procedures and procedures that
249 set up alarm timers are invoked, such procedures should not be
250 terminated by the terminate and terminate_refname commands. If you
251 want to terminate general_ready, invoke it with -revert before it is
252 terminated.