1 92-10-06 print_sys_log, psl
2
3 Syntax: psl LOG_SELECTOR -control_args
4
5
6 Function: prints selected portions of system logs, including the syserr
7 log, Answering Service, admin commands, and Data Management logs.
8 Various control arguments are used to determine which portions of the
9 log are printed, and the format of the output.
10
11
12 Arguments:
13 LOG_SELECTOR
14 is either the pathname of a named log or log family to be monitored,
15 or one of the "log selection" control arguments listed below.
16
17
18 Control arguments log selection:
19 -pathname LOG_PATH, -pn LOG_PATH
20 specifies that the named log or log family is to be examined.
21 -admin
22 specifies that the admin commands log is to be examined. The admin
23 commands log family is called "admin_log", and is located in the
24 >sc1>as_logs directory. This argument is incompatible with any of
25 the other log selection control arguments, or an explicit log
26 pathname.
27
28
29 -answering_service, -as
30 specifies that the Answering Service log is to be examined. The
31 Answering Service log family is called "log", and is located in the
32 >sc1>as_logs directory. This argument is incompatible with any of
33 the other log selection control arguments, or an explicit log
34 pathname.
35 -dm_system, -dms
36 specifies that the Data Management system log for the process's
37 current AIM authorization is to be examined. The Data Management
38 log family is called "dm_system_log", and its location depends on
39 the AIM access class of the log. This argument is incompatible with
40 any of the other log selection control arguments, or an explicit log
41 pathname. Reading the log requires access to the dm_admin_ gate.
42
43
44 -mc_log LOG_NAME, -mcl LOG_NAME
45 specifies that the message coordinator daemon log named LOG_NAME
46 is to be examined. All message coordinator logs are located in the
47 >sc1>as_logs directory; their names depend on the daemon to which
48 they belong. This argument is incompatible with any of the other
49 log selection control arguments, or an explicit log pathname.
50 -syserr
51 specifies that the syserr log is to be examined. The syserr log
52 family is named "syserr_log". The first segment in the family is
53 >sl1>syserr_log; there may be a history segment in >sl1, and older
54 history segments are in the directory >sc1>syserr_log. This
55 argument is incompatible with any of the other log selection control
56 arguments, or an explicit log pathname.
57
58
59 Control arguments limit selection:
60 -from TIME, -fm TIME, -from NUMBER, -fm NUMBER
61 specifies that the first message examined is the first message at or
62 after the specified time or sequence number; if -reverse is
63 specified, the first message is the one at or before the specified
64 value. If no -from value is specified, the default is the first
65 message in the log, or the last if -reverse is specified. This is
66 incompatible with -last.
67 -to TIME, -to NUMBER
68 specifies the last message to be examined, either by message time or
69 sequence number. If not specified, the default is all the remaining
70 messages in the log. This is incompatible with -for.
71
72
73 -last NUMBER, -lt NUMBER, -last TIME, -lt TIME
74 specifies that only the last NUMBER messages, or the messages since
75 TIME, are to be printed. If a NUMBER is specified, it specifies the
76 actual number of messages to be printed, not the number of messages
77 examined in the log. This is incompatible with -from and -for.
78 -for TIME, -for NUMBER
79 specifies a number of messages to print, or a time interval relative
80 to the starting time specified by -from in which the messages must
81 be contained. The number of messages is the actual number of
82 messages printed, not the number of messages examined in the log.
83 This is incompatible with -to and -last.
84
85
86 -forward, -fwd
87 specifies that the log is to be examined starting with the oldest
88 message selected by other control arguments, and proceed forwards.
89 Default
90 -reverse, -rv
91 specifies that the log is to be examined, starting with the most
92 recent message selected by other control arguments and proceeding
93 backwards.
94
95
96 Control arguments message selection:
97 -exclude STR-1 ... STR-n, -ex STR-1 ... STR-n
98 no message whose text contains one of the specified strings STR-1
99 to STR-n is processed. A string is interpreted either as a text
100 string, which must be an exact substring of the message text, or, if
101 surrounded by slashes, as a regular to match against the message
102 text. See the "Notes on String Matching" section below for details.
103 -match STR-1 ... STR-n, -mh STR-1 ... STR-n
104 only messages whose text contains one of the specified strings
105 STR-1 to STR-n are processed. The strings are processed as for
106 -exclude.
107 -all_text, -atxt
108 specifies that all log messages are to be processed, regardless of
109 text contents, cancelling the effect of any preceding -match or
110 -exclude. Default
111
112
113 -severity SEV-1 ... SEV-n, -sv SEV-1 ... SEV-n
114 only messages of the specified severity severities are processed.
115 The severity values SEV-1 to SEV-n may either be decimal integers,
116 or ranges consisting a pair of decimal integers separated by a colon
117 "20:29". If multiple severities are specified, or the -severity
118 control argument is specified more than once, all messages with any
119 of those severities are printed. A severity value must be between
120 -100 and 100. See the "Notes severity values" below for details.
121 -all_severities, -asv
122 messages of all severities are printed. This cancels the effect of
123 any previous -severity control arguments. Default
124
125
126 Control arguments message expansion:
127 -expand CLASS-1 ... CLASS-n, -exp CLASS-1 ... CLASS-n
128 specifies that binary data is to be expanded and displayed along
129 with the message text, for the selected messages. If a data class
130 value CLASS-1 to CLASS-n is specified, only binary data of the
131 specified classes will be expanded; otherwise, all selected messages
132 with binary data will be expanded. The type of expansion depends on
133 whether the -octal or -interpret control arguments are also
134 specified. See the "List of data classes" section below for
135 details. By default, no messages are expanded.
136 -no_expand, -nexp
137 specifies that no messages are to be displayed with binary data
138 expanded. This cancels the effect of any previous -expand control
139 arguments. By default, no messages are expanded.
140
141
142 -octal, -oc
143 specifies that the binary data in expanded messages is to be
144 displayed in octal, rather than, or in addition to, the interpreted
145 representation. If both octal and interpreted representations are
146 desired, both the -octal and -interpret control arguments must be
147 supplied.
148 -interpret, -int
149 specifies that the binary data in expanded messages is to be
150 displayed as interpreted text, by calling the appropriate
151 expand_XXX_msg_ program for the data class of the message. If the
152 -octal control argument is also specified, the binary data is
153 displayed both in interpreted form and as octal data. Default
154
155
156 -match_data STR-1 ... STR-n, -md STR-1 ... STR-n
157 only messages whose interpreted expanded data contains one of the
158 specified strings STR-1 to STR-n are processed. The strings are
159 processed as for -exclude. Note: This control argument merely
160 matches against the textual interpretation of the expanded data; if
161 this interpretation is to be displayed as well, the -interpret
162 control argument must also be specified.
163 -exclude_data STR-1 ... STR-n, -exd STR-1 ... STR-n
164 no message whose interpreted expanded data contains one of the
165 specified strings STR-1 to STR-n is processed. The strings are
166 processed as for -exclude. Note: This control argument merely
167 matches against the textual interpretation of the expanded data; if
168 this interpretation is to be displayed as well, the -interpret
169 control argument must also be specified.
170
171
172 -all_data, -ad
173 specifies that all log messages are to be processed, regardless of
174 interpreted expanded data contents, cancelling the effect of any
175 preceeding -match_data or -exclude_data. Default
176
177
178 -match_data_class CLASS-1 ... CLASS-n, -mdc CLASS-1 ... CLASS-n
179 only messages whose binary data class is one of the specified
180 strings CLASS-1 to CLASS-n are processed. Note: This control
181 argument merely matches against the data class; if the binary
182 data is to be displayed as well, the -octal or -interpret
183 control argument must also be specified.
184 -exclude_data_class CLASS-1 ... CLASS-n, -exdc CLASS-1 ... CLASS-n
185 no message whose binary data class is one of the specified
186 strings CLASS-1 to CLASS-n is processed. Note: This control
187 argument merely matches against the data class; if the binary
188 data is to be displayed as well, the -octal or -interpret
189 control argument must also be specified.
190
191
192 -all_data_classes, -adc
193 specifies that all log messages are to be processed, regardless of
194 binary data class, cancelling the effect of any preceeding
195 -match_data or -exclude_data. Default
196
197
198 Control arguments message format:
199 -line_length N, -ll N
200 specifies the line length used when formatting message text and data
201 for printing. The value N must be between 25 and 500. By
202 default, it is the line length associated with the user_output I/O
203 switch, or, if none as for an absentee, it is 132 for line
204 printer output.
205 -indent N, -ind N
206 specifies that all messages are to be formatted for printing
207 prefixed with N spaces. The value of N must be between 0 and 50.
208 The indentation is printed before any data associated with the
209 message, including the message prefix. By default, there is no
210 indentation.
211
212
213 -continuation_indent N, -ci N
214 specifies that all messages are to be formatted for printing with
215 continuation lines prefixed by N spaces, or, if the keyword
216 "standard" or "std" is used in place of a number, with the
217 continuation lines indented sufficiently to line up under the first
218 character of the text of the message. The value of N must be
219 between 0 and 50. By default, continuation lines are indented
220 to the "standard" indentation.
221
222
223 -prefix STRING, -pfx STRING
224 Specifies that all messages are to be formatted with the specified
225 string as a prefix. This prefix appears after the indentation if
226 any was specified. The prefix must explicitly include trailing
227 spaces, if any are desired to separate the prefix from the message
228 text. By default, there is no prefix.
229 -duplicates, -dup
230 inhibits the printing of "=" messages for messages whose text is the
231 same as the previous message printed. All messages are printed
232 exactly as they appear in the log.
233 -no_duplicates, -ndup
234 prints "==" for messages whose text is the same as the previous
235 message printed. Default
236
237
238 -date_format FORMAT_STRING, -dfmt FORMAT_STRING
239 specifies a date/time format string see time_format.gi.info to be
240 used when formatting the date when successive messages are printed
241 with different dates. The date string is printed on a line entirely
242 by itself, preceded by a blank line. If the date format string is
243 blank, no date separators will be printed; this should be used if a
244 -time_format string is specified that includes the date as well.
245 The default date string is "^9999yc-^my-^dm ^da ^za", which prints
246 as "1984-10-31 Wed est".
247
248 By specifying null strings for date, time, and number formats, the
249 log can be printed and saved; it can then be compared to another
250 log script later, without spurious mis-compares because the times
251 and sequence numbers do not match.
252
253
254 -time_format FORMAT_STRING, -tfmt FORMAT_STRING
255 specifies a date/time format string see time_format.gi.info to be
256 used when formatting the message time portion of the message. If
257 the string is null, no time is printed with the messages. The
258 default time format is "iso_time", which prints as "23:21:59".
259 -number_format IOA_STRING, -nfmt IOA_STRING
260 specifies an ioa_ string to be used when printing the sequence
261 number for the message. If the string is null, no sequence number
262 is printed with the message. The default is "^7d".
263
264
265 Control arguments miscellaneous:
266 -header, -he
267 specifies that a header is to be printed giving the times and
268 sequence numbers of the first and last messages processed.
269 Default
270 -no_header, -nhe
271 specifies that no header is to be printed.
272 -process_id, -pid
273 specifies that the process_id of the process which logged the
274 message is to be printed
275 -no_process_id, -npid
276 specifies that the process_id is not to be printed. Default
277
278
279 -data_class, -dc
280 specifies that the binary data class of the message is to be
281 printed. Note: This control argument merely specifies that the
282 data class name is to be printed; if the binary data is to be
283 displayed as well, the -octal or -interpret control argument
284 must also be specified.
285 -no_data_class, -ndc
286 specifies that the binary data class of the message is not to
287 be printed. Note: This control argument merely specifies that
288 the data class name is not to be printed; if the binary data is
289 not to be printed as well, the -no_expand control argument must
290 also be specified. Default
291
292
293 -absolute_pathname, -absp
294 specifies that the absolute pathname of any log segment examined
295 while processing messages is to be printed; the pathname of each
296 segment is printed only once, whenever segments are switched.
297 -no_absolute_pathname, -nabsp
298 specifies that log segment pathnames are not to be printed.
299 Default
300
301
302 -output_switch NAME, -osw NAME
303 specifies that the messages are to be written on the named I/O
304 switch. The default is user_output.
305 -procedure NAME, -proc NAME
306 specifies that entrypoints in the procedure called NAME are to be
307 used instead of entrypoints in log_read_ to read the log. This is
308 used to read logs protected by inner-ring subsystems, where the
309 inner-ring subsystem provides a replacement log-reading procedure.
310 See the "Notes on inner-ring logs" section, below.
311
312
313 Notes on string matching:
314 The strings specified by -match and -exclude, or by -match_data and
315 -exclude_data, are processed in sequence. An arbitrary number of
316 strings may follow any of those control arguments, and each string will
317 be treated as if it was preceded by another instance of the control
318 argument, except that any string beginning with a hyphen and not
319 immediately following one of the match/exclude control arguments is
320 treated as a new control argument, and no more strings are picked up
321 until the next match/exclude argument.
322
323
324 A string may be either a text string, in which case it is tested simply
325 to see whether it is a substring in the message, or it may be a regular
326 expression, which is matched against the message. A string will be
327 interpreted as a regular expression if it begins and ends with "/"
328 characters.
329
330
331 Each log message is processed against the set of strings, matching its
332 text or data to see if it contains the string. There are two simple
333 cases: only match strings, and only exclude strings. In the case of
334 only match strings, any log message that matches any of the strings
335 will be printed. In the case of only exclude strings, a log message
336 will be printed only if it matches none of the strings.
337
338
339 The more complicated case where match and exclude strings are mixed is
340 handled as follows: test the message against each string in turn. If
341 the message matches, and the string is a "-match" string, the
342 "print-this-message" flag is set on. If the message matches, and the
343 string is a "-exclude" string, the flag is set off. Otherwise, the
344 flag is unaffected. The flag's initial value is on if the first string
345 was a "-exclude" string, and off if the first string was a "-match"
346 string.
347
348
349 List of data classes:
350 A data class is a short string 1 to 16 characters stored with any
351 message that contains binary data, and is used to identify the expander
352 procedure used to expand the data into its interpreted textual form.
353 The data class is specified when the message is placed into the log.
354
355
356 syserr
357 identifies an old-style syserr log message. The "syserr binary"
358 code see syserr_binary_defs.incl.pl1 for a list is the first word
359 of the data in the message; the remaining words of data are the real
360 binary syserr data.
361 io_status
362 identifies a message indicating the status of an I/O device or an
363 error on that device. Binary data of this class should be
364 interpreted using the io_error_summary command.
365 hwfault
366 identifies a message containing machine state information from a
367 hardware failure. Binary data of this class should be interpreted
368 using the display_cpu_error command.
369
370
371 mos
372 identifies a message containing information about a main memory
373 auto-corrected error. Binary data of this class should be
374 interpreted using the mos_edac_summary command.
375 segdamage
376 identifies a message containing information about damage to a
377 particular storage system object.
378 voldamage
379 identifies a message containing information about damage to a
380 particular storage system volume.
381
382
383 mdc_del_uidpath
384 identifies a message containing the UID pathname of a master
385 directory which is missing but still registered.
386 mmdam
387 identifies a message containing information about the location
388 of main memory frames removed from service due to parity errors.
389 mpc_poll
390 identifies a message which contains MPC data filed by poll_mpc.
391 Binary data of this class should be interpreted using the
392 mpc_data_summary command.
393
394
395 fnp_poll
396 identifies a message which contains FNP data filed by poll_fnp.
397 Binary data of this class should be interpreted using the
398 fnp_data_summary command.
399 config
400 identifies a message containing a copy of "cards" from the system
401 config deck.
402 vtoce
403 identifies a message containing a copy of a VTOCE which was found
404 inconsistant by the system scavenger.
405
406
407 access_audit
408 identifies a message containing information about access attempts
409 to various system objects.
410 ibm3270_mde
411 identifies a message containing data about an error encountered
412 by the 3270 multiplexer.
413
414
415 Access required:
416 For all logs except inner-ring logs, read permission is required on the
417 log segments themselves, and status permission is required on their
418 containing directories. If an access error is encountered searching
419 for older history logs, the search is stopped at that point, and no
420 further history will be available. For the logs selected by control
421 arguments, the control argument descriptions list the standard history
422 directories for the logs.
423
424 For inner-ring logs the Data Management system log is the only
425 standard inner-ring log, access to the logs is required, as is access
426 to the gate used by the log-reading procedure see -procedure.
427
428
429 Notes on message selection:
430 Messages are selected for printing in a series of steps, each of which
431 filters out certain messages according to the control arguments
432 specified. The set of messages at each step is any message that were
433 left after the previous step. If a control argument was not specified,
434 then its corresponding step eliminates no messages. Note that the
435 -expand control arguments do NOT select messages, but only affect how
436 their contents are displayed:
437
438
439 1) -to stop looking after specified message
440 2) -from stop looking before specified number
441 3) -for TIME stop looking after specified time
442 4) -last TIME stop looking before specified time
443 5) -severity
444 6) -exclude eliminate matching messages
445 7) -match eliminate non-matching messages
446 8) -exclude_data eliminate matching messages
447 9) -match_data eliminate non-matching messages
448 10) -for NUMBER stop after NUMBER are printed
449 11) -last NUMBER stop after NUMBER are printed
450
451
452 Notes on severity values:
453 Severity values in log messages are used to indicate the importance of
454 the message being logged, in a general way. Most logs use increasing
455 severity to indicate increasing importance, but the actual meaning
456 depends on the log. For the Answering Service and Message Coordinator
457 logs, the severities have the following meanings:
458 0 => Message just logged
459 1 => Message logged and printed on a console
460 2 => Message logged and printed on a console with bells
461 3 => Message logged, printed, and the system crashed
462
463
464 For the syserr log, the severities have different meanings:
465 0 => Message logged and printed on syserr console
466 1 => Message logged, printed, and the system crashed
467 2 => Message logged, printed, and the process writing the
468 message is terminated.
469 3 => Message logged and printed, and console alarm sounded
470 4 => Message just logged, or printed if logging mechanism is
471 inoperable
472 5 => Message just logged, or discarded if it can't be logged
473
474 The severities 20 to 25, 30 to 35, and 40 to 45 are handled just like
475 0 to 5, but are different to indicate that the originating program was
476 writing an access audit message, rather than just an informative
477 message.
478
479
480 Notes on inner-ring logs:
481 Some applications create logs in an inner ring that must be read using
482 a special interface. The only standard log to do this is the Data
483 Management system log, and it is read by specifying the -dm_system
484 control argument which supplies both the pathname and the procedure
485 name dm_log_read_. Other applications may provide their own special
486 procedures for log reading, in which case both the log pathname and the
487 procedure name must be supplied explicitly via the -pathname and
488 -procedure control arguments. Note that a log read using a reader
489 procedure may enforce additional access requirements as well as
490 requiring access to the log itself. In particular, the user must have
491 access to the reader procedure.
492
493
494 Compatibility features--
495 The following control arguments are accepted for compatibility with the
496 old print_syserr_log and print_log commands:
497 -action => -severity
498 -next => -for
499 -debug, -db => -duplicates
500 The effect of print_syserr_log's -class argument can be achieved by
501 supplying a range to the -severity argument: "-class 2" is replaced by
502 "-severity 20:29".