Faximum ELS/PLUS Reference Manual

for SCO OpenServer 5 - Release 2.1 - HTML Edition - Draft 1

Introduction

This architecture makes the API available to any program that can create an ASCII file and start a UNIX process, regardless of the language used (BASIC, C, COBOL, Fourth-Generation Language, shell, etc.). It is also possible to arrange for a compiled or shell program to be automatically invoked when a fax is received.

This document is a tutorial guide to the Faximum API. For specific details on the transmission API, please refer to the manual pages for the fxm, sendfax and submitfax programs in Appendix A. For reception, please refer to the discussion of the dispatch and action databases in Chapter 2.

In addition to the mechanisms described in this section, Faximum also supports a Line Printer Interface which allows programmers to include the routing information (fax number etc.) within a printer stream that is sent to the UNIX/XENIX line printer spooler. This interface will intercept the print stream and automatically pass it to Faximum for transmission. Use of this mechanism enables programmers to send faxes from within their applications without having to use the Faximum API directly. For more information, see Appendix F.

Note that earlier versions of Faximum described an API called transmitfax. While this utility will continue to be supported in future release at least until the end of 1994, the use of the newer submitfax utility is strongly recommended instead.

Overview

The two transmission APIs operate in the same general manner: an application program (compiled or shell) generates a file that describes the request and then a program is invoked (by using either the shell or one of the process creation system calls such as system or exec) to process the request file.

The two transmission APIs differ in their level of abstraction (detail). One, the submitfax interface, is a high-level API that can: look up entries in a person's dialling directory; format a cover sheet; perform intelligent dialling and least-cost routing processing; and handle references to entries in the style and class of service databases. The other, the sendfax interface, is a low-level API that takes a list of files, converts them to TIFF format (if not already in that format), and arranges them to be sent to a specified telephone number.

In addition to these primary interfaces (submitfax and sendfax), there is a simple command line interface called fxm. Fxm enables the key parameters for a fax transmission to be specified on the command line (for example:
fxm "1 604 926 8182" file.ps).

The fxm utility is a shell program that produces a submitfax control fle (as illustrated in Figure 109 above). For more information on fxm, see the manual page in Appendix A.

The Transmission APIs

Briefly, the submitfax interface permits the programmer to reference the dialling, class of service, and style databases. As a result submitfax will look up phone numbers (and determine if the number is local or long distance), automatically determine the best (i.e. cheapest) time to call, and prepare the cover sheet. It will also reference company and people databases to resolve requests to transmit a fax to an entire database.

In contrast, the sendfax interface requires the programmer specify everything: the phone number (as it is to be dialled), the time of day to send the fax, and the list of files to send (any cover sheets must already have been prepared).

Submitfax processes the control file, performing all the database enquiries necessary to specify the fax fully, creating and formatting the cover sheet, and performing the least-cost routing and intelligent dialling computations to determine exactly what digits to dial and when. This information is then put into another file and sendfax is called.

Sendfax then takes the information from the file, arranges to convert all of the files (if necessary) into fax (i.e. TIFF) format, runs the preview program on the converted files (if requested), sends the converted files to the printer (if requested), and passes the files to the fax transmission spooler/scheduler faxsched.

At that point faxsched (not illustrated) will: place the files into the appropriate spool directory; determine the appropriate time to send the fax; and invoke faxcico (not illustrated) to send the fax at that time.

Faximum Software offers an API product for companies that wish to incorporate fax functionality into their product. This product includes all of the software necessary to implement (and integrate) the sendfax functionality with their product. The cost of the API product is significantly lower than that for the entire Faximum PLUS software package.

The Reception API

The receive API is very simple. The system manager can arrange for any program to be executed upon arrival of a fax. The command line arguments to that program may contain the name of the TIFF file that contains the received fax images as well as the details of the reception (such as time received, number of pages, TSI of transmitting fax machine, etc.). This is described in detail in "The Action Database" on page 25.

For Faximum ELS systems, a shell script (/usr/fax/lib/dispatch.sh) is used to handle received faxes. This script contains detailed comments describing its operation and may be edited to perform different or addition functions with received faxes.

The submitfax API

The command file is specified in detail in the manual page for submitfax (Appendix A). The following provides some examples of command files.

Submitfax Example

This example illustrates a fax request to be sent to a single destination (the blank lines have been added for readability and may be omitted). The order of the various parameters within the file is not significant.

