This sections explain in detail how MHonArc functions. Knowing the material covered in this section may help you when trouble shooting.
MHonArc will automatically detect which operating system it is running under. If the following list of conditions are true, MHonArc assumes it is running under MS-DOS:
COMSPEC environment variable is defined.
COMSPEC environment variable is a legal MS-DOS
pathname.
The value of the COMSPEC environment variable is an executable file.
If any of the above conditions is false, MHonArc assumes it is running under Unix.
The previous conditions are used since the conditions will exist if Perl has been installed on an MS-DOS machine. None of the above conditions exist when Perl is installed on a Unix system.
This section describes the steps MHonArc performs when creating/editting an archive. Anytime messages are added or deleted or the index page layout is changed, MHonArc will perform the following steps.
Creates a lock file. This insures only one MHonArc process is updating the archive at any given moment. See Archive Integrity for more information.
Reads the database file. The name, and location, of the database file can be
explicitly specified via the M2H_DBFILE and M2H_OUTDIR environment
variables or the command-line options -dbfile and -outdir.
Otherwise, the current working directory is used.
NOTE: The database file must be in the same location as the archive since the
M2H_OUTDIR variable and -outdir option also specify the location of the
archive.
The database file contains data to update any mail threads and the resource settings when MHonArc was last invoked. This allows new messages to contain the same formatting/resource specifications as existing messages in the archive without having to re-specify the resources each time new messages are added. Resources defined in the database file override the environment variables.
NOTE: If no database file is found, MHonArc will create a new archive.
Read the MHonArc resource file, if specified. The resource file will override any settings contained in the database file.
Read the settings specified on the command-line. Command-line options override any settings in the database and/or resource file.
Update archive.
Rewrites the index pages to reflect the update.
Writes a new database file containing the new state of the archive and all (new) resource settings.
Normally, knowing all the previous steps is unnecessary. However, it may be useful to be aware of them if unexpected behavior, or errors, occur.
MHonArc applies safeguards to try to insure that a mail archive does not get corrupted due to exceptional circumstances. MHonArc does the following to insure a mail archive does not get corrupted:
MHonArc creates a lock file, ".mhonarc.lck", when creating/updating
an archive. The lock file insures that only one MHonArc process is
modifying an archive at any given moment. The -locktries
command-line option, or the M2H_LOCKTRIES environment variable,
allows you to control how long a given MHonArc process will wait if an
archive is currently locked. If MHonArc can not lock the archive after the
specified number of tries, MHonArc will exit, unless the -force option is
specified.
MHonArc will ignore the following signals once messages are actually
being written to disk: SIGABRT, SIGHUP, SIGINT, SIGQUIT, SIGPIPE,
SIGTERM. Possible archive corruption can still occur if a SIGKILL signal
is received since SIGKILLs are uncatchable. A SIGKILL will also prevent
MHonArc from deleting the lock file.
The MHonArc database file is actual Perl code. MHonArc requires it like any other Perl library to load in the contents of the database.
You should never modify the database file by hand. Changing the file by hand could cause future incorrect/unpredictable behavior when processing the archive.
The indexes and message files are legal HTML documents. However, manual editting of the documents is discouraged. The documents contain special comment declarations. The comment declarations act as markers which allow MHonArc to correctly edit the documents when needed.
The comment declarations look like the following:
<!--X-Body-Begin--> <!--X-User-Header--> <!--X-User-Header-End--> <!--X-TopPNI--> ...
Derived files are files that are generated by the MIME filters. These files are created when the data being processed in messages cannot be converted to HTML (eg. images, postscript, video, binaries). The format of these files depend on the content-type of the data.
Here is the explicit order of decreasing precedence when setting resources/options:
environment variables (lowest precedence)
Mail thread detection is dependent upon the mail messages containing the message id(s) of referenced messages. Most mailers reply function will automatically include the message id of the message being replied to.
All mail message being converted into HTML are stored in memory before they are written to disk. This can eat up much memory if many mail messages are being converted. If you are processing multiple mailboxes/folders and worried about memory, you can try the following:
-add option.
Or, invoke MHonArc with the -savemem option.
The database file, and the index pages, are completely rewritten evertime new messages are added. This may cause slight slow-downs when archives become very large.
When reading MH mail folders, mail message are assumed to have numeric filenames.
When sorting by date, MHonArc tries to use the date listed in the first Received field of the message. If no Received field exists, than the Date field is used.
No distinction is made, in the output, on which messages came from which mail folder if multiple mail folders are processed.
MHonArc can probably be modified to handle other types of mailers
(which has been done since the original version only supported MH mail
folders). The MSGSEP resource gives flexibility in processing Unix style
mailbox files.