POSTINO PRO by dada
The latest version of this document is always available at this URL: http://www.divinf.it/dada/perl/postino/docs

Generals

User's Manual

Other Reference Material

Introduction

POSTINO PRO
Version 1.30
by Aldo Calpini (dada@divinf.it)

POSTINO PRO is a program developed in Perl to create and mantain HTML archives of e-mail messages.

The features that this program offers are:

Have fun with it.

Aldo Calpini

Disclaimer

The program is FREE; you can redistribute, modify, disassemble, or even reverse engineer this software at your will. Keep in mind, however, that NOTHING IS GUARANTEED to work and everything you do is AT YOUR OWN RISK - I will not take responsability for any damage, loss of money or of health that may arise from the use of this program!

This program is distributed under the terms of Larry Wall's Artistic License.

Credits

A warm thank you to:

Version History

From newest to oldest; the version earlier than 1.24x (POSTINO without PRO) uses a plain text file instead of ODBC and has limited options; ask me for a copy if you need it.

POSTINO PRO
Version (Date)Changes
1.30 (20/11/96)
  • used some external aid to convert times and addresses.
  • simplified timezones processing.
  • added a modify records option in the admin program.
  • added an update form with some selective updates in the admin program.
  • added grouping by week or by day in sort by date option.
  • stopped SQLing for email from the Senders list in the search form.
  • use less HTML for the Senders list in the search form (thanks Vince...).
1.24x (06/11/96)
  • uses ODBC.
  • resolves timezone offsets in GMT during "Date:" conversion.
  • stores configuration in the registry.
  • support for multiple archives via an administration program.
  • incremental update of an archive.
  • browsing by date (year/month/day), subject or sender (first letter).
  • searching is actually made only in subjects; the text to be searched can be made of multiple keywords (AND/OR and parentesis operators allowed).
  • general commands/options reorganization.
POSTINO
Version (Date)Changes
1.24 (03/10/96)
  • by default the archive now puts you on the last page.
  • added a Thread/Unthread command.
  • added a "Sender" field on the search form.
  • added my e-mail on the bottom of each page generated by the script.
1.2 (09/09/96)
  • the archive is no more created from a Netscape mail file, but from a directory that contains message files.
  • "ftp://" links in message bodies are now converted to true links.
  • better message threading, calculated after all the messages have been parsed.
  • fixed a bug causing links in message body to be broken due to the emphasizing of searched text.
1.11 (04/09/96)
  • messages are now sorted by date.
  • improved "From:" and "Date:" conversions.
  • added an aliases file to give the same name to users with more than one name.
1.0 (12/08/96)
  • the first one.

Prerequisites

The program was tested under Microsoft Windows NT Server versions 3.51 (with Service Pack 4) and 4.0 with a Microsoft Access 7.0 database. It should run in principle under any Microsoft Windows NT/95 and with any database type that have an ODBC driver as well, but you never know... The use of this program requires, however:
  1. A Web Server installed and configured to execute Perl CGI processes.
  2. Perl for Win32 version 5.001m build 110 by ActiveWare.
  3. Win32::ODBC Perl extension (and all its prerequisites, such as an ODBC driver, etc.) by Dave Roth.
See Obtaining the latest versions for info on where to download those programs.

Manifest

This is the content of the POSTINO_PRO.ZIP file:

