SOLAR v0.95.3 slrnews <> SLRNEWS.TXT

i.   Command Line Syntax
ii.  Installation & Configuration
iii. Technical Information

The Solar program slrnews.exe is called by the Solar System to batch
news articles into SOUP 1.2 compliant AREAS, *.MSG, and *.IDX files.
Under 'normal' operation, slrnews.exe is called when needed by the Solar
front-end program solar.exe. But, slrnews.exe may be used independently
or along with other software systems.

i. Command Line Syntax:

  slrnews -u username [-v] [-n] [-f]

    -u username      : The user's login name. This is required.
    -v               : Turn verbose mode on (for debugging).
    -n               : Update user's newsrc file when done.
    -f               : Enable FOSSIL driver support.

  Command line switches may be upper case or lower case. Whitespace need
  not be used for the username (i.e. -uusername also works).

  The '-u username' switch is required. The username will be used by
  slrnews.exe to locate the path to the user's newsrc and OPTIONS.SLR
  files.

  The '-v' switch will cause slrnews.exe to display debugging
  information. It should not be used during normal operation.

  The '-n' switch can be used to cause slrnews.exe to update a user's
  newsrc file after batching. In normal operation, the newsrc file is
  updated by solar.exe, and the '-n' switch should not be used. When the
  '-n' switch is used, a user's newsrc file is only updated after
  successful batching.

  The '-f' switch will enable slrnews.exe's internal FOSSIL code,
  causing output to be sent to stdout and to the serial port via a
  FOSSIL driver. The 'driver' parameter is Waffle's static file must
  also be set for 'fossil' in order for FOSSIL support to be activated.

  Command line switches may be upper case or lower case. Whitespace need
  not be used for the username (i.e. -uusername also works).

ii. Installation & Configuration:

  Location of slrnews.exe
  -----------------------

  Under normal operation, when using Solar as a complete system
  underneath Waffle, slrnews.exe will be called as needed by the other
  Solar programs. Solar expects to find slrnews.exe in Solar's home
  directory.

  In Solar's configuration file, the 'solarpath' parameter points to
  Solar's home directory. Slrnews.exe must reside in that directory for
  the remainder of the Solar System to find it.

  Configuration Parameters
  ------------------------

  Slrnews.exe loads configuration parameters from Waffle's static file,
  the Solar configuration file, and from the user's configuration file,
  if one exists, in that order.

  The location of Waffle's static file comes from the WAFFLE environment
  variable. The location of Solar's configuration file comes from either
  a SOLAR environment variable, or from a 'solar:' parameter in Waffle's
  static file, in that order. The user's configuration file is found
  through the 'user:' parameter in Waffle's static file, the username
  from the command line, and the filename OPTIONS.SLR.

        File loaded              File location specifier
     ----------------------------------------------------------------------
     1) Waffle's static file     WAFFLE environment variable
     2) Solar's config file      SOLAR environment varaible -or-
                                 'solar:' parameter in Waffle's static file
     3) User's OPTIONS.SLR file  'user:' parameter in Waffle's static file,
                                 and '-u' switch on command line.

  Similar parameters in Solar's configuration file over-ride those in
  Waffle's static file. Likewise, parameters in the user's OPTIONS.SLR
  file over-ride similar parameters in Solar's configuration file.

  Environment variables:

    WAFFLE=c:\waffle\system\static
      - an entry in this file may point to Solar's configuration
        file (i.e. solar : c:\waffle\solar\solar.cfg)

    SOLAR=c:\waffle\solar\solar.cfg
      - This is another way to provide the location of Solar's
        configuration file. Only one method is required.

  STATIC - slrnews.exe uses the following parameters from Waffle's
           static file. Parameters which are preceeded with a '*' are
           required.

    device    - The COMM port to use for FOSSIL output, if FOSSIL
                support is enabled. This is required if FOSSIL support
                is enabled.

    driver    - If the value of 'driver' is set to 'fossil', then
                slrnews.exe will use FOSSIL routines for output IF the
                '-f' command line switch was provided to slrnews.exe.

                driver : fossil

    solar     - Path to Solar's configuration file. This can be used
                instead of the SOLAR environment variable to point to
                Solar's home directory.

                    solar : c:\waffle\solar

  * temporary - Path to temporary directory. Since Solar expects to have
                exclusive use of it's own temporary directory, relying
                on this parameter is a bad idea. The 'solarwork'
                parameter in Solar's configuration file overrides the
                value of 'temporary' and is preferred.

                temporary : c:\tmp

  * user      - Path to root of user directories. This is combined with
                the username from the command line to find the user's
                directory.

                user : c:\waffle\user

  * waffle    - Path to the root of your Waffle software directory tree.
                This parameter is used to determine the default logfile
                path for slrnews.exe, and your Waffle's ~\system
                directory. By default, the logfile will be written as
                ~\admin\solar, relative to the value of this parameter.

                waffle : c:\waffle

  SOLAR.CFG - slrnews.exe uses the following parameters from Solar's
              configuration file. All parameters are optional, they
              should be used to over-ride slrnews.exe's internal default
              values when customizing a setup.

    logfile         - Path to the log file slrnews.exe will use to
                      record activity. This is an optional parameter. If
                      not specified, slrnews.exe will default to
                      ~\admin\solar under the Waffle directory tree.

    kill-summary    - Enables or disables user kill files for areas
                      which are summarized. The internal default for
                      slrnews.exe is YES. If you are using a slow
                      machine, slrnews.exe will run faster if you set
                      this to NO, at the expense of functionality.

    news-area-bytes - The maximum number of bytes, before compression,
                      slrnews.exe will batch from any single news
                      message area. This value is checked after batching
                      each message, and only areas batched with SOUP 1.2
                      message type 'u' are counted. Thus, areas which
                      are summaried (SOUP 1.2 message type 'i') are not
                      counted against this maximum value. Slrnews.exe's
                      internal default is the maximum value for a long
                      integer.

    news-area-messages - The maximum number of messages slrnews.exe will
                      batch from any single news message area. Only
                      areas batched with SOUP 1.2 message type 'u' are
                      counted. Thus, areas which are summarized (SOUP
                      1.2 message type 'i') are not counted against this
                      maximum value. Slrnews.exe's internal default is
                      the maximum value for a long integer.

    news-index      - Sets the default SOUP 1.2 index type to use for
                      news messages. Valid settings are:

                             n = No indexes
                             C = Partial C-News overview format
                             c = Full C-News overview format

                      If set to 'n', slrnews.exe will produce type 'C'
                      indexes for all news messages areas which are
                      summarized. The internal default for slrnews.exe
                      is 'c' for full C-News overview format indexes.
                      See the specs for SOUP 1.2 for details.

    news-total-bytes - The maximum number of bytes, before compression,
                      slrnews.exe will batch per execution. This value
                      is checked after each message area is processed,
                      and only areas batched with SOUP 1.2 message type
                      'u' are counted. Thus, areas which are summarized
                      (SOUP 1.2 message type 'i') are not counted
                      against this maximum value. Slrnews.exe's internal
                      default is the maximum value for a long integer.

    news-total-messages - The maximum number of messages slrnews.exe
                      will batch per execution. This value is checked
                      after each message area is processed, and only
                      areas batched with SOUP 1.2 message type 'u' are
                      counted. Thus, areas which are summarized (SOUP
                      1.2 message type 'i') are not counted against this
                      maximum value. Slrnews.exe's internal default is
                      the maximum value for a long integer.

    news-type       - Sets the default SOUP 1.2 message type to use for
                      news messages. Valid settings are:

                             u = Usenet format
                             B = 8-bit binary format
                             i = Index only format

                      If set to 'i', slrnews.exe will only summarize
                      message areas. The internal default for
                      slrnews.exe is 'u' for Usenet format messages. See
                      the specs for SOUP 1.2 for details.

    newsgroups      - Full path to a file containing newsgroup names and
                      descriptions. The file should be in the format:

                             usenet.group.name Group description

                      This is optional. If not used, slrnews.exe will
                      not write descriptions into the SOUP 1.2 AREAS
                      file for news message areas.

    solarwork       - Path to Solar's temporary directory. This value
                      overrides the 'temporary' parameter from Waffle's
                      static file. The use of 'solarwork' is recommended
                      since Solar expects to have exclusive use of it's
                      own temporary directory. However, this parameter
                      is optional.

  OPTIONS.SLR - slrnews.exe uses the following parameters from a user's
                OPTIONS.SLR file:

    news-index      - Sets the default SOUP 1.2 index type to use for
                      news messages. Valid settings are:

                             n = No indexes
                             C = Partial C-News overview format
                             c = Full C-News overview format

                      If set to 'n', slrnews.exe will produce type 'C'
                      indexes for all news messages areas which are
                      summarized. This overrides the setting in the
                      global Solar configuration file.

    news-type       - Sets the default SOUP 1.2 message type to use for
                      news messages. Valid settings are:

                             u = Usenet format
                             B = 8-bit binary format
                             i = Index only format

                      If set to 'i', slrnews.exe will only summarize
                      news message areas. This overrides the setting in
                      the global Solar configuration file.

