Technical Notes, Zetafax

FIX: Deleting messages can corrupt MSGDIR file in automated systems

ZTN1887

ID: ZTN1887

This Zetafax technical note applies to:

  • Zetafax version 2011 or earlier
  • Automated applications using the Zetafax API or ZSUBMIT program

Symptom

This issue can result in one or more of the following symptoms when deleting a message with the Zetafax Client:

  • Deleting messages using the Zetafax Client displays the following error message
    • Cannot write to file: zfax\USERS\username\Z-OUT\MSGDIR.CTL

(where zfax is the folder where the Zetafax Server files are installed)

  • Messages which have been deleted are initially removed from the Zetafax Client Outbox window, but reappear when the Outbox display is next updated
  • The Zetafax Client log file %TEMP%\Zetafax.log contains the following error:
    • Cannot open file for update zfax\USERS\username\Z-OUT\MSGDIR.CTL

Subsequently this issue can result in one or more of the following symptoms:

  • Running the Zetafax Client displays the following error message:
    • One of your MSGDIR.CTL files has either been deleted or corrupted and will be rebuilt
  • Displaying the message history using the Zetafax Client fails for some messages, showing a dialog box containing no information about the message other than the filename.
  • Submitting messages using the Zetafax API or ZSUBMIT fails intermittently, returning the error code ZFERR_MESSAGE_ALREADY_EXISTS to the application and displaying the following error message in the Server.log file or application log:
    • Message messagename already in info file

(where messagename is the base filename for the message files eg ~SEND123 or ~ZAPI123)

  • The Zetafax Client log file Zetafax.log (stored in the %TEMP% folder) contains the following error after submitting a fax using the Zetafax Client
    • Referenced file : zfax\USERS\username\Z-OUT\messagename.* no longer exists
  • For systems submitting messages using the Zetafax Client, the Outbox folder zfax\USERS\username\Z‑OUT contains one or more files with .TMP file extension of zero size
  • For systems submitting messages using the Zetafax API (using an application built integrated with the API or the Zetafax Server ZSUBMIT program), the Outbox folder zfax\USERS\username\Z‑OUT contains one or more files with .TMP file extension containing the following text:
    • (created by ZfxSendSubmitFile() because files messagename.* deleted previously without deleting references in MSGDIR.CTL)
  • For applications using the Zetafax API, retrieving information fails for some messages, returning an error code to the calling application or returning a message status of ZFMSG_UNKNOWN

Cause

This issue occurs when the Zetafax Client program is unable to access the message information file MSGDIR.CTL for an extended period of time.  This can occur if a third party application is using the Zetafax API intensively, causing the operation of the Zetafax Client and Zetafax Server to be adversely affected.

Zetafax stores each fax message in a series of files with the same file body name and different file extensions (eg ~SEND123.CTL, ~SEND123.G3F).  Zetafax also stores a summary of all messages in a folder in a file called MSGDIR.CTL in that folder, to make it quicker to display a list of all messages.  Each message (eg “~SEND123”) has exactly one entry in the MSGDIR.CTL file.

When a new message is submitted (added to the Outbox), Zetafax first finds a filename which is not already used, then checks the MSGDIR file to ensure it does not already contain an entry for that filename before adding a new entry.  When a message is deleted by Zetafax (Zetafax Client, Zetafax Server or Zetafax API), the software removes the entry from MSGDIR.CTL before deleting the message files. 

When deleting a message, if Zetafax is unable to remove the entry from MSGDIR.CTL the software should abort the operation and leave the message file undeleted, so that message file is not reused.

However, due to a fault in the Zetafax Client software, the client can delete the message files in some circumstances even if it is not able to update the MSGDIR file – for example if the file is locked for an extended period by another application.

This problem is unlikely to occur on most systems.  However, the chance of the issue occurring increases significantly on systems where the user’s Outbox contains a large number of messages (typically over 500), increasing the time taken to read or update the MSGDIR file, or where the volume of faxes being sent by an individual user account is high. 

Resolution

The fault in the Zetafax Client software has been corrected, and included with Zetafax 2012.  This release includes other features to improve performance in automated systems, and we recommend that customers experiencing this issue with older software versions upgrade to Zetafax 2012 or later.

A software update for the Zetafax Client is also available for some older system versions to correct this specific issue only, for instances where it is not possible to upgrade to Zetafax 2012.  Please contact Equisys technical support for further details.

Systems where the MSGDIR.CTL file is locked for extended periods can experience a number of performance and other issues.  It is recommended that Zetafax systems are configured to minimise the likelihood of this occurring, using the approaches described in the technical note listed in the reference section (see below).

Deleting message files manually (eg using Windows Explorer or an independent batch process) can give similar symptoms, as this does not remove entries from the MSGDIR file.  This is not a supported action for normal operation, and should only be done in specific circumstances on instruction from technical support staff.

Status

This issue is resolved in Zetafax 2012 and later versions.

References

ZTN1888-HOWTO Protecting access to MSGDIR file in automated systems

Last updated:  24th April 2012 (GW/MW)

Keywords: