Using the Fax Driver

From CometWiki

Latest revision as of 09:38, 26 May 2009

The Comet Fax Gateway

The fax gateway allows an Internet Basic program to send faxes via a Class 1, 2, or 2.0 fax/modem. The fax Gateway has been available since Comet2000.

The fax gateway offers a number of advantages to the Comet user. First, it can send text as well as graphics files (PCX, DCX, TIFF, and BMP). It will also accept graphics commands just like most windows printers. It can also send a cover page, including the standard cover pages shipped with Windows and Office. Each faxed page can also include a banner with such fields as date, time, page number, to, from, company, subject, etc. All of these functions are controlled by your Internet Basic program, and thus can be customized at any time.

While a fax is being transmitted, the fax driver provides status information to the controlling Internet Basic program. This helpful feature allows your program to monitor the status of the entire transmission starting with the dialing process and ending with the “fax complete” event. The fax driver also reports any errors that might occur during transmission. As a result, your program can create a fax log file that can be used for inquiry and reporting purposes.

Requirements

Here are the hardware and software requirements and procedures to install the fax gateway:

A Class 1, 2, or 2.0 fax/modem must be installed in your system. 
Run the CometFaxSupport.exe program to install the required support drivers. This program is available in the /download/faxdriver directory. 
Configure a type 7 gateway on your system. 
Configure a Fax Printer on your system. 

Detail

The fax driver is based on a commercial software product named FaxMan Jr., to which Signature Systems has obtained a distribution license. This driver lets an Internet Basic application send faxes using standard class 1, 2, and 2.0 fax/modems.

The Comet Fax Driver offers a major advantage in that it can monitor the status of the fax as it is being sent. This means that you can write a fax application that maintains its own log file, keeping track of completed faxes as well as any errors that might occur during transmission.

The Comet Fax Driver is configured as a type 7 gateway in SYSGEN.

To use the Comet Fax Driver, your program must open the gateway device and send it a series of CONTROL statements, in the same manner as the other Comet gateways. In the case of the fax driver, you first send a "LoadDriver" control to the universal gateway, specifying the name of the fax driver program (FaxDriver.exe). Subsequent controls to the gateway specify the fax file name(s), the fax properties (such as fax number to dial, name of recipient, name of sender, etc.), and fax commands. The fax driver controls are described below.

Before you write a fax application, it's essential that you understand a little bit about fax files. The fax driver can send one kind of file only, a graphics file (technically, a TIFF Group 3 file). This graphics file may contain an unlimited number of pages. In fact, this file may be a composite of multiple original document files, including text files and the following types of graphics files: PCX, DCX, TIFF, and BMP.

So, the question is, "How do original document files get transformed into a graphics file?" The answer lies within the power of the fax driver. One of the fax driver controls says, in essence, "take the following files and convert them into a faxable graphics file." When that step is complete, your program can continue to set the fax properties and send the fax.

With that in mind, here's an overview of how a fax can be created and sent by an Internet Basic program:

Presumably, your program will be faxing user-specific information such as a quote, and invoice, an order confirmation, etc. To accomplish this, your program will need to create a text file and write the text of the fax to that file. There is no limit to the length of this text file.

Once that text file is built, your program will build a "fax file." This is a faxable graphics file created using the "ImportFiles" control. This control tells the fax driver to convert your text file (plus any other text/graphics files that you want to fax) into a faxable graphics file.

Your program then sets a number of fax properties, including the name of the fax file to be sent, the fax/modem's class and port number, the fax number to be dialed, and other optional descriptive fields (to, from, company names, cover page information, etc.).

Next, your program sends the fax using the "SendFax" control.

While the fax is being sent, your program can monitor the status of the fax driver (via the gateway). The fax driver reports each event than happens. For example, the driver reports "Sending page - 10% complete," "Sending page - 20% complete," etc., all the way up to "Sending page - 100% complete." The driver also reports errors that might occur during transmission. If you choose to, you can create a log file to keep track of the success/failure of the faxes that have been sent. The fax driver does not create a log file.

The fax driver does not erase fax files after they have been faxed. Likewise, the original files (text/graphics) are not erased after a fax is sent. Thus, fax file management is completely up to the Internet Basic programmer.

Here's an important note about the fax file (the one created in step 2). If you don't erase the fax file after the fax has been sent, and you use the "ImportFiles" control again specifying the same file name, the fax driver converts your original documents and appends them to the existing fax file. If you don't want this to happen, erase the fax file after it has been sent.

Installation and configuration

Before installing or configuring the fax driver software, make sure that your computer contains a Class 1, 2, or 2.0 fax/modem that is connected to a phone line.

Software installation/configuration steps:

1.Run the CometFaxSupport.exe program. This program installs the required system drivers, and then prompts for and creates the "Comet Fax Support" directory (the default is as a subdirectory of the Comet "Start in" directory). The installation program also adds a printer to your Windows "Printers" folder. The printer is named "Comet Fax." Add this printer to your Comet.Ini file. For example:

  [PRINTERS]
     Printer = LPF, W, N,, Comet Fax,,;

Configure a type 7 gateway:

  [GATEWAYS]
     Gateway = 7,0;

Run the SYSGEN program and regenerate your configuration, then restart Comet.

You are now ready to use the new fax driver.

If you would like to test the fax driver, use the FaxDrv.ibs demo program located in the DMW directory. Please read the comments in the code and modify the required values to match your needs. Before running the demo program, you will also have to create a text file that will be faxed (the demo program does not do this). See the demo program for more information.

Programming overview
Opening the gateway

Your Internet Basic program will need to open the universal gateway. If you know the gateway device name (for example, G00), you can open it as follows:

     OPEN (lun) "G00", EXCP=exception-statement-label

If you don't know the gateway device name, or if your gateway configuration is likely to change over time, we recommend using a routine that scans all configured gateways, looking for the first type 7 gateway in the list. We've included such a routine in the FaxDrv.ibs demo program.

Loading the fax driver

As mentioned above, a type 7 gateway is a universal gateway (i.e., it is not assigned to a particular type of driver). Therefore, your program will need to load the driver you want to use with this application. In this case, you'll want to load the fax driver, which is a program named FaxDriver.exe. The "LoadDriver" control accomplishes this step

The following code segment shows how to load the fax driver by specifying the required parameters (driver class, caption, and driver name) and sending the control to the gateway (which, in this example, is open on logical unit number 1):

     Set MyDriverClass$ ="FaxDriver@5F@Class"          ! Driver class
     Set MyDriverProg$  ="FaxDriver.Exe"               ! Driver name
     Set MyDriverCaption$ = " "                        ! Null (but include at least
                                                       ! one character for compiler)
     Control$ = "LOADDRIVER:"+_                        ! LoadDriver control
                 MyDriverClass$   + ";"+_              ! CustDriver_Class
                 MyDriverCaption$ + ";"+_              ! null
                 MyDriverProg$                         ! FaxDriver.exe
     Result$ = Control(1,Control$,Excp=LoadFailed)     ! Load fax driver

Building the fax file

The "ImportFiles" control builds the fax file. The following code segment shows how to create a fax file named c:\testfax\faxfile1.fmf by converting a text file named c:\testfax\fax1.txt:

     Control$ = "ImportFiles:c:\testfax\faxfile1.fmf;c:\testfax\fax1.txt"
     Result$ = Control(1,Control$)

For more information, see the FaxDrv.ibs demo program and the FaxMan Jr. help file (Faxmanjr.chc on the \Comet Fax Support directory).

Note

Fax driver controls fall intro three categories: Properties, Methods, and Events. Properties establish parameters for the fax, such as the fax number to be dialed, file to be sent, etc., and also return information about the fax/modem itself, such as the fax/modem class and port number. Methods perform a specific action (for example, the "ImportFiles" control is a method).

Events are occurrences of certain actions that are reported by the fax driver when they happen (for example, start time, completion, end time, etc.). As you read the FaxMan Jr. documentation, you will see the fax controls separated into these three categories.

Specifying the fax file to be sent

The "SendFax" control is a property that specifies the fax file(s) to be sent. The following code segment shows how to specify the fax file created above (note the "SetProperty" portion of the control):

     Control$ = "SetProperty:FaxFiles=c:\testfax\faxfile1.fmf"
     Result$ = Control(1,Control$)

For more information, see the FaxDrv.ibs program and the FaxMan Jr. help file.

Determining the class number and port of the fax/modem

Before you can send a fax, you must determine and set the class number and port number. To facilitate this process, we have included a routine in the FaxDrv.ibs demo program that determines how many (if any) fax/modems are installed. If one or more is found, the device class and port number of the first device is determined.

If you are writing a program for repeated use with the same fax/modem, there is no need to keep repeating this time-consuming step. Instead, move this routine to another program, find the fax/modem's Class and Port values, and save them in a place where your fax-sending program can easily retrieve them (such as a control file for your fax applications.

Then, use the following controls to set the fax/modem's properties:

     Result$ = Control(1,"SetProperty:Port=<port number>")
     Result$ = Control(1,"SetProperty:Class=<device class>")

Specifying other fax properties

The fax driver supports several additional properties, only one of which is required to send a fax. The required property is "FaxNumber". This is the number to which the fax should be sent, and is set as follows:

     Result$ = Control(1,"SetProperty:FaxNumber=<fax number>")

