92-10-06  print_sys_log, psl

Syntax:  psl LOG_SELECTOR {-control_args}


Function: prints selected portions of system logs, including the syserr
log, Answering Service, admin commands, and Data Management logs.
Various control arguments are used to determine which portions of the
log are printed, and the format of the output.


Arguments:
LOG_SELECTOR
   is either the pathname of a named log or log family to be monitored,
   or one of the "log selection" control arguments listed below.


Control arguments (log selection):
-pathname LOG_PATH, -pn LOG_PATH
   specifies that the named log or log family is to be examined.
-admin
   specifies that the admin commands log is to be examined.  The admin
   commands log family is called "admin_log", and is located in the
   >sc1>as_logs directory.  This argument is incompatible with any of
   the other log selection control arguments, or an explicit log
   pathname.


-answering_service, -as
   specifies that the Answering Service log is to be examined.  The
   Answering Service log family is called "log", and is located in the
   >sc1>as_logs directory.  This argument is incompatible with any of
   the other log selection control arguments, or an explicit log
   pathname.
-dm_system, -dms
   specifies that the Data Management system log for the process's
   current AIM authorization is to be examined.  The Data Management
   log family is called "dm_system_log", and its location depends on
   the AIM access class of the log.  This argument is incompatible with
   any of the other log selection control arguments, or an explicit log
   pathname.  Reading the log requires access to the dm_admin_ gate.


-mc_log LOG_NAME, -mcl LOG_NAME
   specifies that the message coordinator (daemon) log named LOG_NAME
   is to be examined.  All message coordinator logs are located in the
   >sc1>as_logs directory; their names depend on the daemon to which
   they belong.  This argument is incompatible with any of the other
   log selection control arguments, or an explicit log pathname.
-syserr
   specifies that the syserr log is to be examined.  The syserr log
   family is named "syserr_log".  The first segment in the family is
   >sl1>syserr_log; there may be a history segment in >sl1, and older
   history segments are in the directory >sc1>syserr_log.  This
   argument is incompatible with any of the other log selection control
   arguments, or an explicit log pathname.


Control arguments (limit selection):
-from TIME, -fm TIME, -from NUMBER, -fm NUMBER
   specifies that the first message examined is the first message at or
   after the specified time or sequence number; if -reverse is
   specified, the first message is the one at or before the specified
   value.  If no -from value is specified, the default is the first
   message in the log, or the last if -reverse is specified.  This is
   incompatible with -last.
-to TIME, -to NUMBER
   specifies the last message to be examined, either by message time or
   sequence number.  If not specified, the default is all the remaining
   messages in the log.  This is incompatible with -for.


-last NUMBER, -lt NUMBER, -last TIME, -lt TIME
   specifies that only the last NUMBER messages, or the messages since
   TIME, are to be printed.  If a NUMBER is specified, it specifies the
   actual number of messages to be printed, not the number of messages
   examined in the log.  This is incompatible with -from and -for.
-for TIME, -for NUMBER
   specifies a number of messages to print, or a time interval relative
   to the starting time (specified by -from) in which the messages must
   be contained.  The number of messages is the actual number of
   messages printed, not the number of messages examined in the log.
   This is incompatible with -to and -last.


-forward, -fwd
   specifies that the log is to be examined starting with the oldest
   message selected by other control arguments, and proceed forwards.
   (Default)
-reverse, -rv
   specifies that the log is to be examined, starting with the most
   recent message selected by other control arguments and proceeding
   backwards.


Control arguments (message selection):
-exclude STR-1 ...  STR-n, -ex STR-1 ...  STR-n
   no message whose text contains one of the specified strings (STR-1
   to STR-n) is processed.  A string is interpreted either as a text
   string, which must be an exact substring of the message text, or, if
   surrounded by slashes, as a regular to match against the message
   text.  See the "Notes on String Matching" section below for details.
-match STR-1 ...  STR-n, -mh STR-1 ...  STR-n
   only messages whose text contains one of the specified strings
   (STR-1 to STR-n) are processed.  The strings are processed as for
   -exclude.
-all_text, -atxt
   specifies that all log messages are to be processed, regardless of
   text contents, cancelling the effect of any preceding -match or
   -exclude.  (Default)


-severity SEV-1 ...  SEV-n, -sv SEV-1 ...  SEV-n
   only messages of the specified severity (severities) are processed.
   The severity values (SEV-1 to SEV-n) may either be decimal integers,
   or ranges consisting a pair of decimal integers separated by a colon
   ("20:29").  If multiple severities are specified, or the -severity
   control argument is specified more than once, all messages with any
   of those severities are printed.  A severity value must be between
   -100 and 100.  See the "Notes (severity values)" below for details.
