SOLAR 0.95.3 slrmail <> SLRMAIL.TXT

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

The Solar program slrmail.exe collects messages from a Waffle user's
electronic mailbox and writes SOUP 1.2 compliant AREAS and *.MSG files.
Under 'normal' operation, slrmail.exe is called when needed by the Solar
front-end program solar.exe. But, slrmail.exe may be used independently
or along with other software systems.

i. Command Line Syntax:

  slrmail -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 mail files 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
  slrmail.exe to locate the path to the user's mailbox and OPTIONS.SLR
  files.

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

  The '-n' switch can be used to cause slrmail.exe to update a user's
  mail files after batching. In normal operation, the mail files are
  updated by solar.exe, and the '-n' switch should not be used. When the
  '-n' switch is used, a user's mail files are only updated after
  successful batching, and if the 'delete-mail' parameter is set to YES.
  See the section on parameters below for more information.

  The '-f' switch will enable slrmail.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.

ii. Installation & Configuration:

  Location of slrmail.exe
  -----------------------

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

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

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

  Slrmail.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 - slrmail.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
                slrmail.exe will use FOSSIL routines for output IF the
                '-f' command line switch was provided to slrmail.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

    version   - The version of Waffle software being used on the host
                system. This is a non-standard Waffle static file
                parameter which is used by slrmail.exe to process the
                old Waffle 1.64 single mailbox format.

                    version : 1.64

                If a more recent version of Waffle is being used, this
                parameter is not needed.

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

                waffle : c:\waffle

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

    delete-mail - Perform update of user's mailbox after batching. The
                  internal default is NO. When set for YES, the '-n'
                  switch must be provided on the command line for
                  updates to be performed by slrmail.exe.

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

    mail-index  - Default SOUP 1.2 index file format for mail messages.
                  This parameter can only be set to "n" in this release
                  of Solar. Future releases may support other SOUP index
                  file formats. This parameter is not required, slrmail
                  will default mail-index to "n". See the SOUP 1.2
                  specification for details on index file formats.

    mail-type   - Default SOUP 1.2 mail message type. This parameter can
                  be set to "m", "M", or "b" in this release of Solar.
                  Future releases may support other SOUP mail message
                  formats. Without this parameter, slrmail.exe defaults
                  to SOUP mail message type "m". See the SOUP 1.2
                  specification for details on mail message formats.

    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.

  Slrmail.exe uses the following parameters from the user's OPTIONS.SLR
  file.

    delete-mail - Perform update of user's mailbox after batching. The
                  internal default is NO. When set for YES, the '-n'
                  switch must be provided on the command line for
                  updates to be performed by slrmail.exe.

    mail-index  - SOUP 1.2 index file format for mail messages. This
                  parameter can only be set to "n" in this release of
                  Solar. Future releases may support other SOUP index
                  file formats. Without this parameter, slrmail.exe will
                  default mail-index to "n". See the SOUP 1.2
                  specification for details on index file formats.

    mail-type   - SOUP 1.2 mail message type. This parameter can only be
                  set to "m", "M", or "b" in this release of Solar.
                  Future releases may support other SOUP mail message
                  formats. Without this parameter, slrmail.exe defaults
                  to SOUP mail message type "m". See the SOUP 1.2
                  specification for details on mail message formats.

iii. Technical Information

  Slrmail.exe is compliant with mailbox formats used by DOS Waffle
  versions 1.64 and 1.65. Slrmail.exe generates *.MSG files with support
  for the following SOUP 1.2 "AREAS" file specifications.

    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  'm'  (UNIX mailbox format)
          File format type  'M'  (MMDF mailbox format)
          File format type  'b'  (8-bit binary format)
       2) Index format type 'n'  (No index file)
       3) Kind of area      'm'  (Private e-mail)

  Slrmail.exe performs a conversion of a user's mailbox file(s) into a
  SOUP format file. One .MSG file is created containing all of the mail
  messages for the user regardless of the version of Waffle being used.
  The actual messages are untouched by slrmail. After processing the
  mailbox, slrmail.exe writes a record to the AREAS file for the MSG
  file. slrmail.exe creates an AREAS file if one does not already exist,
  otherwise it appends the mailbox record to the existing AREAS file.
  Both the .MSG file and the AREAS file are written in Solar's temporary
  directory.

  The .MSG file created by slrmail.exe is 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
  home directory. The number is reset to one (1) once it exceeds 32000.

  Normally, slrmail.exe does NOT update the user's mailbox. That task is
  left for solar.exe to perform after the SOUP packet has been
  successfully created and transfered to the user. If the '-n' switch is
  used when invoking slrmail.exe AND if the 'delete-mail' parameter is
  set in either Solar's configuration file or in the user's OPTIONS.SLR
  file, then slrmail.exe will update the user's mail files after
  creating the SOUP packets files. This is done by a brute force delete
  of the user's mail file(s). Under Waffle 1.65, using the single
  mailbox file schema, slrmail.exe operates only on the mailbox.* files.
  Using Waffle 1.64's multiple message file schema, slrmail.exe operates
  on all files in the user's directory named as "username.*".

  Slrmail.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 = successful completion
     1 = incorrect command line usage
     2 = fatal condition during execution

Notes:

  - Batching for 8-bit binary mail format is significantly slower than
    for MMDF or UNIX formats. This will be addressed in future releases.
