home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / d / dbassist2 / !SysLog / !Help < prev    next >
Text File  |  1997-04-23  |  23KB  |  575 lines
  1. ============================================================================
  2. SysLog Documentation
  3. ----------------------------------------------------------------------------
  4. Version: 0.17
  5. Author:  Jon Ribbens <jon@doggysoft.co.uk>
  6.  
  7. (c) DoggySoft Ltd., 1995, 1996, 1997
  8.  
  9. This program is Freeware and may be freely distributed so long as it is
  10. not charged for, and none of the files are changed or removed. It may be
  11. included with a commercial program which is charged for. There is no
  12. warranty, express or implied. DoggySoft Ltd. is not liable for any loss
  13. or damages caused by the use or misuse of this program.
  14.  
  15.  
  16. Things done:
  17.   * facility to insert arbitrary line
  18.   * considered format of datestamp
  19.   * implemented backoff system for errors writing to logs (partly a bugfix)
  20.   * fixed bug which left files open on errors (e.g. disk full)
  21.   * added Indent/UnIndent/NoIndent
  22.   * do 'temporary logs' thingy for Termite session logs
  23.   * implement log truncation at specified maximum size
  24.   * read <SysLog$Dir> once and once only at startup
  25.   * do automatic tidy-up of 'temporary logs'
  26.   * fixed bug which corrupted the very last line in the options file
  27.   * get allocation for SWI chunk and module name and OS commands
  28.   * user options to disable session logs
  29.   * added "*" line in options file to specify default values
  30.   * reserve disk space option
  31.   * make entry point use two-layer task, so RMEnsuring works
  32.   * add *SysLog ON|OFF and *SysLog <log> <new priority>
  33.   * LogData routine to log a block of hex data (e.g. IP packets)
  34.   * add debugf routine for assembler people
  35.   * add C front-end for C people
  36.   * added SysLog_ReadErrorMessage
  37.   * added %<reg>p and %<reg>a to LogFormatted
  38.   * fixed order of %<reg>a (it was backwards)
  39.   * made log buffer size dependent on logging level
  40.   * made log buffer get de-allocated after ten minutes
  41.   * added SysLog_LogComplete
  42.   * made buffer size be recalculated when log level is changed
  43.   * made setting log level also apply to session logs of that log
  44.   * fixed tidying up of stray session logs (sometimes missed some)
  45.   * fixed a few problems with sessions
  46. 0.15
  47.   * termination of strings is now by zero-byte or line-feed
  48. 0.16
  49.   * add log_forget and call it in CloseSessionLog
  50. 0.17
  51.   * allow CR as a string terminator
  52.   * automatically create 'Old' directory on startup
  53.   * added 'IRQ mode'
  54.  
  55. To do:
  56.   * add expression evaluation to LogFormatted
  57.   * add optional checking of pointer validity
  58.   * add 'features flags'
  59.  
  60. ============================================================================
  61. Rationale
  62. ----------------------------------------------------------------------------
  63.  
  64. Termite is currently lacking in logging facilities. In fact, most
  65. communications software for the Arc is rather poor at logging. This module
  66. is designed to make it easy for comprehensive logging to be added to any
  67. RISC OS program.
  68.  
  69. The logging level can be altered by the user for individual log files, and
  70. buffering is used to speed logging, so it is safe for programs to log large
  71. quantities of data, provided that they use sensible priorities for each type
  72. of message. The logs are also automatically kept to user-specified maximum
  73. lengths, so there is no need to worry about filling up the user's hard disk.
  74.  
  75. Separate log files are used for each application, on the basis that such
  76. segregation of information makes it much easier for the user to find what
  77. they're looking for.
  78.  
  79. A back-off system is used for dealing with errors when writing to logs. Each
  80. error is logged in the "SysLog" log, and the offending log is marked as
  81. "dead". SysLog will then not attempt to write to that log again for one
  82. second. If we again get an error writing to the log, we multiply the
  83. "back-off" time by 1.5, and again mark the log as dead. The back-off time is
  84. not allowed to grow longer than ten minutes.
  85.  
  86.  
  87. ============================================================================
  88. Session logs
  89. ----------------------------------------------------------------------------
  90.  
  91. Usually, log entries are stored strictly chronologically. Sometimes, though,
  92. it may be more useful to store them grouped by 'session'. For example,
  93. NewsBite can have several incoming NNTP connections at once. It is nice to
  94. group the log messages that are coming from each separate connection
  95. together. This can be done using SysLog_OpenSessionLog.
  96.  
  97. SysLog_OpenSessionLog creates a specially-named temporary log file. The log
  98. entries for the session are stored in this log file. When the temporary log
  99. file is closed using SysLog_CloseSessionLog, this data is appended in one
  100. chunk to the end of the main log.
  101.  
  102. SysLog checks for stray temporary log files when it initialises and
  103. finalises, and appends them to the relevant logs. This copes with the
  104. situation where an application crashes or otherwise exits without calling
  105. SysLog_CloseSessionLog.
  106.  
  107.  
  108. ============================================================================
  109. Priorities
  110. ----------------------------------------------------------------------------
  111.  
  112. Message priorities can be in the range 0 to 255, with 0 being the highest
  113. priority and 255 being the lowest. Unless otherwise specified by the user,
  114. only messages with priorities of less than 125 are stored in the log files.
  115. You should therefore think about what things the user is likely to want to
  116. have logged by default, and ensure that these things are logged at
  117. a priority of 124 or less.
  118.  
  119. The priority of errors often depends on how significant the consequences of
  120. the error are, not what the cause of it is. e.g. sometimes "out of memory"
  121. will be an extremely important unrecoverable error (because the program
  122. can't start up), and sometimes it will be unimportant (because the program
  123. can use disk instead, or maybe try again later).
  124.  
  125.  
  126. ============================================================================
  127. Log names
  128. ----------------------------------------------------------------------------
  129.  
  130. Log names are used as the leafnames to store the logs as, so they must
  131. comply with the rules for RISC OS leafnames. They must also not be longer
  132. than ten characters.
  133.  
  134. It is intended that each application have its own log, so an obvious choice
  135. for the log name is the application name (without the '!'). Very large
  136. applications could have more than one log file - in which case the naming
  137. scheme is unspecified. Try and choose sensible log names.
  138.  
  139. If your application is going to be distributed, you should write to
  140. support@doggysoft.co.uk, to request that your log name be formally
  141. allocated. This will hopefully avoid having more than one program using the
  142. same log file.
  143.  
  144. The following log names are reserved for internal use:
  145.  
  146.   any name beginning with a '-' character
  147.   any name beginning with "SysLog"
  148.   "Old"
  149.  
  150.  
  151. ============================================================================
  152. OS commands
  153. ----------------------------------------------------------------------------
  154.  
  155. *SysLog <log name> <priority> <message>
  156.  ------
  157.  
  158. Adds a time-stamped message to the log file, if and only if the specified
  159. log file is set up to log messages of this priority. The priority must be in
  160. the range 0-255.
  161.  
  162.  
  163. *SysLog <log name> <new priority>
  164.  ------
  165.  
  166. Temporarily (but with immediate effect) changes the logging priority of the
  167. specified log. The priority must be in the range 0-256.
  168.  
  169.  
  170. *SysLog ON|OFF
  171.  ------
  172.  
  173. *SysLog OFF will temporary disable SysLog - all log messages received after
  174. this command is issued will be ignored. *SysLog ON resumes normal operation.
  175.  
  176.  
  177. *SysLog_Flush ON|OFF
  178.  ------------
  179.  
  180. *SysLog_Flush with no paramaters flushes all currently open log files to
  181. disk. If it used with the parameter 'ON' then it causes all log files to be
  182. flushed immediately after each message is written to them. *SysLog_Flush OFF
  183. disables this behaviour. (This is intended for use when the a program is
  184. being debugged, and keeps crashing the computer. With SysLog_Flush ON,
  185. you're guaranteed that all the log information your program produces before
  186. it crashes will actually be available after a re-boot. It also makes logging
  187. *very slow*.)
  188.  
  189.  
  190. ============================================================================
  191. SWIs
  192. -----------------------------------------------------------