Comet 32 Runtime
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.
Here are the hardware and software requirements and procedures to install the fax gateway:
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:
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.
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.
[PRINTERS] Printer = LPF, W, N,, Comet Fax,,;
[GATEWAYS] Gateway = 7,0;
You are now ready to use the new fax driver.
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.
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
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).
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.
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.
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>")
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:
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:
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.
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:
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.
Use the "SendFax" method to send the fax, as follows:
Result$ = Control(1,"SendFax)
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:
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>")
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 fax transmission is complete, close the fax driver by closing the universal gateway. For example:
The DMW directory contains FaxDrv.ibs which demonstrates the above programming techniques.
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.
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:
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:
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 post them on Signature's Forum: Support.signature.net