Faxual II

Faxual II

Faxual II gives Clipper 5.x programs fax capability using any Class 1, Class 2 or Class 2.0 fax modem.

Faxes can contain your text in almost any font at any size and as many PCX or BMP graphics as you can fit on the page.

Faxual II is fully compatible with ExoSpace and Blinker in real, dual and extended mode and can be almost completely overlaid using Blinker and WarpLink. Memory requirements in the root are under 2K.

Best of all, Faxual II operates in the background without interfering with the program in the foreground.

Download Faxual II Demo

General Library Functions

F2ErrorMessage() Convert error code to message

F2Error() Error code from last operation

Fax Device Functions

The fax device is the software equivalent of a fax machine. It is responsible for sending faxes, and reporting their status.

Sending a Fax

Sending a fax involves the following steps (some are optional):

Create one or more fax files to send. Since you can send several files in a fax job, you may want to put a cover page in one file and text in another, or put together a longer fax out of multiple short documents.

Configure the fax device. (This only needs to be done once, before sending the first fax.) Every program should at least call these two functions:

FaxLocalId() to set the local ID (the phone number in the page header)

FaxPort() to connect the fax device to a serial port

These functions are often useful:

FaxCDWait() to set carrier detect wait time

FaxHeader() to change the page header

FaxInitString() to set the modem initialization string

FaxRetries() to set the number of retries on a busy signal

FaxRetryWait() to set the time between retries

FaxSpeed() to change the serial port speed

Open the serial port using SerOpen(). You can open and close the port for each fax, or open it at the beginning and leave it open throughout the program.

Call FaxSend(). After the fax driver checks that the fax device is available and all of the files are valid, FaxSend() returns and fax transmission begins in the background.

Wait for the fax to finish. During this time, your program can do other work, or simply wait for the fax driver to finish. It can check the status of the outgoing fax using FaxStatus(), or simply ignore it until it has another fax to send.

Check the completion status. Once FaxStatus() reports that the fax job is finished, you can find out if it succeeded (or why it failed) with StError(). You can get other statistics at this time, like the time spent online (StConTime()), or the number of pages sent (StJPagesDone()).