readme.txt a file that wants to be read...
HTML/example.html example of introductory page for an archive
HTML/*.gif sample images that you can use with POSTINO
DOCS/index.html POSTINO PRO Reference (this file)
DOCS/registry.html POSTINO PRO Registry entries
DOCS/license.html Larry Wall's Artistic License
BIN/postino_pro.pl the Browser program
BIN/postino_adm.pl the Administration program
BIN/install.bat the Install program

Obtaining the latest versions

Installation Instructions

  1. Uncompress the distribution .ZIP file with a program that supports long file names (eg. unzip, WinZip) and tell him to recreate the directory structure (eg. -d option for unzip); check with the Manifest the correct location of the files.
  2. Copy the file BIN\POSTINO_PRO.PL to a directory where it can be called as a CGI process.
  3. Copy the file BIN\POSTINO_ADM.PL to a directory where it can be called as a CGI process, but only from the administrator (eg. a password-protected CGI directory).
  4. Run the file BIN\INSTALL.BAT either by a double-click on it or from the command line.
  5. Finished.

Getting started

POSTINO PRO is splitted in two different programs: the Administration program (POSTINO_ADM.PL) and the Browser one (POSTINO_PRO.PL). This is the general procedure to follow after having installed the program:
  1. Open your web browser.
  2. Call the Administration program.
  3. Create and set up an archive. This implies also having a messages directory that contains the files to be archived, and setting up an ODBC DataSourceName (eg. database) to store the data in.
  4. Update the content of this archive.
  5. Set it as the default archive.
  6. Call the Browser program.
  7. Enjoy!

    ...and

  8. Eventually return to the Administration program to modify the archive's settings, update its content, create another archive, etc.

The Browser program

The browser program is called POSTINO_PRO.PL; you can call it as you would with a normal CGI program. Let's assume in our example that you call it as: 
  http://www.divinf.it/cgi-bin/postino_pro.pl
You can digit this URL in your Web browser's location field (and then probably bookmark it), or you can go there from an HTML page with an hyperlink like this: 
  <A HREF="http://www.divinf.it/cgi-bin/postino_pro.pl">POSTINO<A>
which will let you browse the Default archive (if one was specified). If you instead want to access a specific archive, you can add a parameter "archive" to the link, like: 
  <A HREF="http://www.divinf.it/cgi-bin/postino_pro.pl?archive=archivename">POSTINO<A>
Where archivename is the name of the archive you want to access. Alternatively, you can write a form like this: 
  <FORM ACTION="http://www.divinf.it/cgi-bin/postino_pro.pl">
    <INPUT TYPE=hidden NAME=archive VALUE="archivename">
    <INPUT TYPE=submit VALUE=POSTINO>
  </FORM>
The first line after the title of each page generated by the Browser program will display the available commands. The three main functions are: You can always switch from one function to another by clicking on those commands.

The Browsing mode

Once you have called the Browser program, you will be, as the name implies, in browsing mode. A number of messages (by default all the messages posted in the last day of the archive) will be shown on your page; you can display the content of a message by clicking on its subject. You also have a toggle to Thread/Unthread the messages shown and three Sort options: by date, by subject or by sender.

Thread/Unthread

This function acts like a toggle (eg. if you click on "Unthread" it means that you were in threaded mode and vice versa).

In Thread mode only the first message of each thread (eg. topic) is shown; the presences of replies to a topic is indicated by an icon before a messages data. This icon is usually a plus sign that you can click to expand the thread (eg. see all the replies to a topic); once expanded, the plus on the icon should becomes a minus; click it again to collapse the thread. You can have only one thread expanded at a time.

In Unthread mode, instead, all the messages are shown at the same level with the selected sort option.

Sort options

You can choose to sort the messages in the archive by date, by subject or by sender.

With a sort by Date option, each page will show the messages in a week. You can then browse by changing the Year, the Month and the Week that you want to see, or you can choose to Group by days instead of weeks.

With the sort options by Subject or by Sender, the archive is sorted alphabetically, and each page will show all the messages with the same first letter on the choosen field. Click on a letter on the Letters line to choose which page you want to see.

Viewing a message

When you click on a message's subject you will open it and read its content; just before it, you will see (if they exist) all the messages in the Thread to which this message belong; they also can be viewed by clicking on their subjects. The subject of the message that you're viewing is instead displayed in bold, and the name of the author as a link; if you click on it, you can send him/her an e-mail message.

The Search command

When you click on the Search command, you will get a form where you can give a text to search for and/or a sender.

The text is made up of keywords, eventually combined with AND/OR and parentesis operators to build complex queries.

Examples:

split
will find all the messages that contains "split" in the subject.
split join
will find all the messages that contains "split" and "join" in the subject.
split and join
same as above.
(split and join) or database
will find all the messages that contains "split" and "join" in the subject, plus all the messages that contains "database".

You can eventually select a name from the senders list and restrict the search only to the messages posted by that user. You can also choose a sender and leave the text blank to see all the messages posted by that user.

When you have filled the form, press the Search button to start the search. From the results page you can click on a message's subject to display it, as in Viewing a message.

Who

This option will show a list of the users that posted to this archive, and the number of messages each one did post. If you click on a user's name you can send him/her an e-mail message. You can also sort the list alphabetically (by user name) or by number of messages posted (in descending order).

The Administration program

The administration program is called POSTINO_ADM.PL; you can call it as you would with a normal CGI program. Let's assume in our example that you call it as: 
  http://www.divinf.it/adm-bin/postino_adm.pl
You can digit this URL in your Web browser's location field (and then probably bookmark it), or you can go there from an HTML page with an hyperlink like this: 
  <A HREF="http://www.divinf.it/adm-bin/postino_adm.pl">Administer POSTINO<A>
If your site is publically accessible through the Internet, you would probably place the program in a password-protected CGI directory, otherwise everyone will be able to change your configuration and delete the archive you created.

Once you have called the program, you will see a list of the Archives defined; you can select an archive from this list and then click one of the buttons on the right to modify its configuration, set it as the default archive, update its content, delete it and finally modify manually the messages data.
If you never created an archive, however, the list will be empty. Then you have a New Archive field in which you can enter the name of a new archive and click the Create button to create a new archive.
Then again, there is the name of the Default Archive that you can choose by clicking on the Configure POSTINO button.

Creating a new archive

To create a new archive, from the main page of the Administration program type in the name you want to give to it in the field New Archive and press the Create button. A form will appear asking you to fill in the settings for this archive, which are in order:

Name

This is the name of the archive that will appear in the <TITLE> tag of each HTML page regarding it. 
Default:  the name of the archive just created

Examples: Perl - Win32 - Archive
          MY E-MAIL ARCHIVE

Message directory

Absolute path to a directory that contains the message files to archive. See Messages format for more details. 
Default:  none

Examples: d:/users/dada/mail
          c:/mailbox/dada

Message files

The files that will be searched for in the Message directory; it is a normal DOS file specification. 
Default:  *.msg

Examples: 1996*.msg
          *.*

HTML File

Absolute path to an HTML file that will be automatically updated with the archive data (last update time and number of messages). 
Default:  none

Examples: d:/http/postino/index.html
          d:/www/mailarchives/privatemail/info.htm
The HTML File should contain the following HTML comments: 
<!--POSTINO_LAST_UPDATE-->...<!--POSTINO_LAST_UPDATE_END-->
<!--POSTINO_MESSAGES-->...<!--POSTINO_MESSAGES_END-->
The text between the comments (...) will be replaced with the actual values: respectively, the date/time in which the archive was last updated and the number of messages it contains.

Alias File

Absolute path to an file that contains the aliases to apply to this archive. Aliases are used to give the same name to users with more than one name; the file must contain an alias per line in the format "from > to". An example alias file can be: 
A. Calpini > Aldo Calpini
A.Calpini > Aldo Calpini
Calpini Aldo > Aldo Calpini
dada > Aldo Calpini
dada@divinf.it > Aldo Calpini
and so on. 
Default:  none

Examples: d:/users/dada/postino.aliases
          d:/www/mailarchives/privatemail/aliases.txt

DSN

This is the ODBC Data Source Name (eg. database) that will receive data from POSTINO PRO. You have to manually define the DSN from the control panel and make sure it is callable from a CGI process. Refer to the Win32::ODBC documentation for info on how to setup such a DSN. 
Default:  none

Examples: Postino
          DSN=Postino;UID=myname;PWD=mypassword

Table

The table that will receive data from POSTINO PRO. It must of course exist in the given DB_DSN and its fields should be set up to fit the POSTINO data that will come. It is a valid database table name. 
Default:  none

Examples: Perl-Win32
          privatemail

Fields

The name of the fields that will contain the data:
Field Type Use
ID Counter The identification number of the message
ParentID Number (integer) Used to thread messages
Year Number (integer) The year number
Month Number (integer) The month number
Day Number (integer) The day of the month number
Hour Number (integer) The hour
Minutes Number (integer) The minutes
Subject Text (255 chars) The subject of the message
Name Text (255 chars) The name of the sender
Email Text (255 chars) The e-mail address of the sender
File Text (255 chars) The name of the file (in the message directory) that contains the body of the message
Defaults are the bold field names in the above table; note also that POSTINO will create some additional fields in your table (actually it creates "NewRecord", "Subject_FirstLetter" and "Name_FirstLetter") to simplify its operations.

Image Expand

The URL to an image that will be put on the HTML pages when a message contains child messages (replies); this happens of course when you are browsing an archive in Thread mode. It is normally a plus sign icon and should be of the same size of the Collapse and Void images. 
Default:  /postino/expand.gif

Examples: http://www.divinf.it/perl-win32/expand.gif
          http://www.name-at-will.com/icons/plus_sign.gif

Image Collapse

The URL to an image that will be put on the HTML pages when a message was expanded. It is normally a minus sign icon and should be of the same size of the Expand and Void images. 
Default:  /postino/collapse.gif

Examples: http://www.divinf.it/perl-win32/collapse.gif
          http://www.name-at-will.com/icons/minus_sign.gif

Image Void

The URL to an image that will be put on the HTML pages when a message has no childs (instead of the Expand/Collapse images). It should be a blank image (eg. a .gif filled with transparent color) of the same size of the Expand and Collapse images. 
Default:  /postino/void.gif

Examples: http://www.divinf.it/perl-win32/void.gif
          http://www.name-at-will.com/icons/nothing.gif

HTML Body

The <BODY> tag for the HTML pages of this archive. 
Default:  <BODY BGCOLOR="#FFFFF0">

Examples: <BODY>
          <BODY BACKGROUND="email.gif" LINK=red>

HTML Title

This will appear in the first line of the generated HTML pages; it can be a complete HTML fragment. 
Default:  <FONT COLOR=red>POSTINO</FONT> <FONT COLOR=indianred>PRO</FONT>

Examples: <FONT SIZE=+2>MY E-MAIL ARCHIVE
          <IMG SRC="http://www.name-at-will.com/images/email_big.gif">
Note that this title will be preceded by the HTML Title Font you specify; POSTINO will try to close the HTML tags left open; this applies actually on FONT, B, I, U, TT, PRE and BLINK tags.

HTML Title Font

This will be the font used for the title in the first line of the generated HTML pages; it is an HTML format definition. 
Default:  <FONT FACE=Arial SIZE=3><B>

Examples: <I>
          <FONT COLOR=green SIZE=7><B><U>
Note that POSTINO will try to close the HTML tags left open; this applies actually on FONT, B, I, U, TT, PRE and BLINK tags.

HTML Normal Font

This will be the font used for almost all the texts (commands, messages data, etc.) in the generated HTML pages; it is an HTML format definition. 
Default:  <FONT FACE=Arial SIZE=2>

Examples: <FONT>
          <FONT COLOR=yellow><I>
Note that POSTINO will try to close the HTML tags left open; this applies actually on FONT, B, I, U, TT, PRE and BLINK tags.

Once you are satisfied with your settings, press the OK button to save the archive. You can then change those settings or update the archive content to have something to browse...

Choosing the default archive

When you call the Browser program, you can pass him an "archive" parameter to select which archive you want to browse. If you don't pass this parameter, POSTINO PRO will let you browse the Default Archive. To set this value, choose an archive from the selection list Archives and press the Set as default button. Now, when you call the browser program the selected archive will be browsed without the need of the "archive" parameter.

Changing the configuration of an archive

To change the configuration settings for an archive, from the main page of the Administration program select an archive from the list of the Archives and press the Configure button. A form will appear with the current settings for this archive that you can modify and then save pressing the OK button. The settings are the same explained here above for creating a new archive.

Updating an archive

Once you press the Update button, a page will appear showing you the current number of records in the database and of files in the messages directory. You can then press the Update button to confirm that you want to update the archive's content, or one of the Selective Updates to refresh the aliases or the timezones of the whole archive.

When updating the archive, the files matching the given specification are searched for in the given directory and, if a corresponding record is not found in the database, they are added to it. In fact, when you have just created an archive you would probably perform an Update to insert the records in the database.

This is the workflow of the Update procedure:

  1. records in the DB are counted, to add after the last one.
  2. files in the message directory are retrieved.
  3. files that are not present in the DB (eg. new files) are selected.
  4. new data are added to the DB.
  5. messages are threaded.
  6. indexes of the first letters for subjects and senders are updated.
  7. finished; you can now browse your archive.

When the program is adding records, you will sometimes get warning messages about unrecognized timezones; this is due mainly to the presence of non-standard or meaningless timezone information that comes from some mail server. If you encounter such a case, I please you to inform me via e-mail so I can patch the program to recognize it. That's why there is an Update timezones option.

Updating the aliases

This option is useful when you don't want to update the whole archive content, but you have made some changes to the aliases file. When you press the Update aliases button, all the names of the selected archive will be updated to reflect the content of the aliases file you specified in the archive's configuration.

Deleting an archive

To delete an archive simply select it from the Archives selection list and press the Delete button. Another page will appear asking you to confirm the deletion of the archive, and if you do so by pressing the OK button, it will be finally deleted. Note that this action doesn't delete the messages files that were archived, nor does it delete the records in the archive's database; just the configuration values are deleted, and of course that archive will be no more available for POSTINO PRO.

Modifying the records of an archive

This option allows you to review or modify the single records in the archive. You will get a list of messages similar to the browsing page; however, you can move yourself among the records selecting a page, choosing the exact number of records you want to see, or finally giving the filename of the single message you want to modify. If you click on a message's subject, you'll get a form in which you can change any of the message's data fields. Click Save record to confirm the modifications.

Messages format

For the correct operation of POSTINO PRO, the messages to be archived must reside in a single directory; each message must be in a single file and all those files should have an unique file name specification (eg. "*.msg"). The format of the file must be RFC822 compliant (standard mailbox format); in particular, POSTINO PRO expect to find in files:

How to give feedback

Please send any comments, suggestions, bug reports to Aldo Calpini.

Troubleshooting

Trouble: I get an error "Can't locate Win32::Registry..." when running the install program.
Reason: You either don't have Perl for Win32 version 5.001m build 110 installed, or it is not installed properly.
See Obtaining the latest versions and go to the Perl for Win32 Home Page for info on how to downlad and install Perl.
Trouble: I get an error "Can't locate Win32::ODBC..." when running the install program.
Reason: You either don't have the Win32::ODBC Perl extension installed, or it is not installed properly.
See Obtaining the latest versions and go to the Win32::ODBC Home Page for info on how to downlad and install Win32::ODBC.
Trouble: I get "Error opening ODBC connection" when running POSTINO PRO.
Reason: You either misspelled something regarding the ODBC connection in the archive's settings or the ODBC DSN is not accessible from your Web Browser.
See the Obtaining the latest versions and go to the Win32::ODBC Home Page for info on how to setup a correct DSN.
Trouble: I get an URL not found error when clicking any link of POSTINO PRO and/or POSTINO ADM.
Reason: Your Web Server doesn't pass the correct "SCRIPT_NAME" environment variable to the script.
This could happen for example if you call the script with PerlIS.dll on a server like Alibaba, that supports PerlIS.dll as an ISAPI alias and gives the script name as an extra-path information. To solve the problem, go in the Registry Editor and set the URL and/or AdminURL values in the POSTINO registry key to the complete URL you use to call them. See also Registry Entries for more info on the registry structure of POSTINO.

Last updated 20/11/1996 by Aldo Calpini.