PMMail Archiver, Copyright (c) 1998, Jonathan B. Bayer


Table of Contents
-----------------

Overview
Installation
Performance
Usage
Calling as an external Hook from within PMMail
Command Line Syntax
Configuration File Options and Syntax
Creating a test directory
So You Need To Restore A File
Command Line Examples
Configuration File Examples
Multiple folder filters
External Exit/Hook Examples
InfoZip and InfoUnzip
Program overview
Registration Information
Support
__________________________________________________________________________

Overview
--------

PMMail is a great e-mail program.  One of the shortcomings it has
(along with most other e-mail programs) is the inability to archive
messages.

PMMail Archiver is designed to fill this void.  It can archive messages,
reindex the message folders, and sort the address book.  As a bonus an
additional program has been included called Attach.  This program is
designed to remove the complete path from e-mail attachments, leaving
just the file name.  See the file ATTACH.TXT for instructions on using
the Attach program.

Upon registration you will receive the latest copy of PMMail Archiver,
along with an additional program called Detach, which can automatically
detach attached files from e-mail messages and place them in specified
directories.

This program was written as a command-line driven program so that
it could be called from within PMMail as an external hook, usually upon
exiting the program.

PMMail Archiver can be driven entirely from the command line, or a
configuration file may be set up for most common parameters.

The program is available in Windows and OS/2 versions.  The Windows
version of the program is called "warchive.exe", and the OS/2 version
is called "oarchive.exe".  Throughout this manual the program is
referred to as "archiver" or "archiver.exe".  Simply replace the
"archiver" with the appropriate name for the operating system you are
using.

Folders are "filtered" according to the criteria specified on the
command line and in the (optional) configuration file.  Nested folders
will be of a folder that does not match the criteria will still have
the filters applied to them.  Also, you can specify a path of folder
directory names to archive a specific folder.  See the examples for
more specific information on this feature.

Files are "filtered" according to the criteria specified on the
command line and in the (optional) configuration file.  Filter options
can be either all required, or any required.  If all required is
specified then a message will need to match all filter options before
it is archived/restored.  If any required is specified then a message
will need to match only one filter option for it to be archived/restored.

Files are archived into a standard zip file.  There is an additional
file created called "backup.bag" which contains the PMMail information for
each file archived.

Restored files are put into a special folder created by the program,
called "Restored Files".  This folder is created in each account that
has files restored.  Inside this folder the program will recreate the
same folder hierarchy as existed when the file(s) were archived.  It will
not create empty folders.
__________________________________________________________________________

Installation
------------

There is no installation script.  Copy the executable to either the
PMMail Tools directory, or the PMMail executable directory.  Either
make sure that it is in your path, or call it directly.

__________________________________________________________________________

Performance
-----------

The performance of PMMail Archiver will depend upon several factors.  Some
of them are:  Speed of your computer, memory available, number of files
to archive.

An exact number cannot be specified, however I am listing some performance
statistics below which will give you an idea of the time it will take to
archive your files:

==========================================================================
Computer:   P-133, 80 meg. memory
OS:         OS/2 Warp 3

Files to be archived:  Multiple accounts, total of 5114 messages.

Action                                                      Time used
--------------------------------------------------          ---------
Reading the directories.  Lots of disk activity.              1:40
Zip processing file list,  Very little disk activity         13:00
Zip creating zip file, high disk activity                     4:30
Rewriting bag files                                           0:25
Deleting archived files                                       4:00


==========================================================================
Computer    P-200 MMX, 32 meg. memory.
OS:         OS/2 Warp 4 with FixPak 5 applied.

Files to be archived:  One account, total of 7946 files..
Action                                                      Time used
--------------------------------------------------          ---------
Reading the directories.  Lots of disk activity.              2:58
Zip processing file list,  Very little disk activity         36:12
Zip creating zip file, high disk activity                     2:28

__________________________________________________________________________

Usage
-----

The program has the following functions:

