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:

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):

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):

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.

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:

PropertyDescription

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

ItemDescriptionProperty 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:

ValueMeaning

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:

Demonstration Program

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 post them on Signature's Forum:
Support.signature.net