iii. Operational Notes

  Slrnews.exe reads a user's NEWSRC.SLR file, which contains newsgroup
  subscription information, and produces SOUP 1.2 format files. The
  administrator and ultimately the user have control over the type of
  files created. The following SOUP 1.2 AREAS file specifications are
  suported.

    o Full support of all fields in AREAS file :
          prefix<TAB>area name<TAB>encoding[<TAB>description[<TAB>number]]

    o The following 'encoding' values:
       1) File format type  'u'  (USENET format)
          File format type  'B'  (8-bit binary format)
          File format type  'i'  (Index file only, i.e. summarize)
       2) Index format type 'n'  (No index file)
          Index format type 'C'  (Partial Cnews Overview Format)
          Index format type 'c'  (Full Cnews Overview Format)
       3) Kind of area      'n'  (Public messages, or news)

  Slrnews.exe can either summarize or batch a particular news message
  area. For areas which are summarized, slrnews.exe will produce a
  single .IDX file for each message area. For areas which are batched,
  slrnews.exe will produce at one .MSG file for each message area, and
  if an index format is specified, it will also create a single .IDX
  file for each message area.

  For each message area processed, slrnews.exe writes a record to the
  AREAS file. Slrnews.exe creates an AREAS file if one does not already
  exist, otherwise it appends the record to the existing AREAS file. The
  .IDX, .MSG, and AREAS files are written in Solar's temporary
  directory.

  The .MSG files created by slrnews.exe are named using a sequential
  numerical filename (i.e. 1.MSG, 2.MSG, etc). The sequential number is
  tracked for each user individually in the file SEQNO.SLR in the user's
  directory. The number is reset to one (1) if it exceeds 32000.

  By default, slrnews.exe will not update the user's NEWSRC.SLR file,
  unless the command line switch -n is specified. The updates are
  written to NEWSRC.TMP while slrnews.exe processes each area. If '-n'
  is used, when slrnews.exe has successfully completed batching, the
  NEWSRC.TMP file is renamed to NEWSRC.SLR to affect the update.

  Slrnews.exe is implimented as an int function, enabling it to pass a
  value back to a DOS ERRORLEVEL statement or another program's
  detection method if needed. The following lists the exit codes :

       0 = success
       1 = incorrect command line usage
       2 = fatal error during execution