Archiving of message files
Restoration of message files
Reindexing of message folders
Sorting address book


        Archiving
        ---------
        The program takes the filter parameters the user specifies on
        either the command line or in the configuration file (or both).
        It creates a file called "backup.bag" which contains all the
        "folder.bag" entries for the files which are being archived.  The
        archive process will archive this file along with all the message
        files (and INI files for the folders).  If requested the program
        will delete the archived files and update the "folder.bag" files
        for each folder.

        Restoration
        -----------
        The program takes the filter parameters specified and the archive
        file specified on the command line.  It unzips the "backup.bag"
        file and examines it applying the filters to each entry.  After
        this it will, if necessary, create a folder in each account called
        "Restored Files" which will contain all files restored for that
        account.  Inside this folder it will recreate the folder structure
        which existed at the time the archive was created and restore the
        files to the same folder (inside the "Restored Files") where they
        were before.
        If query mode is on the user will be asked about each file before
        it is restored.

        If the account being restored does not exist then the account
        directory and the "acct.ini" file will be restored.

        If you perform an archive after restoring files, all the files in
        "Restored Files" folder will be eligible for archiving again.

        Reindexing
        ----------
        The program takes the specified accounts and ignores all other
        parameters.  It will then re-index all folders in the specified
        accounts.  It reads each file, and if a "folder.bag" entry exists
        for that file it will preserve the file priority and status.  It
        will rewrite each "folder.bag" file in each directory with updated
        information.


        Sorting
        -------
        The program will sort the address book using the specified field.
        It currently does an ascending sort only.

__________________________________________________________________________

Calling as an external Hook from within PMMail
----------------------------------------------

PMMail can call an external program at several points.  If you wish
to call this from within PMMail it is safest to call it when exiting the
program.  If you have one set of parameters then you can call the program
directly from within PMMail, otherwise you will need to create a batch/
command file and call the archiver several times with the different
parameters.

OS/2
----
At the main screen select the PMMail menu, go into Settings, and go to the
Rexx page.

Enable the Program Close Exit, and put either the program name & options
or the Rexx command file in the entry field.

Windows
-------
At the main screen select the PMMail menu, go into Properties, and go to
the User Hooks page.

Enable the Program close hook, and put either the program name & options
or the batch file in the entry field.

__________________________________________________________________________

Command Line Syntax
-------------------

Usage:   archiver  [parameters] [archive file name]

The program must either be run from the main PMMail directory, or
the main directory must be specified using the /p parameter.

***** IMPORTANT *****

This program REQUIRES the latest versions of InfoZip and InfoUnzip.
Currently the latest version of InfoZip is 2.2, and the latest version
of InfoUnzip is 5.32.

If no archive file is specified then the program will create a file in
the current directory called ARCHIV??.ZIP, where the question marks will
be replaced by a sequential series of numbers.
A specified archive file name can have question marks embedded, and the
question marks will be replaced as above.

The archive file is NOT optional when doing a restore.

ANY parameter on the command line will totally override the corresponding
parameter in the configuration file.  You can have multiple entries for
some of the command line parameters, but if you even specify one of them
on the command line the program will totally ignore any of the same
parameters in the configuration file.

Command Line Parameters -  either a dash, plus, or forward slash are
                           acceptable.  The parameters ARE case sensitive.

Location parameters     Multiple Description
                        Allowed
-------------------     -------- -----------
/c configFileDirectory           Specify the location of the
                                 configuration file (archive.cfg).
/c configFile                    Specify the complete path of
                                 the configuration file.
/c NONE                          Do not use a configuration file.
/p pmmaildirname                 If no accounts specified then will
                                 perform work on all accounts.
/a accountdirname        Yes     If /p not specified then either the
                                 complete path is required, or the program
                                 must be run from the PMMail directory
                                 (where the accounts are).
/b accountName           Yes     Full or partial name of account.

These parameters are currently inclusive or'd together.  In other words,
if ANY parameter is met then the file will be archived/unarchived.  This
can be changed by specifying the /R option on the command line, or the
AllRequired parameter in the configuration file.


Archive parameters      Multiple Description
Unarchiving parameters  Allowed
----------------------  -------- -----------