dest_name1 = "Jane Doe"
dest_title1 = "Programmer"
dest_dept1 = "MIS"
dest_company1 = "ACME Concrete"

dest_fax1 = "1 604 926 8182"
dest_time1 = "next friday 6pm"
dest_class1 = "urgent"
dest_account1 = "overhead"

from_name = "John Doe"
from_title = "Project Manager"
from_dept = "Software Engineering"

subject = "This is a test fax"
messagefile = /tmp/message
style = "company standard"

preview = No
notify = No
print = Cover
printer = "laser printer"

file_name1 = "/tmp/image.tif"
file_type1 = "TIFF File"
file_style1 = ""

file_name2 = "/tmp/file"
file_type2 = "ASCII File"
file_style2 = "Company Letterhead"
Let us examine this command file in detail.

dest_name1 = "Jane Doe"
dest_title1 = "Programmer"
dest_dept1 = "MIS"
dest_company1 = "ACME Concrete"
This part of the submitfax control file provides the information about the first (and in this example, only) destination that is to be placed on the cover sheet (assuming that a cover sheet is to be generated).

dest_fax1 = "1 604 926 8182"
dest_time1 = "next friday 6pm"
dest_class1 = "urgent"
dest_account1 = "overhead"
This specifies for the first (and only) destination: (a) the fax number, (b) the earliest time this fax is to be sent (it may be further delayed if the class parameter specifies that a cheaper evening telephone rate be used), (c) the class of service for this destination, and (d) the account. More information on the affect of these parameters may be found in Chapter 2.

from_name = "John Doe"
from_title = "Project Manager"
from_dept = "Software Engineering"
This information is placed on the cover sheet to identify the sender.

subject = "This is a test fax"
messagefile = /tmp/message
style = "company standard"
The subject parameter provides a subject line for the cover sheet; the messagefile specifies the name of an ascii text file containing the message to be placed on the covrsheet (you may also use the parameter message to specify a short message directly); and the style parameter controls the appearance of the fax (see Chapter 2 for more information on styles).

preview = No
notify = No
print = Cover
printer = "laser printer"
This next part indicates: whether the fax is to be previewed prior to transmission; whether e-mail is to be sent upon successful transmission of the fax; whether a copy of the fax is to be sent to the printer (in this case only the cover sheet); and the name of the printer (the name of the entry in the printer database) that is to be used.

Note that previewing the fax will only work if the program was invoked from the console. When a fax is previewed, the console is taken over by the previewer and switched to graphics mode. Needless to say this may have catastrophic effects if the user on the console is not expecting to preview a fax (i.e., if the request was submitted in the background).

file_name1 = "/tmp/image.tif"
file_type1 = "TIFF File"
file_style1 = ""

file_name2 = "/tmp/file"
file_type2 = "ASCII File"
file_style2 = "Company Letterhead"
The last part specifies the attachments to the fax. The file name can be a relative or absolute path name. The permitted values for the other options are detailed in the manual page for submitfax in Appendix A.

The sendfax API

The command file is specified in detail in the manual page for sendfax (Appendix A). The following provides an example of a sendfax command file.

Sendfax Example

This example illustrates a fax request to be sent to a single destination (the blank lines have been added for readability and may be omitted).

file
cover /tmp/cover ascii delete
file1 /tmp/image.tif tiff
file2 /tmp/file "ps -h -s 14"
end

fax 1.604.926.8182
notify=yes
account-number="<999-999> <Jane Doe> <ACME Concrete>"
tsi=""
tsia=""
banner="sent by Faximum (FAX for UNIX) %c Page $p of $t"
priority=50
retry-limit=10
retry-time=5
device=fax-line-1:9268182
alternate-device=fax-line-1:5551212
alternate-count=5
time-to-send = "0000-2400 0000-2400 0000-2400"
data-file1=cover
data-file2=file1
data-file3=file2
end
The first section lists all of the files that are to be sent, the conversion program to run on the file to produce the image file, and an optional flag indicating the file is to be deleted after it has been copied to the spool directory.

The next section lists all of the parameters associated with the actual transmission. These parameters are described in detail in the manual page for sendfax in Appendix A.

How Faximum Uses the API

Note that although Faximum itself continues to use transmitfax, users wishing to access the high-level API are strongly recommended to use submitfax instead of transmitfax.

Summary

For more information on the details of each API please refer to the appropriate manual pages in Appendix A.