Reset the fax device. This makes it ready to accept another fax job. (It also clears out the last job's completion status.)

If you want, you can close the serial port now. You can also leave it open in readiness for the next job.

FaxCancel() Cancel current operation

FaxDriver() Give fax driver a time slice

FaxModemType() Get/set modem type

FaxOptions() Get/set device options

FaxReset() Reset device

FaxSend() Send a fax

FaxStatus() Get fax device status

Fax Device Status Functions

Because fax transmission happens in the background, checking the status at a given time can be difficult. You might ask for the name of the current file at one moment, and the size of the current file the next, and get the wrong answer because one file was finished and another started between the two calls. To avoid these problems, we check device status by means of a "snapshot" that contains all of the status at a particular instant. You can get particular pieces of information out of a snapshot using these status query functions.

StConTime() Get connect time

StDate() Get fax date

StError() Get error code

StFByteCount() Get file byte count

StFBytesDone() Get file bytes done

StFileNumber() Get file number

StFilename() Get file name

StFPageCount() Get file page count

StFPageNumber() Get file page number

StFPagesDone() Get file pages done

StJByteCount() Get job byte count

StJBytesDone() Get job bytes done

StJFileCount() Get job file count

StJFilesDone() Get job files done

StJPageCount() Get job page count

StJPageNumber() Get job page number

StJPagesDone() Get job pages done

StMode() Get operating mode

StPByteCount() Get page byte count

StPBytesDone() Get page bytes done

StPhase() Get operation phase

StPhaseTime() Get time in phase

StRemoteId() Get remote ID

StSpeed() Get connection speed

StTime() Get fax time

StTotTime() Get job total time

Serial I/O Functions

Faxual II can use either its own built-in serial I/O functions, or the Telepathy serial communications library, to communicate with a fax modem. The functions described in this section are available in either case. If you use the built-in serial I/O layer, these functions call that layer; if you use Telepathy, they call the appropriate functions in Telepathy instead.

In normal use, the only functions from this group you need to call are SerOpen(), to open a serial port before using it to send faxes, and SerClose(), to close the port when you are done with it. You may also need SerSetup() to use serial ports with nonstandard addresses or IRQ numbers.

SerClose() Close serial port

SerFormat() Get/set serial data format

SerHandshake() Get/set handshaking

SerOpen() Open serial port

SerReceive() Receive data

SerSend() Send data

SerSetup() Configure serial port

SerSpeed() Get/set serial port speed

Fax File RIP Functions

RIP stands for Raster Image Processor. A RIP is the processor that runs a printer. The Faxual II RIP performs the same function. It is a software RIP that produces fax files.

To create a fax file, first initialize the RIP with RipBegin(). Then draw text and graphics on the page with other RIP functions. When you are finished with a page, call RipEject() to write the page to the file and start a new page. When the file is complete, call RipEnd() to close the file.

The RIP lets you draw on the page in any order, like a laser printer. You do not have to work from top to bottom, or left to right.

RipBegin() Create a fax

RipCJust() Center a line of text (X/Y)

RipClipLimit() Get/set clipping limit

RipClipRect() Set clipping rectangle

RipCol() Get/set current column

RipColUnit() Get/set column unit

RipCurX() Get/set current X position

RipCurY() Get/set current Y position

RipCutoff() Get length of page used

RipDrawBitmap() Draw bitmap

RipDrawRect() Draw rectangle outline

RipEject() End of page

RipEnd() End of fax

RipFillRect() Fill rectangle with gray

RipFont() Get/set current font

RipLength() Get page length

RipLJust() Left-justify a line of text (X/Y)

RipMoveRel() Move current point relative (X/Y)

RipMoveTo() Move current point absolute (X/Y)

RipOrigin() Set coordinate origin

RipPos() Move current point (R/C)

RipRCCJust() Center a line of text (R/C)

RipRCLJust() Left-justify a line of text (R/C)

RipRCRJust() Right-justify a line of text (R/C)

RipRCUnits() Set row/column units

RipRJust() Right-justify a line of text (X/Y)

RipResolution() Get page resolution

RipRow() Get/set current row

RipRowUnit() Get/set row unit

RipTextOp() Get/set text operator

RipTextSize() Get text size

RipUnit() Get/set X/Y unit

RipWidth() Get page width

RipWrite() Write text at current position

RipXOrigin() Get/set X origin

RipYOrigin() Get/set Y origin

Font Functions

Font Files

Faxes are basically graphics. Writing text onto a fax page really means drawing pictures of the characters that make up the text. The pictures come from a font file.

Some font files are supplied with Faxual II.

You can create others from Windows scalable fonts using the conversion program included with Faxual II.

Font Attributes

A font file contains, in addition to pictures of characters, a variety of information about the font. The attributes include:

FontCharSet() Get character set

FontFamilyName() Get font family name

FontFullName() Get font full name

FontIsBold() Get bold flag

FontIsItalic() Get italic flag

FontPointSize() Get font point size

FontResolution() Get font resolution

Font Measurements

These functions measure the heights of different parts of a font. They are used to figure out how to space text vertically on the page.

FontAscent() Get character ascent

FontAveWidth() Get average character width

FontDescent() Get character descent

FontHeight() Get character height

FontLineSpacing() Get interline spacing

FontMaxWidth() Get maximum character width

Ascent is the maximum height of the font above the baseline. This is similar to 'ascender height' in typography, but includes space for accents and extra-tall symbols. (Ascender height is usually the height of the tallest letter, and does not include space for accents or symbols.)

Descent is the maximum distance the font extends below the baseline. This is similar to 'descender height' in typography.

Font height is the sum of the ascent and descent. If you space lines of text this distance apart, descenders on one line may just touch ascenders on the next, but they will never overlap. (Type set this way is called 'set solid'.)

Line spacing is the recommended distance between two lines of text. In most fonts it will be larger than the font height to allow some blank space between lines. A few fonts are intended to be set solid, and the line spacing will be the same as the height.

Bitmap Functions

BmCount() Get number of bitmaps loaded

BmHandle() Get loaded bitmap handle

BmLength() Get bitmap length

BmLoadPcx() Load a PCX graphic file

BmLoadBMP() Load a Windows BMP graphic file

BmLoadPcx() loads a PCX graphic file into memory. The file is stored in memory as a bitmap identified by a handle. The handle can be passed to functions like BmWidth() and BmLength() to get information about the bitmap, and it can be passed to RipDrawBitmap() to draw the bitmap on the current page. When you are finished with the bitmap, you should use BmUnload() to remove it from memory.

Files loaded by BmLoadPcx() must be monochrome (black and white) PCX bitmap files. The largest bitmap that can be loaded is about 8M pixels, or 1M bytes of data (but PCX files are stored compressed, so the size of the file is not an accurate measure).

BmWidth() Get bitmap width

BmUnload() Unload a bitmap

Download Faxual II Demo