Modifying the Pegasus Mail SETUP.DAT setup program data file
Pegasus Mail System, Copyright (c) 1990-97, David Harris.
----------------------------------------------------------------------

The standard Pegasus Mail distribution archives contain a setup program
that installs the software onto the user's local system and performs some
of the basic configuration of the system. The setup program, SETUP.EXE (or
SETUP32.EXE for the Win32 version of Pegasus Mail) reads a script file
called SETUP.DAT (or SETUP32.DAT) that tells it how to install the
program. This file explains what modifications can be made to SETUP.DAT
by ISPs and Network Administrators who wish to supply altered distribution
archives, or customised setup routines.

Throughout this document, we will refer to SETUP.EXE and SETUP.DAT, on the
understanding that these references are interchangeable with their 32-bit
counterparts.


1: Operation

When SETUP.EXE starts, it performs the following steps in the order shown:

a: It looks for SETUP.DAT in the directory from which it was run. If it
   cannot find SETUP.DAT there, it issues an error and exits, otherwise
   it opens SETUP.DAT and begins reading it.

b: It looks for an optional [Setup] section containing specialised scripting
   commands. If it can find the section, it scans it and stores the results.

c: It looks for a mandatory section called [Manifest] that contains a list
   of all the files that should be present in the distribution archive. If
   any of the files in the [Manifest] section cannot be found in the
   directory from which SETUP.EXE was run, it issues an error then exits.

d: It issues a greeting to the user and waits for the user to click
   "Continue".

e: It asks the user whether or not NetWare support should be installed.
   If the user indicates that NetWare support should be installed, it
   displays an information dialog advising the user how to obtain the
   optional NDS mode support modules for Pegasus Mail.

f: It asks the user where the Pegasus Mail software should be installed:
   if the user has indicated no NetWare support, then the default
   location for this is "C:\PMAIL".

g: It asks the user to select which dictionary (US English or UK English)
   it should install as the default dictionary.

h: It displays a "ready to install" screen showing the user's selections
   and offering options to create a program manager group, to create
   registry entries to allow WinPMail to interoperate with Microsoft's
   Internet Explorer, and an option to suppress the copying of files.

If the user clicks "OK" at step (h) and the "Don't copy files" option is
unchecked (i.e, file copying should take place), then setup looks for the
proper installation section in SETUP.DAT and executes it.


2: Installation sections

SETUP.DAT can contain two installation sections - one called [Base
Standalone], which is the section used when no NetWare support is to be
installed, and another called [Base NetWare Bindery], which is used when
NetWare Support is to be installed. Installation sections simply contain
instructions telling SETUP how to create directories and copy files in
the destination. Within an installation section, lines that start hard
against the left margin are interpreted as directory names, while indented
filenames are assumed to be files that should be copied into that
directory. So, for example, the following fragment of SETUP.DAT -

RESOURCE 
   wpm-lmtt.r
   wpm-char.r
   rescom.exe
   rquotes.src

creates a directory called RESOURCE and copies the files "wpm-lmtt.r",
"wpm-char.r", "rescom.exe" and "rquotes.src" into that directory. The
directory RESOURCE is created under the directory the user gave in step 1f
above. A directory can have more than one level - so, an entry like
"FORMS\MULTIPOP" is permissible; SETUP.EXE will create both directories
correctly in one pass.

Renaming files during copying: files can be renamed as they are copied by
placing the name for the destination file after the name of the source
file, separated by a single space. So, the fragment:

.
   pmdict3.pmd pmdct3uk.pmd

Would copy PMDICT3.PMD from the distribution archive into the directory
where WINPMAIL.EXE is being installed (signified by the "." entry),
renaming it to PMDCT3UK.PMD in the process.

Version-sensitive files: SETUP.EXE can be used to update existing
installations of Pegasus Mail. In cases like this, some of the system
files may have been customised by the user for the previous version. The
most likely candidates for this kind of customization are *.FFF files (used
to inform WinPMail about available extensions) and *.R files (resource
files, used to alter character translation tables). In cases like this,
the customised version usually should not be overwritten by the new sample
version. To tell SETUP.EXE to check for an existing version of a file, use
a colon (:) character in front of the filename. If SETUP.EXE finds an
existing version of the file, it will copy the new version to a directory
called NEW.xxx, where xxx is the new WinPMail version. So, the fragment:

.
   tphone.dll
   :tphone.fff

tells SETUP.EXE that TPHONE.DLL can be overwritten, but that if there is an
existing TPHONE.FFF, then the existing file should not be touched and the
new version should be copied into NEW.XXX.


3: Other installation sections

As well as the base installation sections, SETUP.EXE also looks for the
following sections as it installs software:

[System standalone]
- specifies files that should be copied into the WINDOWS\SYSTEM directory
  when a non-NetWare installation is done.

[System NetWare Bindery]
- specifies files that should be copied into the WINDOWS\SYSTEM directory
  when an installation with NetWare support is done.

[US English]
- specifies files that should be copied if the user has chosen the US
  English dictionary as his or her default dictionary.

[UK English]
- specifies files that should be copied if the user has NOT chosen the US
  English dictionary as his or her default dictionary.


