HOWTO: Use DDE to automate sending faxes from within Zetafax

ZTN1315

ID: ZTN1315

This Zetafax technical note applies to:

• Zetafax 8.0.0.104 and later

Summary

This document will tell you how to send faxes with the Zetafax client using DDE. This document assumes that you have familiarity with programming and access to documentation explaining how DDE works in your chosen environment.  This document will:

• Explain when you should use DDE to automate Zetafax
• Explain the initialisation, commands and parameters you can use.
• Provide two pseudo-code functions for sending a fax with DDE; one for sending a single fax, and one for sending a multi-part fax to a single recipient.
• Provide the VBA code for two Microsoft Word macros, one sending a multipart fax and one sending a single fax.

When Should You Use DDE?

When you print a fax to the Zetafax Printer the Zetafax client usually pops up a dialog box so that you can address the fax. Using DDE you can address the fax programmatically so the client doesn't need to prompt for user input.

You could use DDE to send faxes if:

• The client is likely to be running
• The user is likely to be at the machine when DDE runs
• You do not have an API licence

You should NOT use DDE to send faxes if:

• You need to track the fax's status after it has been sent
• Your code needs to run completely unattended (e.g. on a server)
• You need to send over 200 faxes at once

In all these situations you would need to use the Zetafax API.

DDE Initialisation, Commands and Parameters

DDEInitialize Parameters

When you initialise a DDE session you need to know the application name and the DDE topic. The application name is "Zetafax" and the topic is "Addressing". So to initialise the DDE session you would call:

          chan = DDEInitialize "Zetafax", "Addressing"

Note: This call will only succeed if the Zetafax client has started.

DDEExecute Parameters

You use DDEExecute to send commands to the client. Commands should be placed in square brackets.  You can send multiple commands with a single call to DDEExecute. So to send a fax then release the client from DDE control at the same time you would write the following:

          DDEExecute chan, "[Send][DDERelease]"

This table lists the commands that can be sent to the Zetafax client.

The first thing you should do once the DDE session has started is execute a "DDEControl" command. The last thing you should do before you terminate the DDE session is execute a "DDERelease" command. Between these two commands the client is under the control of DDE, and will not respond properly to user input.

DDEPoke Parameters

This table lists all the settings that can be poked into the client before a fax is sent. Each of these settings can also be used in embedded addressing.

Pseudo-code Functions

Note: Writing in green are comments

Single part fax

'Sending a single part faxes

DDEInitialize 'Zetafax', 'Addressing'

DDEExecute '[DDEControl]'

While Faxes left to send

      Print to Zetafax Printer

      Wait for print job to finish

      If we want to poke the entire address in one go

              DDEPoke 'To', 'Andrew, Equisys, 020 7203 4005'

      Else

              DDEPoke 'Name', 'Andrew'

              DDEPoke 'Organisation', 'Equisys'

              DDEPoke 'Fax', '020 7203 4005'

      End If

      DDEPoke 'Priority', 'Urgent'

      'Poke all other settings as required'

      If we want to preview fax

              DDEExecute '[Preview]'

      Else If we want to send the fax

              DDEExecute '[Send]'

      End If

End While

DDEExecute '[DDERelease]'

DDETerminate

Multiple part fax

'Sending a multi-part fax to a single addressee'

DDEInitialize 'Zetafax', 'Addressing'

DDEExecute '[DDEControl]'

Loop

      Print to Zetafax Printer

      Wait for print job to finish

      If No more printing to do

              Exit Loop

      End If

      DDEExecute '[MultiPart]'

End Loop

DDEPoke 'To', '"Andrew", "Equisys", "020 7203 4005"'

'Poke all other settings as required'

'Multiple DDEExecute calls can be combined'

DDEExecute '[MultiSend][DDERelease]'

DDETerminate

Sample VBA Word Macros

Single part fax

' SendMultiFax fax macro

' Macro created 11 June 2004 by Equisys plc.

'