Filter Options
--------------

/f folderdirname         Yes     Directory name of the folder directory
                                 containing messages to be archived or
                                 restored.
/G foldername            Yes     PMMail text name of folder containing
                                 messages to be archived or restored.
/A age in days                   Anything older than this gets archived.
/d datecutoff                    Specifies the message date at which to
                                 start archiving message.  Format must be
                                 [yy]yy/mm/dd.  This uses the date the
                                 message was saved on the system.
/D messageDateCutoff             Same as /d except uses the date in the
                                 message instead of the date the message
                                 was saved.
/t timecutoff                    Specifies the message at which to start
                                 archiving.  This must be used with
                                 either the /d (dateCutOff) or /D
                                 (messageDateCutoff) options.
                                 The format must be hh:mm, although the
                                 colon is optional.
/s subject               Yes     Subject match.  This will match the
                                 beginning of the subject.  The match
                                 will not be case sensitive.
/S subject               Yes     Partial subject match.  This will match
                                 anywhere in the subject. The match will
                                 not be case sensitive.
/F address               Yes     From address.
/T address               Yes     To address.


Other options
-------------
/N                               Delete files after archive process is
                                 complete.
/V 1                             Verbose mode.  Tell me what you are doing
/V 2                             Verbose mode, but do not delete.  This
                                 overrides the /N option.
/V 3                             Verbose mode, but do not archive or
                                 delete.
/V 4                             Show all specified options and exit
/O [filename]                    Send a copy of all output to the
                                 specified file.  If no file specified
                                 then send output to file "archiv??.rpt".
/q                               If verbose mode is specified then make
                                 the zip/unzip operations quiet.  If no
                                 verbose mode is specified then make the
                                 zip/unzip operations noisy.
/Q                               Query mode for restore only.
/n                               Toggle the nestedFolder option.  NestedFolders
                                 are initially off.  This is a position dependent
                                 option.  It only affects folders specified AFTER
                                 it occurs.  It can occur multiple times on the
                                 command line.

/r                               Restore files.
/R                               Required.  Make all filters required.
/o                               Restore files to original location.


Folder and Sort Parameters
--------------------------

/i  [option]                     Option to specify sorting of address book.
                                 Option can be one of:
                                             name
                                             alias
                                             email
                                             company
                                 If no option is specified then
                                 the default sort is by alias.
/I                               Option to specify reindexing.

__________________________________________________________________________

Configuration File Options and Syntax
-------------------------------------

The configuration file is a text file, with one statement per line.  The
following rules apply to the file:

   a. Comments begin with a pound sign or number sign.
   b. Statements are not case sensitive.
   c. Spaces at the beginning and end of the line are ignored.
   d. Line beginning with a slash is interpreted just like a command line.
   e. Statement begins line, followed by white space (either tabs or
      spaces), followed by data.  If data has spaces then it needs to begin
      with a single or double quote.  Quotes can be embedded by escaping
      them with a backslash.  Data ends at either the end of the line or a
      closing quote.
   f. Only one of each statement is allowed in the configuration file,
      unless specifically noted as allowing multiple entries.
   g. All configuration options will be overridden by options specified
      on the command line.


The default name of the file is "archive.cfg".  The location of the
configuration file can be specified on the command line using the /c
option (see above).  Also, the /c option can specify the full path name
of a configuration file.  This gives you the ability to have multiple
configurations.

The statements are not case sensitive.