4: The [Setup] Section

The behaviour of SETUP.EXE, the prompts it offers and the assumptions it
makes, can be altered by adding a [Setup] section to SETUP.DAT. The
[Setup] section is examined before any other operation takes place, and
can contain the following commands:

[Setup]
Set winpmail directory = <path>
Set winpmail directory prompt = <Y|N>
Set NetWare = <Y|N>
Set US dictionary = <Y|N>
Set mailto handler = <Y|N>
Set copy files = <Y|N>
Set manifest check = <Y|N>
Set create group = <Y|N>

* Set winpmail directory = <path>

  Changes the default location SETUP.EXE will offer to the user for
  installing WinPMail. <Path> should be a fully-qualified path relative
  to the root of a disk drive.

  Example:  set winpmail directory = C:\NET\UTILS\WINPMAIL

  Notes: We strongly recommend that you do not alter the default value,
  C:\PMAIL. There are some third-party utilities available for Pegasus
  Mail that assume this directory.


* Set winpmail directory prompt = <Y|N>

  Controls whether or not SETUP.EXE will give the user the opportunity to
  alter the default installation location. If set to 'N', then the option
  will not be given and the installation can only be done to the default
  directory (or the directory set by the "set winpmail directory" option).

  Example:  set winpmail directory prompt = N


* Set NetWare = <Y|N>

  Controls whether or not the option of installing NetWare support will be
  offered to the user. If set to 'N', then the dialog will not be presented
  and only a standalone installation can be performed.

  Notes: If you create a distribution archive that does not contain the
  NetWare support files, then you must include this command set to 'N',
  since otherwise SETUP.EXE will fail if the user attempts to perform a
  NetWare installation.


* Set US Dictionary = <Y|N>

  Controls the dictionary installation section SETUP.EXE will use when
  installing the dictionary files. If set to 'N', SETUP.EXE will look for
  an installation section called [UK English] in the SETUP.DAT and will
  execute the commands it contains. If set to 'Y', SETUP.EXE will look for
  an installation section called [US English] and will execute the
  commands it contains. If this option is present, SETUP.EXE will not
  offer the user the option to select a default dictionary (i.e, that
  dialog will be suppressed).

  Notes: If you wish to create a distribution archive that only contains
  a single dictionary (perhaps to save space) then you will need to use
  this command to specify a section and then include that section with
  only the copy instructions for the single dictionary. So, if you are
  an ISP in the USA and wish to supply only the US English dictionary in
  your distribution archive, you would add "Set US Dictionary = Y" to your
  [Setup] section, then would make the following change to SETUP.DAT:

     [US English]
     pmdct3us.pmd pmdict3.pmd


* Set mailto handler = <Y|N>

  Sets the default value of the control in the final dialog that decides
  whether or not SETUP.EXE should add registry entries allowing Pegasus
  Mail to be used by Microsoft Internet Explorer. There is usually no
  reason to turn this option off, since other programs (including Forte
  Free Agent) will also use these settings, and they do not interfere with
  other browsers.


* Set copy files = <Y|N>

  Sets the default value of the control in the final setup dialog that
  determines whether or not SETUP should actually copy files to the
  installation directory. If set to 'N', the registry will be updated and
  the Pegasus Mail group created (if applicable) but not files will be
  copied.


* Set manifest check = <Y|N>

  Controls whether or not SETUP should attempt to determine that all the
  files in the [Manifest] section are present before installing. If set to
  'N', then no file copy will take place and the "Don't copy files" option
  in the final dialog will be disabled.

  Notes: This option is usually useful if you want to install or supply a
  preconfigured SETUP.EXE/SETUP.DAT combination that only updates settings
  for the user.


* Set create group = <Y|N>

  Sets the default value of the control in the final setup dialog that
  determines whether or not SETUP should create a Program Manager group
  containing icons for Pegasus Mail, its online help, and its guide.


5: Customising SETUP.DAT

ISPs and Network Administrators wishing to supply customised SETUP.DAT
files in their distribution archives will usually need to take the
following steps:

a: Modify the [Manifest] section to reflect the files that are actually
   supplied as part of the distribution archive.

b: Modify the [Base Standalone] and/or [Base NetWare Bindery] sections to
   install the proper subset of files for the selected operating mode.

c: [Optionally] Create a [Setup] section containing commands that default
   or suppress certain parts of the installation process


Example:

An ISP wishes to supply a version of Pegasus Mail that is automatically
installed in standalone mode to C:\PMAIL, and which does not contain the
NetWare support files or the UK English dictionary.

The ISP would follow these steps:

a: Remove WPNNW3.DLL, NWCALLS.DLL, PMGRANT.EXE, NEWMAIL.EXE and PMDICT3.PMD
   from the distribution archive, and delete the references to these files
   in the [Manifest] section of SETUP.DAT

b: No modifications need to be made to the [Base standalone] section

c: Create the following [Setup] section in SETUP.DAT:

   [Setup]
   Set NetWare = N
   Set winpmail directory prompt = N
   Set US Dictionary = Y

d: Modify the [US English] section of SETUP.DAT to look like this:

   [US English]
   pmdct3us.pmd pmdict3.pmd