-all_severities, -asv
   messages of all severities are printed.  This cancels the effect of
   any previous -severity control arguments.  (Default)


Control arguments (message expansion):
-expand {CLASS-1 ...  CLASS-n}, -exp {CLASS-1 ...  CLASS-n}
   specifies that binary data is to be expanded and displayed along
   with the message text, for the selected messages.  If a data class
   value (CLASS-1 to CLASS-n) is specified, only binary data of the
   specified classes will be expanded; otherwise, all selected messages
   with binary data will be expanded.  The type of expansion depends on
   whether the -octal or -interpret control arguments are also
   specified.  See the "List of data classes" section below for
   details.  By default, no messages are expanded.
-no_expand, -nexp
   specifies that no messages are to be displayed with binary data
   expanded.  This cancels the effect of any previous -expand control
   arguments.  By default, no messages are expanded.


-octal, -oc
   specifies that the binary data in expanded messages is to be
   displayed in octal, rather than, or in addition to, the interpreted
   representation.  If both octal and interpreted representations are
   desired, both the -octal and -interpret control arguments must be
   supplied.
-interpret, -int
   specifies that the binary data in expanded messages is to be
   displayed as interpreted text, by calling the appropriate
   expand_XXX_msg_ program for the data class of the message.  If the
   -octal control argument is also specified, the binary data is
   displayed both in interpreted form and as octal data.  (Default)


-match_data STR-1 ...  STR-n, -md STR-1 ...  STR-n
   only messages whose interpreted expanded data contains one of the
   specified strings (STR-1 to STR-n) are processed.  The strings are
   processed as for -exclude.  Note: This control argument merely
   matches against the textual interpretation of the expanded data; if
   this interpretation is to be displayed as well, the -interpret
   control argument must also be specified.
-exclude_data STR-1 ...  STR-n, -exd STR-1 ...  STR-n
   no message whose interpreted expanded data contains one of the
   specified strings (STR-1 to STR-n) is processed.  The strings are
   processed as for -exclude.  Note: This control argument merely
   matches against the textual interpretation of the expanded data; if
   this interpretation is to be displayed as well, the -interpret
   control argument must also be specified.


-all_data, -ad
   specifies that all log messages are to be processed, regardless of
   interpreted expanded data contents, cancelling the effect of any
   preceeding -match_data or -exclude_data.  (Default)


-match_data_class CLASS-1 ... CLASS-n, -mdc CLASS-1 ... CLASS-n
   only messages whose binary data class is one of the specified
   strings (CLASS-1 to CLASS-n) are processed.  Note: This control
   argument merely matches against the data class; if the binary
   data is to be displayed as well, the -octal or -interpret
   control argument must also be specified.
-exclude_data_class CLASS-1 ... CLASS-n, -exdc CLASS-1 ... CLASS-n
   no message whose binary data class is one of the specified
   strings (CLASS-1 to CLASS-n) is processed.  Note: This control
   argument merely matches against the data class;  if the binary
   data is to be displayed as well, the -octal or -interpret
   control argument must also be specified.


-all_data_classes, -adc
   specifies that all log messages are to be processed, regardless of
   binary data class, cancelling the effect of any preceeding
   -match_data or -exclude_data.  (Default)


Control arguments (message format):
-line_length N, -ll N
   specifies the line length used when formatting message text and data
   for printing.  The value (N) must be between 25 and 500.  By
   default, it is the line length associated with the user_output I/O
   switch, or, if none (as for an absentee), it is 132 (for line
   printer output).
-indent N, -ind N
   specifies that all messages are to be formatted for printing
   prefixed with N spaces.  The value of N must be between 0 and 50.
   The indentation is printed before any data associated with the
   message, including the message prefix.  By default, there is no
   indentation.


-continuation_indent N, -ci N
   specifies that all messages are to be formatted for printing with
   continuation lines prefixed by N spaces, or, if the keyword
   "standard" or "std" is used in place of a number, with the
   continuation lines indented sufficiently to line up under the first
   character of the text of the message.  The value of N must be
   between 0 and 50.  By default, continuation lines are indented
   to the "standard" indentation.


-prefix STRING, -pfx STRING
   Specifies that all messages are to be formatted with the specified
   string as a prefix.  This prefix appears after the indentation (if
   any was specified).  The prefix must explicitly include trailing
   spaces, if any are desired to separate the prefix from the message
   text.  By default, there is no prefix.
-duplicates, -dup
   inhibits the printing of "=" messages for messages whose text is the
   same as the previous message printed.  All messages are printed
   exactly as they appear in the log.
