DDE Programming with FACSys

This document includes the following topics:

Introduction

Step 1: Establishing a DDE Conversation with FACSys

Step 2: Constructing a Fax Event Using DDE

Step 3. Sending a Fax Event Using DDE

Step 4. Terminating the DDE Conversation

Using DDE In Microsoft Applications

Troubleshooting and Examples

Introduction

The FACSys client software can act as a DDE server for any application that has DDE client capabilities. As a result, you can develop a DDE command interface between another application and FACSys. The DDE command interface you develop provides a means of building a fax job at the FACSys client workstation and scheduling that job for faxing automatically. For example, as a means of programmatically creating a list of fax destinations, you might write a macro that accesses information from another database (e.g., an application’s address book). After the destination list is created, your macro may include a file to be faxed to the list, or the macro user might "print a document to fax" from a word-processor.

Steps Required By Your DDE Program

The DDE program you develop must do the following:

1. Establish a DDE conversation with FACSys

2. Construct a fax event

3. Send the fax event

4. Terminate the DDE conversation

Each step is discussed in detail in the sections below.

Back to Top

Step 1: Establishing a DDE Conversation with FACSys

To establish a DDE conversation with FACSys, the FACSys client application must be running at the client workstation.

• For FACSys 4.1 clients, the Fax Monitor must be running at the client workstation.
• For FACSys 4.5 clients, the FACSys Desktop program must be open or running as a background process on the client desktop (i.e., the FACSys Desktop program must be accessible as an icon in the Windows taskbar system tray area).

Use the DDEInitiate command and supply the application name "FACSYS" and the topic name "TRANSMIT" to the FACSys client. For example:

//Open Channels

SystemChanNum = DDEInitate("FACSYS", "SYSTEM")

TransmitChanNum = DDEInitiate("FACSYS", "TRANSMIT")

Back to Top

Step 2: Constructing a Fax Event Using DDE

A DDE client application constructs a fax event by issuing a series of commands to the FACSys DDE server. A DDE client application sends, or "pokes", these commands using the DDEPoke function. DDEPoke supports one item: Send Fax. The Send Fax commands supported by the FACSys DDE server are listed and described below.

Send Fax commands:

• recipient
• attach
• setcoverpage
• resolution
• priority

2.1 Recipient Command

The recipient command is used to specify a fax destination and event details. The command syntax is as follows:

recipient(FaxNumber, Time, Date, Name, Company, Subject, Reserved, BillingCode)

NOTE: The FaxNumber is the only required parameter. If other parameters are not included, you must enter a comma delimiter in their place.

2.1.1 Recipient Command Parameters

• FaxNumber - Required. Fax number of the recipient.
• Time - Optional. The time of day at which the fax should be sent in hh:mm:ss format.
• Date - Optional. The date on which the fax should be sent in mm/dd/yy format.
• Name - Optional. The display name of the recipient.
• Company - Optional. The company name of the recipient.
• Subject - Optional. The subject of the fax.
• Reserved - Optional. This field is not currently supported.
• BillingCode - Optional. The billing code associated with the specified recipient.

2.1.2 Recipient Command Remarks

The Time, Date and Subject parameters are associated with the entire fax event, not just the specified recipient. If these parameters appear in more than one recipient command, the last value specified will be applied to the fax event.

Although most parameters are optional, the relative position within the parameter list must be maintained. For example, the following syntax can be used to specify a fax number and display name without specifying a date and time:

recipient(555-1212,,,John Doe)

If no date and time are specified, the fax event will be scheduled immediately. If only a date or time is specified, the current date or time will be used for the unspecified information.

2.2 Attach Command

The attach command is used to specify the path and name of the file to be attached to the fax. The command syntax is as follows:

attach(FileName)

2.2.1 Attach Command Parameters

• FileName - Required. The fully qualified path name of a file to be included with the current fax event.

The following file types are currently supported by the FACSys DDE server: TIFF, DCX, PCX, BMP, ASCII, MG3, PCL5e, Postscript II and RTF.

2.3 SetCoverPage Command

The SetCoverPage command is used to specify the file name of the fax cover page. The command syntax is as follows:

setcoverpage(FileName)

2.3.1 SetCoverPage Command Parameters

• FileName - Required. The name of the cover page file. This file must be resident in the FACSYS\LOGO directory on the fax server.

Specify only the name, not the path, of the cover page file.

To have the first attachment file interpreted as a cover page message, append the '@' character to the cover page file name. NOTE: The attachment file must be an ASCII text file.

2.4 Resolution Command

