PC Online 1998 September

home *** CD-ROM | disk | FTP | other *** search

/ PC Online 1998 September / PCO_0998.ISO / filesbbs / os2 / archiv19.arj / ARCHIVER.ZIP / MANUAL < prev next >

Wrap

Text File | 1998-07-14 | 33.2 KB | 851 lines

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. __________________________________________________________________________