-no_duplicates, -ndup
   prints "==" for messages whose text is the same as the previous
   message printed.  (Default)


-date_format FORMAT_STRING, -dfmt FORMAT_STRING
   specifies a date/time format string (see time_format.gi.info) to be
   used when formatting the date when successive messages are printed
   with different dates.  The date string is printed on a line entirely
   by itself, preceded by a blank line.  If the date format string is
   blank, no date separators will be printed; this should be used if a
   -time_format string is specified that includes the date as well.
   The default date string is "^9999yc-^my-^dm ^da ^za", which prints
   as "1984-10-31 Wed est".

   By specifying null strings for date, time, and number formats, the
   log can be printed and saved; it can then be compared to another
   log script later, without spurious mis-compares because the times
   and sequence numbers do not match.


-time_format FORMAT_STRING, -tfmt FORMAT_STRING
   specifies a date/time format string (see time_format.gi.info) to be
   used when formatting the message time portion of the message.  If
   the string is null, no time is printed with the messages.  The
   default time format is "iso_time", which prints as "23:21:59".
-number_format IOA_STRING, -nfmt IOA_STRING
   specifies an ioa_ string to be used when printing the sequence
   number for the message.  If the string is null, no sequence number
   is printed with the message.  The default is "^7d".


Control arguments (miscellaneous):
-header, -he
   specifies that a header is to be printed giving the times and
   sequence numbers of the first and last messages processed.
   (Default)
-no_header, -nhe
   specifies that no header is to be printed.
-process_id, -pid
   specifies that the process_id of the process which logged the
   message is to be printed
-no_process_id, -npid
   specifies that the process_id is not to be printed.  (Default)


-data_class, -dc
   specifies that the binary data class of the message is to be
   printed.  Note: This control argument merely specifies that the
   data class name is to be printed; if the binary data is to be
   displayed as well, the -octal or -interpret control argument
   must also be specified.
-no_data_class, -ndc
   specifies that the binary data class of the message is not to
   be printed.  Note: This control argument merely specifies that
   the data class name is not to be printed; if the binary data is
   not to be printed as well, the -no_expand control argument must
   also be specified.  (Default)


-absolute_pathname, -absp
   specifies that the absolute pathname of any log segment examined
   while processing messages is to be printed; the pathname of each
   segment is printed only once, whenever segments are switched.
-no_absolute_pathname, -nabsp
   specifies that log segment pathnames are not to be printed.
   (Default)


-output_switch NAME, -osw NAME
   specifies that the messages are to be written on the named I/O
   switch.  The default is user_output.
-procedure NAME, -proc NAME
   specifies that entrypoints in the procedure called NAME are to be
   used instead of entrypoints in log_read_ to read the log.  This is
   used to read logs protected by inner-ring subsystems, where the
   inner-ring subsystem provides a replacement log-reading procedure.
   See the "Notes on inner-ring logs" section, below.


Notes on string matching:
The strings specified by -match and -exclude, or by -match_data and
-exclude_data, are processed in sequence.  An arbitrary number of
strings may follow any of those control arguments, and each string will
be treated as if it was preceded by another instance of the control
argument, except that any string beginning with a hyphen and not
immediately following one of the match/exclude control arguments is
treated as a new control argument, and no more strings are picked up
until the next match/exclude argument.


A string may be either a text string, in which case it is tested simply
to see whether it is a substring in the message, or it may be a regular
expression, which is matched against the message.  A string will be
interpreted as a regular expression if it begins and ends with "/"
characters.


Each log message is processed against the set of strings, matching its
text (or data) to see if it contains the string.  There are two simple
cases: only match strings, and only exclude strings.  In the case of
only match strings, any log message that matches any of the strings
will be printed.  In the case of only exclude strings, a log message
will be printed only if it matches none of the strings.


The more complicated case where match and exclude strings are mixed is
handled as follows: test the message against each string in turn.  If
the message matches, and the string is a "-match" string, the
"print-this-message" flag is set on.  If the message matches, and the
string is a "-exclude" string, the flag is set off.  Otherwise, the
flag is unaffected.  The flag's initial value is on if the first string
was a "-exclude" string, and off if the first string was a "-match"
string.


List of data classes:
A data class is a short string (1 to 16 characters) stored with any
message that contains binary data, and is used to identify the expander
procedure used to expand the data into its interpreted textual form.
The data class is specified when the message is placed into the log.


syserr
   identifies an old-style syserr log message.  The "syserr binary"
   code (see syserr_binary_defs.incl.pl1 for a list) is the first word
   of the data in the message; the remaining words of data are the real
   binary syserr data.