The resolution command is used to set the resolution of the outbound fax. The command syntax is as follows:

resolution(ResVal)

2.4.1 Resolution Command Parameters

• ResVal - Desired fax resolution. Supported values are HIGH and LOW.

If this command is not sent, the fax event will default to HIGH resolution.

2.5 Priority Command

The priority command is used to set the priority of the outbound fax. The command syntax is as follows:

priority(PrioVal)

2.5.1 Priority Command Parameters

• PrioVal - Desired fax priority. Supported values are LOW, NORMAL, HIGH and URGENT.

If this command is not sent, the fax event will default to NORMAL priority.

Back to Top

Step 3: Sending a Fax Event Using DDE

When all information is prepared and sent to the FACSys client, the DDE client application can request the FACSys DDE server to execute commands on its behalf. A DDE client executes these commands using the DDEExecute function. The execute commands supported by the FACSys DDE server are listed and described below.

Execute commands:

• sendnow
• cancel
• FileHold, FileHoldOn, FileHoldOff

3.1 SendNow Command

The sendnow command initiates the send event. The command syntax is as follows:

SendNow

3.1.1 SendNow Command Remarks

This command causes the FACSys DDE server to schedule the current fax event. If the current fax event does not contain at least one recipient and one attachment, the FACSys Schedule Fax dialog will be invoked.

3.2 Cancel Command

The cancel command clears any information poked previously by the DDEPoke command. The command syntax is as follows:

Cancel

3.2.1 Cancel Command Remarks

This command causes the FACSys DDE server to clear all information associated with the current fax event.

3.3 FileHold(On|Off) Commands

The filehold commands are used to set the state of the FACSys client's "hold files" option. The syntax for each command is as follows:

• FileHold
• FileHoldOn
• FileHoldOff

3.3.1 FileHold(On|Off) Commands Remarks

These commands allow a DDE client application to programmatically control the hold state of the FACSys DDE server. While on hold, files printed to the FACSys printer will be retained as part of the current fax event.

• FileHold will toggle the current hold state.
• FileHoldOn will force the FACSys DDE server to a hold state.
• FileHoldOff will force the FACSys DDE server to release the current fax event.

NOTE: The FileHold commands must be issued before you send information to the FACSys client using the DDEPoke function. Use FileHoldOn, then send the fax data, then use FileHoldOff. For example:

//Hold the DDE server

DDEExecute(TransmitChanNum, "FileHoldOn")

DDEPoke(TransmitChanNum, <<File, recipient info>>)

...

DDEExecute(TransmitChanNum, "FileHoldOff")

//Executing "FileHoldOff" will send the fax...

NOTE: Once a connection is established and you have sent data, use the DDERequest Status function to monitor the status of the conversation as well as to resolve any spooling and timing issues. The Status function has no parameters, and will return either the value READY or BUSY depending on the state of the FACSys client. A new event should not be scheduled until a READY status has been returned by the FACSys client. For example:

//Open Channels

SystemChanNum = DDEInitate("FACSYS", "SYSTEM")

TransmitChanNum = DDEInitiate("FACSYS", "TRANSMIT")

......

//Loop until monitoring facilities are ready

While (DDERequest(SystemChanNum, "STATUS") != READY) Do

End

Back to Top

Step 4. Terminating the DDE Conversation

DDE client applications should terminate their conversations with the FACSys DDE server using the DDETerminate function.

Back to Top

Using DDE In Microsoft Applications

Microsoft Excel, Microsoft Word for Windows, and Microsoft Visual Basic all support DDE and provide statements in their macro languages that allow users to write macros that perform DDE. If you have written macros in one of these Microsoft applications, you may find the following table helpful. The table compares the DDE statements and functions in the Microsoft Excel and Microsoft Word macro languages with the equivalent DDE properties and methods in Visual Basic.

Back to Top

Troubleshooting and Examples

Before you call for technical support, use the utility DDETEST.EXE to verify communication with your FACSys server. DDETEST helps you determine whether or not there is a problem with the connection to your server. If your DDE program is not working but the DDETEST program does work successfully, then there is a problem in your DDE code. If the DDETEST program cannot communicate with your fax server, then there is a problem with the connection. The DDETEST.ZIP file is available from the emFAST FTP site at FTP.FACSYS.COM in the directory \UTILS.

There are two DDE program examples also posted on our FTP site in the directory FTP.FACSYS.COM\UTILS:

• MAILMRG.TXT - uses WordBasic as the macro language for mailmerging with Office95
• MM_97.TXT - uses VBA as the macro language for mailmerging with Office97

Back to Top