Museum

ERRLOG_$OPEN                      Domain/OS                       ERRLOG_$OPEN


NAME
     errlog_$open - open an error log file and log an error

SYNOPSIS (C)
     #include <apollo/base.h>
     #include <apollo/errlog.h>

     short errlog_$open(
          char *path_name,
          short &path_length,
          long &min_size,
          long &time_out,
          char *entry_comment,
          short &comment_length,
          long &fault_status,
          short &errlog_options,
          status_$t *status)

SYNOPSIS (Pascal)
     %include '/sys/ins/base.ins.pas';
     %include '/sys/ins/errlog.ins.pas';

     function errlog_$open(
          in path_name: univ name_$pname_t;
          in path_length: integer;
          in min_size: integer32;
          in time_out: integer32;
          in entry_comment: univ string;
          in comment_length: integer;
          in fault_status: univ status_$t;
          in errlog_options: errlog_$option_set_t;
          out status: status_$t): ios_$id_t;

SYNOPSIS (FORTRAN)
     %include '/sys/ins/base.ins.ftn'
     %include '/sys/ins/errlog.ins.ftn'

           integer*2 path_length, comment_length, errlog_options
           integer*4 min_size, time_out, status, stream_id
           character path_name(1023), entry_comment(80)

           stream_id = errlog_$open(path_name, path_length, min_size,
          &                         time_out, entry_comment, comment_length,
          &                         fault_status, errlog_options, status)

DESCRIPTION
     Errlog_$open opens an error log file at path_name, writes a standard
     entry header to it, optionally logs an error provided by the caller, and
     returns a stream ID for the file.  Although error log information may be
     written to any open stream, the standard directory for error log files is
     `node_data/system_logs.

     path_name
          The pathname of the log file.  A file is created at path_name if one
          does not exist already.

     path_length
          The number of bytes in path_name.

     min_size
          The minimum number of bytes to retain in the error log file.  If the
          file is larger than this it may be shortened by deleting the oldest
          entries, but the file's size is never reduced to less than min_size
          bytes.  If min_size is zero, all entries are retained.

     time_out
          The maximum number of seconds to wait for the file to become avail-
          able.  If it is not initially available, errlog_$open attempts to
          open the file at one second intervals for up to time_out seconds.
          (The log might, for example, be locked by another process executing
          the same program.)

     entry_comment
          A comment to write in the log entry header.  The contents of
          entry_comment are written to the file following a standard header
          line containing the date and time, user identification, and operat-
          ing system version.  It can be used to log product and version
          information.  The comment line is omitted if comment_length is 0.

     comment_length
          The number of bytes in entry_comment.

     fault_status
          If fault_status is not status_$ok, the standard error message per-
          taining to that status is written in the entry header.

     errlog_options
          A small set of options to modify error logging to the file.  Choose
          a combination of the following values:

          errlog_$silent
               Suppresses the default behavior of errlog_$open, which is to
               write a message on ios_$stderr alerting the user that a log
               entry is being written.

          errlog_$no_header
               Do not write a standard entry header.  Ignore entry_comment and
               fault_status.

          errlog_$no_divert
               Do not divert log entries to ios_$stderr if the log file cannot
               be opened.  Normally, if the error log cannot be opened,
               errlog_$open returns ios_$stderr after writing the standard
               header to it.  This option has no effect on the completion
               status supplied in status.

     status
          The completion status.