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