Equisys technical notes

Technical guidance, explanations and fixes for our products

HOWTO: Monitor the status of submitted faxes using the Zetafax API



ID: ZTN1101

This Zetafax technical note applies to:

  • Zetafax 5.5 and later.


The Zetafax API makes it simple to submit faxes to the Zetafax server for sending, which can then be monitored using the Zetafax client program.  For many systems that is sufficient - if a fax fails, the user will see this in the Zetafax client and can resubmit the fax manually.

However the Zetafax API also makes it simple to monitor the status of submitted faxes, allowing an application program to report the status of faxes it has submitted, or take appropriate action if a fax fails.  For example, if a fax fails the program could log an error, try with an alternative fax number, or send an e-mail notification to the administrator.

More information

The following API functions are particularly useful in this type of application:

ZfxGetMsgList - returns a list of messages for a specific Zetafax user, and their final status (eg queued, sending, sent OK, failed).   This includes queued messages, and completed messages which have not yet been deleted from the INFO file (MSGDIR.CTL).

ZfxGetMsgInfo - returns information about a specific message, including the status.

ZfxGetMsgHistory - returns detailed transmission history for a specific message, including the status of each recipient (for messages sent to multiple users) and details of each call attempt.

ZfxDeleteMsg - deletes a completed message.

There are two general approaches that can be used:

Use a dedicated Zetafax account, and monitor all messages for that user.

Where an application can have its own dedicated Zetafax account, it can treat the messages in that account as its own queue.  The logic for monitoring would be as follows:

            WHILE running
                          Get status of all messages (using ZfxGetMsgList)
                          FOR each message
                                        IF message submitted by this application
                                        AND message status OK or FAILED
                                                    Read detailed message history (using ZfxGetMsgHistory)
                                                    Take required action
                                                    Delete message (using ZfxDeleteMsg)
                          Wait 1 minute (to avoid interfering with server operation)

This method is efficient where messages are submitted as a single user, since retrieving the status of all messages for one user involves reading a single file only (the INFO file, MSGDIR.CTL), and where the application " owns" all the messages in the account. 

It becomes less efficient when there are many users being monitored, or where there are very many queued messages (e.g. 300 or more, since reading the INFO file takes longer).

Keep a separate list of submitted messages, and monitor them individually

Where an application wants to submit faxes as many different users it is inefficient to monitor the status of messages in each account.  In this case it is better to keep a separate list of messages that have been submitted in some form of database, then request the status of each one independently.

This method is particularly efficient where the total number of queued messages is relatively small (e.g. 100 or fewer), since each status request requires a file access.  It is unaffected by whether the messages are in multiple accounts or a single account.

The list of submitted messages should include the user and the fax message file, and can be implemented in a number of ways - e.g. stored in a database, in a simple text file or in the registry.  The Zetafax HPSCAN program uses this mechanism, implemented simply as an " in progress" file for each submitted message, stored in its own directory.

Note that the database needs to be " persistent" - i.e. not lost if the program restarts - since if the computer is restarted the Zetafax server automatically requeues any outstanding faxes.

The logic for monitoring would be as follows:

            WHILE running
                          FOR each message in " database"
                                        Get status of this message (using ZfxGetMsgInfo)
                                        IF message status OK or FAILED
                                                    Read detailed message history (using ZfxGetMsgHistory)
                                                    Take required action
                                                    Delete message (using ZfxDeleteMsg)
                                                    Delete entry from " database"
                          Wait 1 minute (to avoid interfering with server operation)

Note:  When you decide how often to check the status of messages, remember that any interrogation of the server has an impact on performance, however small.  You could write an application program which checked the status of a message every second, and it would notice when a fax completed very quickly.  However, spotting changes that quickly is almost certainly unnecessary, and could also reduce the throughput of the server.

Even if you want to spot changes more quickly when developing and testing your program, for most live applications checking for message completion every 1 minute or even 5 minutes is sufficient, and will reduce adverse affects to a minimum.


For more information on the functions, and other aspects of the Zetafax API, see the " Zetafax API manual" .

Last verified:       14 November 2005 (CT/EB)
Last updated: 1 December 2000 (GW/GW)

Equisys Logo, Document Management and Expense Management for Business Central

Replaced by script
Recent news

The sudden rush towards remote working practices in 2020 led many organizations to implement changes to upgrade their document capture processes on Microsoft Dynamics 365 Business Central or ...

Company credit cards are often seen as the most convenient way to incur travel & entertainment expenses, however it can be a very different story when it comes to the administration of these ...

North America
Equisys Inc
30000 Mill Creek Avenue
Suite 335
Alpharetta, GA 30022
(770) 772 7201
Equisys Ltd
91 Southwark Bridge Road
United Kingdom
+44 (0)20 7203 4000

© Equisys Ltd
All rights reserved

© Equisys Ltd    All rights reserved    Contact    Privacy policy    Cookies