Allowable statements for the configuration file are:

   Statement        Multiple  Description
                    Allowed
   ---------        --------  -----------
   pmmailDirName              Specify the location of the PMMail
                              directory.
   accountDir         Yes     Specify the account directory(ies) to
                              archive.
   accountName        Yes     Specify the full or partial account name(s).


   Filter Statements
   -----------------
   folderDir          Yes     Specify the folder directory(ies).
   folderName         Yes     Specify the full or partial folder name(s).
   NestedFolders [yes|no]     A position dependent option.  If "yes" then
                              all folder filters following this will
                              match both the folder and all folders
                              nested within it.  If "no" then the folder
                              filters will have to match exactly.  This
                              statement can appear multiple times in the
                              configuration file.
   fileAge                    Specify the minimum age before a file will
                              be archived.
   dateCutOff                 Specify the latest date (in YYYY/MM/DD) for
                              a file to be archived.
   messageDateCutoff          Specify the latest date (in YYYY/MM/DD) for
                              a file to be archived.  Use the message date
                              instead of the saved date.
   TimeCutOff                 Specify the time together with the either the
                              dateCutOff or messageDateCutoff for a file to
                              be archived.  This option cannot be used by
                              itself.  The time format must be hh:mm,
                              although the colon is optional.
   beginSubject       Yes     Specify the full or partial subject.  If
                              the subject has spaces then surround it with
                              quotes.  The subject must begin with this
                              text.
   PartialSubject     Yes     Specify a partial subject.  This text can
                              appear anywhere within the subject.  Again,
                              if spaces are included surround the text
                              with quotes.
   fromAddress        Yes     Specify the address from which the mail came.
   toAddress          Yes     Specify the address to which the mail was
                              sent.
   fileSize                   In K, any file as big or bigger than the
                              specified size will be archived.


   Miscellaneous Statements
   ------------------------
   archiveFile                Specify the name of the archive file.
                              Putting question marks in will let the
                              program create a sequential series of
                              archives.  See the description of the
                              archive file name earlier.
   Delete                     Flag to indicate that the files are to be
                              removed after the archiving is completed.
   verbose                    Be noisy.  See the options earlier.
   OuputFileName [filename]   Send a copy of all output to the
                              specified file.  If no file specified
                              then send output to file "archiv??.rpt".
   Sort [option]              Specify Address book sort option.  If this
                              option is specified then the address book
                              will be sorted after all other operations
                              (if any) are completed.
                              The option can be one of:
                                             name
                                             alias
                                             email
                                             company
                              If no option is specified then the default
                              sort is by alias.

   archiveDay                 Day of week to archive the files.  The day
                              must be at least two (2) characters long for
                              uniqueness.
   allRequired                If present then all options need to be met
                              before a file will be archived.  If not
                              present then any matching option will cause
                              a file to be archived.
   OriginalLocation           For restore operation only, restore files
                              to their original locations instead of
                              into the restore folder.
__________________________________________________________________________

Creating a test directory
-------------------------

It is recommended that you create a test directory where you can try out
this program without any chance of deleting messages from PMMail.  The
easiest way would be to simply copy the entire directory structure to
another area on your disk:

---------------------------------------------------------------------

For example, assume that PMMail is located in c:\southsde\PMMail, and you
want to copy it on the same disk.

Create a subdirectory called Test (or anything else you want to), and
simply xcopy PMMail into it:

   xcopy c:\southsde  test\southsde /s

or, you could copy it to a different disk:

   xcopy c:\southsde d:\southsde /s

---------------------------------------------------------------------

If you are short of disk space then you can setup a copy of your PMMail
directories with only some of the data.

For example, assume you have 4 e-mail accounts.  Again, assuming a
subdirectory called Test, first copy the Tools directory:

   mkdir c:\test
   mkdir c:\test\southsde
   xcopy c:\southsde\tools c:\test\southsde\tools /s

Then copy the files in the PMMail directory:

   mkdir c:\test\southsde\pmmail
   copy c:\southsde\pmmail\*.* c:\test\southsde\pmmail

Finally copy one of your accounts:
    (the two lines below should be on one line)

   xcopy c:\southsde\pmmail\accnt_0.act
              c:\test\southsde\pmmail\accnt_0.act /s

---------------------------------------------------------------------

When you are done creating a test directory you can then run the archiver
from the test directory without any fear of damaging your live files.

__________________________________________________________________________

So You Need To Restore A File
-----------------------------

Restoring a file consists of several steps.  The only requirement is that
the account directory already be created (this limitation will be removed
in a later release).

It is strongly recommended that if you are restoring a limited number of
files that you use the /R (allRequired) mode.

