HOWTO: Using DDE

ZTN1032

ID: ZTN1032

This Zetafax technical note applies to:

• Zetafax 5.5 client and later

Summary

Addressing information can be passed across from a Windows application to the Zetafax client using Dynamic Data Exchange (DDE), prior to printing the document. The full range of options is available with the API add-on, but there is limited support without it.

Applications such as word processors may communicate with the Zetafax client directly using DDE commands.  Provided adequate details have first been given using the DDE commands, when a document is "printed" using either of the Zetafax printer drivers no dialog boxes will be displayed and the fax or faxes will be submitted to the fax server automatically.

This technical note includes three examples that may be used without the API upgrade.

More information

Before issuing any addressing commands, a DDE conversation must be established between the application and the Zetafax client program. The name of the DDE server is "Zetafax", and the topic for the purposes of addressing faxes is "Addressing".

The Zetafax client program should be put under the control of DDE by issuing a DDEControl DDE Execute call.

Addressing commands can then be issued using DDE Poke calls. Details of the commands which may be used are given below.

A message file should be created by printing to the Zetafax printer driver. Alternatively an ASCII file, or a suitable Epson or TIFF file renamed "ZETAFAX.SPL" may be copied to the spool file location used by the Zetafax client program typically either %windir% or the directory given by the TEMP/TMP environment variable (e.g. C:\TEMP\ or %windir%\TEMP\)

The message can be submitted to the Zetafax server for sending with a Send DDE Execute call, or for preview with a Preview DDE Execute call.

Further messages can be submitted by specifying a new addressee, organization, and fax number, creating a new message file, and then issuing a Send or Preview DDE Execute call. Note that each of the addressing settings, such as the choice of letterhead, will remain unchanged between messages until the appropriate DDE Poke call is made to alter it. If these settings need to be reset to their default values between messages, the Zetafax client program should be released from DDE control with a DDERelease DDE Execute call and then put back under DDE control with a DDEControl DDE Execute call.

After submitting the message or messages the Zetafax client program should be released from the control of DDE by issuing a DDERelease DDE Execute call.

The DDE conversation should finally be terminated properly.

The following WM_DDE_EXECUTE commands may be issued using the "Addressing" topic:

The following table lists the items that may be poked (WM_DDE_POKE) using the "Addressing" topic whilst the Zetafax client program is under DDE control on all Zetafax configurations:

For a description of each command and its parameters see the Zetafax software guide page 466 'Embedded addressing commands',

With an API license the following additional items may be poked:

For a full description of each command and its parameters see the API manual shipped as part of the API add-on.

Example

CODE LISTING

Option Explicit

Sub Wait(PauseTime)

'This routine waits for PauseTime seconds.

      Dim Start

      Start = Timer    ' Set start time.

      Do While Timer < Start + PauseTime

              DoEvents      ' Yield to other processes.

      Loop

End Sub

Sub Size()

'This routine waits for the spool file size to change

      Dim Spool_file_Size, Spoolfile

      Spoolfile = System.PrivateProfileString ("", "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Print\Printers\Zetafax FaxMerge Printer", "port") ' Get Variable for the Spoolfile on any system

      Spool_file_Size = FileLen (Spoolfile)      ' Returns file length (bytes).

      Do While Spool_file_Size = 0

              DoEvents

              Spool_file_Size = FileLen (Spoolfile)      ' Returns file length (bytes).

      Loop

End Sub

Sub Send_Fax()

'

' Send _Fax Macro

'

' This macro sends the current active document as a fax. It uses

' DDE to communicate with the Zetafax client.

'

      Dim chan                                              'Channel for DDE link

      Dim oldActivePrinter                      'Store current active printer

      On Error GoTo Send_Fax_Error

      'Set up DDE control of Zetafax

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

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

      'Set Zetafax as the default printer

      oldActivePrinter = ActivePrinter

      ActivePrinter = "Zetafax Printer"

      'Print the document

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

      wdPrintDocumentContent, Copies:=1, Pages:="", PageType:=wdPrintAllPages, _

      Collate:=True, Background:=False, PrintToFile:=False

      Call Wait(10)            'waits for spool file to be created

      Call Size                    'waits for spool file to close

      'Set the addressing options

      DDEPoke Channel:=chan, Item:="TO", Data:="020 7123 4567, Sam Smith, Smith and Sons"

      'Submit the fax and release DDE control

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

      'Tidy up

      DDETerminate Channel:=chan

      'Reset ActivePrinter

      ActivePrinter = oldActivePrinter

Send_Fax_Exit :

      Exit Sub

Send_Fax_Error :

      MsgBox "Error: (" & Err.Number & ") " & Err.Description

      Resume Send_Fax_Exit

End Sub

Microsoft Excel

In this example the addressing information will come from cells B1, B2 and B3 for the fax number, recipient and organisation respectively, but the printer spool path is hard coded.

Note that to run the macro you must have the Zetafax client program running.

The following code listing contains the function Send_Fax, which is called when the 'Send' button is depressed.

CODE LISTING

Option Explicit

Sub Wait(PauseTime)

'This routine waits for PauseTime seconds.

      Dim Start

      Start = Timer    ' Set start time.

      Do While Timer < Start + PauseTime

              DoEvents      ' Yield to other processes.

      Loop

End Sub

Sub Size()

'This routine waits for the spool file size to change

      Dim Spool_file_Size, Spoolfile

      Spoolfile = "c:\temp\zetafax.spl" 'Set Spoolfile to the printer spool path

      Spool_file_Size = FileLen (Spoolfile)      ' Returns file length (bytes).

      Do While Spool_file_Size = 0

              DoEvents

              Spool_file_Size = FileLen (Spoolfile)      ' Returns file length (bytes).

      Loop

End Sub

Sub send_fax()

'

' Send _Fax Macro

'

' This macro sends the current worksheet as a fax. It uses

' DDE to communicate with the Zetafax client.

'

      Dim chan                                              'Channel for DDE link

      Dim oldActivePrinter                      'Store current active printer

      On Error GoTo Send_Fax_Error

      'Set up DDE control of Zetafax

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

      DDEExecute chan, "[DDEControl]"

      'Save current default printer

      oldActivePrinter = Application.ActivePrinter

      'Print the worksheet to Zetafax Printer

      Application.Worksheets.PrintOut ActivePrinter:="Zetafax Printer"

      Call Wait(10)            'waits for spool file to be created

      Call Size                    'waits for spool file to close

      'Set the addressing options reading from the worksheet

      DDEPoke chan, "FAX", Me.Range ("B1")

      DDEPoke chan, "NAME", Me.Range ("B2")

      DDEPoke chan, "ORGANISATION", Me.Range ("B3")

      'Submit the fax and release DDE control

      DDEExecute chan, "[Send][DDERelease]"

      'Tidy up

      DDETerminate chan

      'Reset ActivePrinter

      Application.ActivePrinter = oldActivePrinter

Send_Fax_Exit :

      Exit Sub

Send_Fax_Error :

      MsgBox "Error: (" & Err.Number & ") " & Err.Description

      Resume Send_Fax_Exit

End Sub

References

For additional information on automation of faxes, please see the following Zetafax technical notes:

ZTN1011-HOWTO Using Embedded addressing

ZTN1013-HOWTO Using ZSUBMIT

ZTN1066-HOWTO Using the Zetafax API functions

ZTN1068-HOWTO Using the Zetafax API from Visual Basic

Last updated 11th May 2011 (GC/SV/MW)