Public Sub SendMultiFax()

      Dim chan

      chan = DDEInitiate(" Zetafax" , " Addressing" )

      DDEExecute chan, " [DDEControl]"

      ActivePrinter = " Zetafax Printer"

      ' Print the document three times and use it as a multipart fax

      For i = 1 To 3

              Application.PrintOut FileName:=" " , Range:=wdPrintAllDocument, _

                                                        Item:=wdPrintDocumentContent, Copies:=1, Pages:=" " , _

                                                        PageType:=wdPrintAllPages, Collate:=True, Background:=False, _

                                                        PrintToFile:=False

              Call Wait 'waits for print file to be created

              If i < > 3 Then

                      DDEExecute chan, " [MultiPart]"

              End If

      Next

      DDEPoke chan, " To" , " +44 020 7203 4005, Sam Smith, Equisys PLC"

      DDEExecute chan, " [MultiSend][DDERelease]"

      DDETerminate chan

End Sub

Multiple part fax

'

' SendSingleFax Macro

' Macro created 11 June 2004 by Equisys plc.

'

Public Sub SendSingleFax()

      Dim chan, Address, Contact

      ' Set up DDE control of Zetafax

      chan = DDEInitiate(App:=" Zetafax" , Topic:=" Addressing" )

      DDEExecute Channel:=chan, Command:=" [DDEControl]"

      ' Set Zetafax to the default printer and print the document

      ActivePrinter = " Zetafax Printer"

      ' FilePrint

Application.PrintOut FileName:=" " , Range:=wdPrintAllDocument,

  Item:= wdPrintDocumentContent, Copies:=1, Pages:=" " , _

  PageType:=wdPrintAllPages, Collate:=True, Background:=False, _

  PrintToFile:=False

                  Call Wait 'waits for print file to be created

      ' Address for the Fax taken from an array of data.

      Contact = Array(" +44 20 7203 4005" , " Brian Bull" , " Equisys plc" )     

      ' Add data for the address

      Address = Contact(0) & " , " & Contact(1) & " , " & Contact(2)             

      ' Format data to Address

      ' Set the addressing options

      DDEPoke Channel:=chan, Item:=" TO" , Data:=Address ' Address the fax

      ' Submit the fax and release DDE control

      DDEExecute Channel:=chan, Command:=" [Send][DDERelease]"

      DDETerminate Channel:=chan

End Sub

Wait routine for all types of fax

Private Sub Wait()

      On Error GoTo oops

      Dim pauseDuration As Single

      Dim fileSize As Long

      Dim strSpoolfile As String

Dim tmStart As Double

      ' This line finds the spool path for the Zetafax printers. Do not Change this line.

      strSpoolfile = System.PrivateProfileString(" " , " HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Print\Printers\Zetafax Printer" , " port" )

      Do

              DoEvents

              fileSize = FileLen(strSpoolfile)      ' Returns file length (bytes).

Loop While fileSize = 0

' If you are printing direct to the printer you do not need this pause

' and can remove the next five lines.

      pauseDuration = 2    ' Set duration.

      tmStart = Timer        ' Set start time.

      Do While Timer < tmStart + pauseDuration

              DoEvents              ' Yield to other processes.

      Loop

      Exit Sub

oops:

      If Err.Number = 53 Then

              ' eat " file not found" errors

              Resume Next

      End If

MsgBox Err.Description

        End Sub

Common Problems

This section lists commonly encountered problems and their solutions

• The most common problem is the client trying to send the fax before it has been prepared. This happens when you have forgotten to implement a "Wait" function to wait for the print job to finish
• If you are trying to send a large number of faxes you should stay within the guidelines offered in the "When to use DDE" section above. If you want to increase the number of faxes you can send you can try printing directly to the printer
• If more than 10 seconds elapse between the DDEControl command and the DDESend command the client may time the request out.

References

Zetafax technical notes:

ZTN1032 HOWTO: Using DDE   - similar to this document but for versions prior to 9.

ZTN1057 INFO:  Enabling Zetafax client DDE logging - this document tells you how to enable DDE logging within the Zetafax client.  This is useful when you wish to track bugs.

Last Updated: 15 December 2005 (MS)

First Published: 11 June 2004 (AG/EB)