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

ID: ZTN1101

This Zetafax technical note applies to:

• Zetafax 5.5 and later.

Summary

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)

                                        ENDIF

                          ENDIF

                          Wait 1 minute (to avoid interfering with server operation)

            END

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"

                                        ENDIF

                          ENDIF

                          Wait 1 minute (to avoid interfering with server operation)

            END

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.

References

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

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