Files are normally restored to a new folder called "Restored Files" (which
will be created if it doesn't exist) in each directory.  If you wish, you
can specify the /o (originalLocation) option to put the files back into
their original locations in the account directories.

You have several options depending upon how much you know about the file
you are looking for.

What you know
-------------
If you know the account directory and the folder the file was in,
and who the file was from:

Command you can use
-------------------
archiver /r /R /a acct_0.act /f folder.dir /F name@addr.com archive.zip

What it does
------------
/r     Specify restore mode.
/R     Specify the allRequired mode.
/a     Specify account directory being restored.
/f     Specify the folder directory being restored.
/F     Specify the e-mail address in the messages being restored.


What you know
-------------
If you know the account directory and folder directory:

Command you can use
-------------------
archiver /r /R /a acct_0.act /f folder.dir /Q   archive.zip

What it does
------------
/r     Specify restore mode.
/R     Specify the allRequired mode.
/a     Specify account directory being restored.
/f     Specify the folder directory being restored.
/Q     Specify query mode.  This will ask you before restoring each
       file.

__________________________________________________________________________

Command Line Examples
---------------------

Example 1 - Archiving
---------------------

archiver /V 2 /p d:\src\pmmail /a jbayer0.act /a jbayer2.act /A 100 arch???

What it does:

/V       Verbose level of 2.
/p       Specify the source directory for PMMail.
/a       Specify the account directory jbayer0.act to back up.
/a       Specify the account directory jbayer2.act to back up.
/A       Specify to back up files which are more than 100 days old.

Create a numerically sequenced archive file beginning with arch001.zip


Example 2 - Restoring files
---------------------------

archiver /Q /r arch001.zip

What it does:

/Q       Query mode.  Ask before restoring a file.
/r       Restore mode.  Restore files from the specified archive file..


Example 3 - Reindexing
----------------------
archiver /I

What it does:

/I       Reindex all folders.


__________________________________________________________________________

Configuration File Examples
---------------------------

Example 1 - Archiving
---------------------

archivefile arch???
pmmailDirName d:\src\pmmail
accountDir jbayer0.act
accountDir jbayer2.act
fileAge 100
archiveDay Fri

What it does:

Create a numerically sequenced archive file beginning with arch001.zip.
Specify the source directory for PMMail.
Specify the account directory jbayer0.act to back up.
Specify the account directory jbayer2.act to back up.
Specify to back up files which are more than 100 days old.
Specify that archives are to be done on Fridays only.


Example 2 - Archiving using command line syntax
-----------------------------------------------

archivefile arch???
/p d:\src\pmmail
/a jbayer0.act
/a jbayer2.act
/A 100
archiveDay      Fri

What it does:

This does the same as example 1, although using the command line syntax
in the configuration file.

__________________________________________________________________________

Multiple folder filters
-----------------------

You have the following directory structure:

my.act/
       main_0.fld/
                  test_0.fld/
                  pers_0.fld/
                  spam_0.fld/
                             read_0.fld/
                             unread.fld/
                  beta_0.fld/
                             mine_0.fld/
                                        high_0.fld
                             read_0.fld/
                                        high_0.fld

You want to backup the following:

   All of beta_0.fld/mine_0.fld
   all of beta_0.fld/read_0.fld/high_0.fld
   All of pers_0.fld

Command line syntax (line is split on multiple lines for clarity)
-------------------

archiver /f beta_0.fld\mine_0.fld
         /f beta_0.fld\mine_0.fld\high_0.fld
         /f beta_0.fld\read_0.fld\high_0.fld
         /f pers_0.fld

Configuration File
------------------

NestedFolder   yes
folderDir beta_0.fld\mine_0.fld
folderDir beta_0.fld\read_0.fld\high_0.fld
folderDir pers_0.fld


What it does
------------

Each folderDir (/f) filter will cause the all the message files
in the corresponding folder to be archived.

The configuration file has the additional option "NestedFolder"
available, which will let all folders beneith the specified folder
be archived.
__________________________________________________________________________

External Exit/Hook Examples
---------------------------

This is an example of how to use an external command file to
call the archiver from within PMMail.

For OS/2 you will create a Rexx command file.  For Windows you
will create a batch file.


OS/2 Rexx command file.

   Place the following into the entry field:
      pmclose.cmd

DOS/Windows batch file
   Place the following into the entry field:
      pmclose.bat

In the pmclose.cmd/pmclose.bat file:

      archiver /V 2 /A 100 /a jbayer0.act
      archiver /V 2 /A 10 /a jbayer1.act
      archiver /i alias
      archiver /I

What it does:

   This calls the archiver four times.  The first time it will
   archive all files in the jbayer0.act directory which are at
   least 100 days old:

      /A 100         Specifies file age
      /a jbayer0.act Specifies account directory

   The second time it will archive all files in the jbayer1.act which
   are at least 10 days old:

      /A 10          Specifies file age
      /a jbayer1.act Specifies account directory

   The third time it will sort the address book file by alias:

      /i alias

   The fourth time it will reindex all folders in the PMMail directory:
      /I
__________________________________________________________________________

InfoZip and InfoUnzip
---------------------

PMMail archiver depends on the available of the InfoZip programs "Zip" and
"UnZip".  These are Freeware, compatible programs with the PKZip series
of programs.  Information on them and links to the executables are
located at:

      http://www.cdrom.com/pub/infozip/

As of Feb. 5, 1998 the files you will need to download are:

   For OS/2:

             unz532x2.exe     UnZip 5.32, OS/2 self-extr. exes (32-bit)
             zip22x2.zip      Zip 2.2, OS/2 32-bit exes (no encryption)


   For Windows-95/NT:

             zip22xN.zip       Zip 2.2, NT/95 Intel exes (no encryption)
             unz532xN.exe      UnZip 5.32, NT/95 Intel exes, self-extract

__________________________________________________________________________

Program overview
----------------

PMMail Archiver works by examining all the files in the specified directory
structure and checking the specified parameters against each file.

The following steps are taken during the archive process:

   1. Verify all the specified options for validity.
   2. For each account specified, or all accounts if none specified:
      a. Read the directory and get list of all folders.
      b. Read each folder and get list of files.
      c. Read the folder.bag file in each folder.
      d. Read each file to get file information.
      e. Check each file against filter criteria.  Eliminate files
         which don't match.
   3. Create a list of files which are to be archived.
   4. Create a file BACKUP.BAG to contain folder.bag entries for each
      file being archived.  Store full path relative to the PMMail
      directory.
   5. Call InfoZip to archive selected files.
   6. If InfoZip was successful and the files are to be deleted:
      a. Rewrite the folder.bag file for each folder, removing those files
         from the bag file which were archived.
      b. Delete the files in each folder which were archived.


The following steps are taken during the restore process:

   1. Verify all the specified options for validity.
   2. Verify the zip file exists.
   3. Unzip the backup.bag file from the zip file.  If it is not there
      then exit with an error.
   4. Read the backup.bag file to get list of files contained in backup.
   5. Filter the list of files using the specified parameters.
   6. Restore the files.  If query mode is active then query the user
      before restoring each file.
__________________________________________________________________________

Registration Information
------------------------

This program is Shareware.  You are allowed to use it for a reasonable
amount of time to evaluate it.  Please do not use it beyond the
evaluation period (30 days) without registering it. This shareware
version of PMMail Archiver has been furnished for your evaluation.  If
you find the product useful and wish to continue to use it, please take
the time to register your product.  Complete registration information is
located in the REGISTER file
__________________________________________________________________________

Support
-------

Support is provided by the author.  If you have any problems please contact
me at:

  Jonathan B. Bayer
  PO Box 561
  Edison, NJ   08818-0561

  Email: Jonathan_Bayer@bigfoot.com
  Web:   http://members.xoom.com/jbayer/archiver

Mention PMMail Archiver in the subject of your message for faster support.
Please provide your serial # and all relevant information.

__________________________________________________________________________

