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: