MHonArc v2.5 -- Appendix: Diagnostics

# Appendix: Diagnostics

Three types of messages exist in MHonArc: Informative messages, Warnings, and Errors. Informative messages give you the current status of MHonArc's execution. Warnings signify undesired conditions, but are not critical in MHonArc's exection. Errors signify critical conditions that inhibit MHonArc from finishing its task.

Another set of messages exists that are generated from the Perl interpreter itself. MHonArc tries its best to catch any conditions that may cause Perl to abnormally abort, but conditions may arise where this is not possible.

This section describes the various diagnostics MHonArc may produce and messages Perl may produce.

- Informative messages
- Warnings
- Errors
- Perl Messages

## Informative messages

Informative messages may be suppressed via the QUIET resource. Only the more important Informative messages are listed here.

#### No new messages

No new mail messages exist when performing an add operation to an archive. This can occur if an empty MH mail folder, or empty mailbox file, is passed to MHonArc; or the folder contains messages already in the archive.

#### Trying to lock mail archive ...

The statement means that a lock file is in place for the archive you are trying to update. Normally, an existing lock file implies that another MHonArc process is currently using the archive, and other MHonArc processes will wait awhile to see if the archive will be unlocked. The time MHonArc waits can be modified by the LOCKTRIES and LOCKDELAY resources.

There are times when a lock file exists, but no MHonArc process is modifying the archive. This can occur if MHonArc is abnormally terminated. If you know that no other MHonArc process is editing the archive you are try to modify, then manually remove the lock file or use the FORCE resource.

WARNING | If LOCKMETHOD is set to `flock`, then the lock file should never be manually deleted. When MHonArc abnormally terminates, then the lock will be automatically released when the `flock` method is used. A stale lock can still occur under the `flock` method if for some reason a MHonArc process hangs. In this case, just kill the offending process and the lock will automatically be released.

## Warnings

Warning messages denote some undesired event occurred, but the event is not severe enough to cause program termination.

#### Warning: Could not find date for message

MHonArc was unable to find a date for a mail message, or could not parse the date if the date is not in a common format. The message is given the current date if no date is found.

#### Warning: Database (dbversion) != program (prgversion) version

Indicates that the version of MHonArc updating an archive is different from the version of MHonArc that created the database file. Problems can arise if the database file changes in format from different version of MHonArc. See the release notes of the MHonArc distribution if changes in the databse format will effect older archives.

#### Warning: Unable to create outdir/dbfile

Indicates MHonArc was unable to create the database file dbfile for the mail archive created/modified in outdir. This message can occur if outdir permissions changed during MHonArc execution, the existing dbfile is read-only, or the file system is full.

This warning can be severe because no future add operations can be performed to the archive.

#### Warning: Unable to open footer: footer

MHonArc was unable to open the footer file, footer, for inclusion into the index page. Make sure footer exists, and is readable by you.

#### Warning: Unable to open header: header

MHonArc was unable to open the header file, header, for inclusion into the index page. Make sure header exists, and is readable by you.

#### Warning: Unable to open folder

MHonArc was unable to open the specified mail folder for reading. Make sure folder exists and is readable (and executable if a directory) by you.

#### Warning: Unable to open message: folder/message

MHonArc was unable to open the specified MH mail message folder/message for reading. Make sure folder/message exists and is readable by you.

#### Warning: Unable to open resource file: file

MHonArc was unable to open the resource file, file, for reading. Make sure file exists, and is readable by you.

#### Warning: Undefined time zone: "timezone"

MHonArc has found an unrecognized timezone acronym, timezone, in a mail message. You can tell MHonArc about other timezone acronyms, and their hour offset to UTC, by using the TIMEZONES resource

The timezone UTC (or GMT) is used for an undefined timezone acronyms.

## Errors

Errors denote conditions that cause MHonArc to abort execution.

Some error conditions may cause the MHonArc archive to become corrupted. If the error occurs when MHonArc is writing files, you may have to recreate the archive from the original messages.

#### ERROR: Database read error of dbfile

An error occured when trying to read an archive's database. The error can occur if the database file is not readable or the file got corrupted.

#### ERROR: Unable to create file

MHonArc was unable to create file. This message can occur if the directory being written to is not writable, a read-only file with the same name exists, or the file system is full.

#### ERROR: Unable to create lockfile after # tries

The statement means that MHonArc timed-out trying to obtain a lock on the archive. You may be able to avoid time-out problems by modifying the LOCKTRIES and LOCKDELAY resources.

Sometimes a lock file exists, but no MHonArc process is modifying the archive. This can occur if MHonArc is abnormally terminated. If you know that no other MHonArc process is editting the archive you are try to modify, then manually remove the lock file or use the FORCE resource.

WARNING | If LOCKMETHOD is set to `flock`, then the lock file should never be manually deleted. When MHonArc abnormally terminates, then the lock will be automatically released when the `flock` method is used. A stale lock can still occur under the `flock` method if for some reason a MHonArc process hangs. In this case, just kill the offending process and the lock will automatically be released.

#### ERROR: Unable to open file

MHonArc was unable to open file for reading. Make sure file exists, and is readable by you.

#### ERROR: Unable to require perl-library

Make sure you properly installed MHonArc. Also make sure Perl is installed properly if the library is a standard Perl library.

## Perl Messages

Generally, if execution is aborted and the following error messages appear, then you will have to manually delete the lock file since MHonArc will not have the chance to delete the file.

#### Can't locate file in @INC at file line number.

A library that MHonArc tried to load was not found in the Perl include search paths. This error usually implies that MHonArc was not installed correctly. Make sure that MHonArc was installed via the `install.me` program that is provided in the MHonArc distribution.

#### file did not return a true value at file line number.

If you are using your own MIME filters with MHonArc, make sure the library files return a true value, like `1`.