Click above to get retro games delivered to your door ever month!

 Fax Device Functions
 Overview
------------------------------------------------------------------------------

 Background Operation

    Sending a fax requires very little of the computer's power.  Most of the
    time is spent waiting for the modem to send or receive data.  To make
    better use of computer power, Faxual II sends faxes in the background,
    using just the time your program would normally be wasting, idling or
    waiting for keyboard input.

    Faxual II runs the background fax task only when the foreground program
    makes time available.  It will not preempt the foreground program.  But
    some parts of the fax process are time-critical, and cannot be delayed
    more than a few seconds without disrupting fax operation.  This means
    that we must place some restrictions on what the foreground program can
    do while a fax operation is in progress.

    The foreground program should never go more than (about) one second
    without giving up some time to the fax task.  The operations that give
    up time are:

    .   Stopping in an input wait state.  Clipper operations that produce
        wait states include READ, WAIT, ACCEPT, INPUT, ACHOICE(), DBEDIT(),
        and MEMOEDIT().  INKEY() works as a wait state if you give it a
        parameter (i.e. if it actually waits for a key), but not if you call
        it with no parameter.

    .   Calling FaxDriver() will explicitly give up some time to the fax
        task.

    .   Most RIP text or drawing operations, and most other time-consuming
        RIP operations (like loading fonts or bitmaps) also give up time to
        the fax task.

    Operations that are likely to cause problems include:

    .   RUNning or shelling DOS commands or programs.  The fax task can only
        run while your Clipper program is running.

    .   Writing output to a slow local printer.  If your program can write
        more data than the printer's buffer will hold, the program will have
        to stop and wait for the printer to catch up, and the fax task will
        not run during that time.  Writing a page or two to a laser printer
        is usually safe.  Writing to a network printer is almost always
        safe.

    .   Time consuming database operations, like indexing, packing, or
        copying large numbers of records.  You may be able to get around
        this restriction by clever use of FaxDriver().  For example, instead
        of

        COPY TO SOMEDBF

        you could write

        COPY TO SOMEDBF WHILE FaxDriver() .OR. .T.

 Device Modes

    A fax device can be in one of three modes.  To find out which state is
    current, call FaxStatus() to get a device status block, and use StMode()
    on the status block.  The mode will be a numeric value, one of:

    Device modes defined in FAXUAL2.CH
    ----------------------------------------------------------------------
    Value   Constant        Device state
    ----------------------------------------------------------------------
      0     FAX_IDLE        No operation in progress.
      1     FAX_DONE        An operation has completed.
      2     FAX_SEND        Send operation in progress.
    ----------------------------------------------------------------------

    The mode must be FAX_IDLE before you can change any parameters or call
    FaxSend().  When you call FaxSend(), the mode changes to FAX_SEND.  When
    the operation completes (either normally or due to an error), the mode
    becomes FAX_DONE.  At that point you can retrieve the final status of
    the operation.

    When an operation is done, you must reset the device to FAX_IDLE before
    you can change parameters or send another fax.  This is accomplished by
    FaxReset().  FaxReset() can also be used to abort an operation in
    progress, but it will not perform a 'clean' abort.  To cancel an
    operation, making sure the modem is hung up and reset correctly, use
    FaxCancel().

 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
        FaxMinSpeed()   to set the minimum acceptable connection speed
        FaxOptions()    to set modem and device options
        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.