io_status
   identifies a message indicating the status of an I/O device or an
   error on that device.  Binary data of this class should be
   interpreted using the io_error_summary command.
hwfault
   identifies a message containing machine state information from a
   hardware failure.  Binary data of this class should be interpreted
   using the display_cpu_error command.


mos
   identifies a message containing information about a main memory
   auto-corrected error.  Binary data of this class should be
   interpreted using the mos_edac_summary command.
segdamage
   identifies a message containing information about damage to a
   particular storage system object.
voldamage
   identifies a message containing information about damage to a
   particular storage system volume.


mdc_del_uidpath
   identifies a message containing the UID pathname of a master
   directory which is missing but still registered.
mmdam
   identifies a message containing information about the location
   of main memory frames removed from service due to parity errors.
mpc_poll
   identifies a message which contains MPC data filed by poll_mpc.
   Binary data of this class should be interpreted using the
   mpc_data_summary command.


fnp_poll
   identifies a message which contains FNP data filed by poll_fnp.
   Binary data of this class should be interpreted using the
   fnp_data_summary command.
config
   identifies a message containing a copy of "cards" from the system
   config deck.
vtoce
   identifies a message containing a copy of a VTOCE which was found
   inconsistant by the system scavenger.


access_audit
   identifies a message containing information about access attempts
   to various system objects.
ibm3270_mde
   identifies a message containing data about an error encountered
   by the 3270 multiplexer.


Access required:
For all logs except inner-ring logs, read permission is required on the
log segments themselves, and status permission is required on their
containing directories.  If an access error is encountered searching
for older history logs, the search is stopped at that point, and no
further history will be available.  For the logs selected by control
arguments, the control argument descriptions list the standard history
directories for the logs.

For inner-ring logs (the Data Management system log is the only
standard inner-ring log), access to the logs is required, as is access
to the gate used by the log-reading procedure (see -procedure).


Notes on message selection:
Messages are selected for printing in a series of steps, each of which
filters out certain messages according to the control arguments
specified.  The set of messages at each step is any message that were
left after the previous step.  If a control argument was not specified,
then its corresponding step eliminates no messages.  Note that the
-expand control arguments do NOT select messages, but only affect how
their contents are displayed:


     1) -to            (stop looking after specified message)
     2) -from          (stop looking before specified number)
     3) -for TIME      (stop looking after specified time)
     4) -last TIME     (stop looking before specified time)
     5) -severity
     6) -exclude       (eliminate matching messages)
     7) -match         (eliminate non-matching messages)
     8) -exclude_data  (eliminate matching messages)
     9) -match_data    (eliminate non-matching messages)
    10) -for NUMBER    (stop after NUMBER are printed)
    11) -last NUMBER   (stop after NUMBER are printed)


Notes on severity values:
Severity values in log messages are used to indicate the importance of
the message being logged, in a general way.  Most logs use increasing
severity to indicate increasing importance, but the actual meaning
depends on the log.  For the Answering Service and Message Coordinator
logs, the severities have the following meanings:
   0 => Message just logged
   1 => Message logged and printed on a console
   2 => Message logged and printed on a console with bells
   3 => Message logged, printed, and the system crashed


For the syserr log, the severities have different meanings:
   0 => Message logged and printed on syserr console
   1 => Message logged, printed, and the system crashed
   2 => Message logged, printed, and the process writing the
        message is terminated.
   3 => Message logged and printed, and console alarm sounded
   4 => Message just logged, or printed if logging mechanism is
        inoperable
   5 => Message just logged, or discarded if it can't be logged

The severities 20 to 25, 30 to 35, and 40 to 45 are handled just like
0 to 5, but are different to indicate that the originating program was
writing an access audit message, rather than just an informative
message.


Notes on inner-ring logs:
Some applications create logs in an inner ring that must be read using
a special interface.  The only standard log to do this is the Data
Management system log, and it is read by specifying the -dm_system
control argument which supplies both the pathname and the procedure
name (dm_log_read_).  Other applications may provide their own special
procedures for log reading, in which case both the log pathname and the
procedure name must be supplied explicitly via the -pathname and
-procedure control arguments.  Note that a log read using a reader
procedure may enforce additional access requirements as well as
requiring access to the log itself.  In particular, the user must have
access to the reader procedure.


Compatibility features--
The following control arguments are accepted for compatibility with the
old print_syserr_log and print_log commands:
   -action => -severity
   -next => -for
   -debug, -db => -duplicates
The effect of print_syserr_log's -class argument can be achieved by
supplying a range to the -severity argument: "-class 2" is replaced by
"-severity 20:29".