For example, to send a fax to Signature Systems, you would write the following code:

     Result$ = Control(1,"SetProperty:FaxNumber=1-808-742-9769")

Here are the other properties that can be set with the "SetProperty: control:

           Property                      Description
           FaxBanner                    User-defined banner string
           FaxComments              Comments to be used when sending the fax
           FaxCompany                Name of the Company to which the fax is being sent
           FaxCoverPage             Cover page to be used when sending a fax
           FaxName                     Name of the fax recipient
           FaxResolution               0=low resolution, 1=high resolution
           FaxSubject                   Subject of the fax
           FaxUserData                A user defined field for fax information
           LocalID                        ID string for this fax/modem (up to 20 characters)
           UserCompany              Name of the Company which is sending the fax
           UserFaxNumber           Fax number of the Company which is sending the fax
           UserName                    Name of the person which is sending the fax
           UserVoiceNumber       Voice number of the person which is sending the fax

Two of these properties warrant some extra explanation. FaxBanner is a line of text that may be added to the top of each fax page sent, and FaxCoverPage is the name of the cover page file to be used when sending a fax. The following shaded area contains information from the FaxMan Jr. help file:

Banner And Coverpage Formatting Characters

Banners: A banner string may consist of any of three parts: a left-justified portion, a center-justified portion, and a right-justified portion. Each part is separated by a vertical bar ('|'). The banner string may be of any length, however, only one line of text will appear at the top of a fax. You may insert format characters into the banner string in order to include some information concerning the fax, see the description of format characters below. If the fax banner is empty then no fax banner will be sent.

The banner string has a limit of 64K, a great deal more than would fit across a single page, and we do not limit the text in any given justification area. Therefore there is the potential that the center-justified portion could overwrite the left-justified portion and the right-justified portion could overwrite the both the left and center-justified portions. The user would not normally be aware of this situation because the banner is printed only on out going faxes.

Format Characters:

The following strings are valid formatting characters for both the Coverpage Comments and the Banner string:

%d = date (dd-mmm-yyyy format, e.g. 03-Feb-1995)
%t = send time (24-hour format, e.g. 6:00pm = 18:00:00)
%p = total # of pages in the fax
%c = current page

Item    Description                 Property Name
%r        Recipient name             FaxName
%y       Recipient company       FaxCompany
%s       Sender's name              UserName
%m      Sender's company        UserCompany
%I        Sender's fax ID            LocalID
%u       Subject of fax               FaxSubject
%f        Fax number                  FaxNumber
%u       Comments                    FaxComments 
%x       Sender's fax #              UserFaxNumber
%h       Sender's voice #           UserVoiceNumber

For example, to make a banner that contains "to, from, and subject" information (left, center, and right-justified, respectively), write the following control:

Result$ = Control(1,"SetProperty:FaxBanner=To:%r|From:%s|Subject: %u)

To include a cover page with your fax, use the FaxCoverPage property to specify the name of the cover page to send. Sample cover pages are shipped with various versions of Windows and Office. These typically include:

confdent.cpe 
fyi.cpe 
generic.cpe 
urgent.cpe 

You can edit these pages, or create new ones, with the Microsoft Cover Page Editor (faxcover.exe), which is included with Microsoft Fax. The fax driver merges the appropriate fax properties into the cover page file, creating a custom cover page.

Thus, to include the generic cover page, you would write the following control:

     Result$ = Control(1,"SetProperty:FaxCoverPage=generic.cpe)

Note: Do not specify a path for the cover page file. The fax driver searches for the cover page in the Windows directory on your system.

Sending the fax

Use the "SendFax" method to send the fax, as follows:

     Result$ = Control(1,"SendFax)

Monitoring the fax driver

During transmission, your Internet Basic program can monitor the fax driver. There are several reasons to do this. First, your program must know when the transmission is done in order to know when to close the gateway (remember, unlike previous fax interfaces in Comet, this fax driver is capable of sending information to the Internet Basic program while the fax is being sent).

Second, if you are creating a fax program that will run in foreground, your program can provide a "progress log" for the end user, showing them each event that occurs during transmission. (Note that your fax program does not have to run in foreground. In fact, it might be more useful for you to create a "fax server" that runs in background.)

Third, when the fax transmission is complete (or if the transmission process ends with an error), your program could create an entry in a fax log file. Such a log file would contain as much information as you deem necessary, such as the fax number that was dialed, the start and end times, the fax file name, and other properties that were set prior to the attempted transmission. You could then build an inquiry/report program to display the contents of your log file.

While it's possible for your program to monitor the fax driver on a continuous basis, it's more sensible to let the fax driver communicate its events to the program as they occur. The fax driver includes a "WaitForEvent" method that causes the Internet Basic program to pause while waiting for a change in the fax driver's status (i.e., an "event"). Here is the syntax of this method:

     Result$ = Control(1,"WaitForEvent:<number of milliseconds>")

For example, here's how to make the Internet Basic program pause for us to 5 seconds:

     Result$ = Control(1,"WaitForEvent:5000")

If there is a change in the fax driver's status sooner than the specified time limit, the program will immediately proceed to the next statement. However, if there is no change (in other words, no event), the program will pause for the specified amount of time, and then proceed to the next statement.

See the FaxDrv.ibs demo program for an example of a "WaitForEvent" loop.

When an event occurs, an event type value is returned in the receiving variable of the CONTROL statement (in other example, this is RESULT$), starting at byte 2. The following values are returned:

         Value          Meaning
           1          EVENT.STATUS
           2          EVENT.NEGOTIATION
           3          EVENT.PAGES
           4          EVENT.STARTTIME
           5          EVENT.ENDTIME
           6          EVENT.COMPLETE
           7          EVENT.RECEIVE.FILENAME
           8          EVENT.TIMEOUT

When a particular event occurs, you program can retrieve further information by using the "GetProperty" control, which is coded as follows:

     Result$ = Control(1,"GetProperty:<property>")

Examples:

When the event type is 1, indicating that an "event status" has occurred, your program can get the "CurrentStatus" property, as follows:

     Result$ = Control(1,"GetProperty:CurrentStatus")

The current status is returned in the receiving variable (RESULT$), starting a byte 2. There are 36 values, including the aforementioned "Sending page - 10% complete," "Sending page - 20% complete," "Sending page - 30% complete," series. They are shown in the FaxDrv.ibs demo program as well as the FaxMan Jr. help file.

When the event type is 6, the fax transmission is complete. At that point, your program can use the "GetProperty" control to retrieve information about the complete fax, such as start time, end time, number of pages sent, etc. See the FaxDrv.ibs program for an example of this.

Closing the fax driver

When the fax transmission is complete, close the fax driver by closing the universal gateway. For example:

     Close (1)

Demonstration Program

The DMW directory contains FaxDrv.ibs which demonstrates the above programming techniques.

GDI Output

The Comet Fax Gateway also supports GDI-style output, so that your faxes may now include lines, geometric shapes, bitmap images, and text in your choice of fonts.

Programming information

The Comet Fax Gateway can fax a GDI-style form by sending the output to the "Comet Fax" printer. This output is captured and written to the fax file, which is then faxed to the recipient. The following control turns on the print capture mode:

     Result$ = CONTROL(lun,"SetProperty:FaxFileStatus=1")

Subsequent printing to the "Comet Fax" printer (e.g., "LPF") is captured and written to the fax file (the "fmf" file).

Thus, your fax application might be structured like this:

Turn on print capture using the above control. 
Build the fax file by printing the form to the "Comet Fax" printer. 
Specify the fax properties, send the fax, and monitor the sending (the traditional fax controls). 

Demonstration Programs

The DMW directory contains two programs that work together to demonstrate how to send a fax using forms printing techniques. The programs are FaxPrint (the source is FaxPrint.IBS) and CForm (the source is CForm.IBS).

The FaxPrint program works in three parts:

Print capture mode is turned on. 
The form is printed by "entering" the CForm program. When running this demo program, CForm will prompt for a printer name.     
Enter the name of the Comet Fax printer (e.g., "LPF") specified in your Comet.Ini file. The output is captured and written to  the fax file. 
Send the resulting fax. Once the end of the print job has been detected, code that should be familiar to you (from the FaxDrv demonstration program) sends the fax. 

Notes:

CForm is a demo program that prints lines, shapes, bitmap images, and text in various fonts (it's the "Hay Time Feed and Grain" invoice for those who are familiar with the DMW sample programs). This program has been modified as follows for purposes of the Comet Fax Driver: it prints a single form and then does an "Exit."

The FaxPrint program is hard-coded to create a fax file named "TextFax.Fmf" in a Comet directory named "FAX." Modifying the following statements in FaxPrint.IBS can easily change either of these:

    Set FaxFileName$ = "TestFax.fmf"
    Set FaxDir$ = "Fax"

The FaxPrint program uses a control file to remember the port and class of the fax device. If the file does not exist or an error occurs reading the file, FaxPrint will use the first available fax device it finds on your system. If a device is found, the port and class are recorded in the control file for future use. The FaxPrint program is hard-coded to create a file named "FAXCTRL," but modifying the following statement can easily change this:

    Set FaxCtrlFile$ = "FaxCtrl"

If you have any questions about this material or the Comet Fax Gateway in general, please