Go to the first, previous, next, last section, table of contents.

Using qfax

qfax Overview

The qfax program transmits or receives G3 format (QFAX) files.

The qfax program supports many options, you can force Class 2.0 or Class 2 mode from the command line. This option applies to all examples, but is not repeated below.

ex qfax;'[-2] [-2.0] etc
-2
forces Class 2 mode.
-2.0
forces Class 2.0 mode.

Running qfax send

ex qfax;'[-i ini] [-l logfile] [-v] [-x] [-eN] [-bN]
             [-s phone file | -S phone [file] | -z phone file'
-v
displays progress/debug information on the console (stderr device)
-l
defines a log file for process/debug info.
-x
suppresses the c68 `Any key to exit' message
-i
defines additional Hayes commands to be sent before dialling. (appended to the INI string in the `qfax_dat', so if this defines a command starting AT, you don't need another AT here).
-e
qfax emits a status code when it terminates. If the transfer was successful, this will be 0, and on error, ERR_IU, ERR_FE, ERR_TE, ERR_BP or ERR_NF. You can use the -e option to change the error result code. For example, if you were invoking qfax from a QLIB program, you might want it to always return 0, regardless of status; in this case -e 0.
-b
defines a maximum MODEM value for sending. If your respondent is using high speed modem on hardware that cannot cope, this will provide a "one-off" speed limit.
-s
followed by phone number to dial. In a valid `Hayes' ATD format or NAME or ALIAS from QFAX_PHONE.
-S
followed by phone number to POLL. In a valid `Hayes' ATD format or NAME or ALIAS from QFAX_PHONE.
-z
followed by phone number to dial. In a valid `Hayes' ATD format or NAME or ALIAS from QFAX_PHONE. Uses stack supplied channels:

ex qfax,#serial_channel,#dontcare,#info;'-z etc'

file file to send to the phone number.

for example

ex qfax;'-v -l ram2_sfax_log -s 010-968-699407 ram2_jh_fax'
    (Send jh a fax, log information to screen and to ram2_sfax_log)

    ex qfax;'-i M1 -v -s graham  ram2_Graham_fax'

You can have up to 30 `-i' parameters, these are sent after the default qfax initialisation, so you can over-ride the defaults.

Caution: The -s TelNo File or -S TelNo [File] must be the last parameter to this command. The -s and -S options are mutually exclusive.

Polling (requests)

The -S version of the qfax command allows you to poll a remote machine that supports polling. In this case you make the initial connection (and pay for the call), and you receive the fax. This command requires a phone number (or alias) and optionally a file name; if you supply a file name, qfax will send your file before receiving the polled fax.

ALIAS and qfax

qfax send supports ALIAS. Given a suitable ALIAS or NAME in `qfax_phone', and QFAXINI = -v -l ram2_sfax_log, you could do the first example as:

ex qfax;'-s jh ram2_jh_fax'

qfax receive

qfax can receive faxes in a number of modes

In each case, qfax will create a file for each received page using either a given pattern (-r option only) or using a default pattern. The default pattern is:

  1. the root for inbound fax is described by the INDIR parameter in the `qfax_dat' file.
  2. A subdirectory is created from the caller TSI (essentially the caller's phone number). qfax removes any non-numeric characters to create the directory. If you have an NAME defined for the TSI, the NAME is used for the directory name.
  3. qfax creates a sequential sequence number for the file (and a file `seq_dat' to store sequence numbers). The sequence number is a zero filled five digit number. The fax file suffix (section Fax file Suffix) is appended.

INDIR = ram1_infax_

and I sent you a fax, with my ID setting as +968-699407, it
should be received as:

ram1_infax_968699407_00000_fax

dir RAM1_infax_968699407_
gives the faxes received from +968-699407

Two subsequent faxes would be received as:

ram1_infax_968699407_00001_fax
ram1_infax_968699407_00002_fax

With a suitable PHONEBOOK NAME, these files may be received as

ram1_infax_jonathan_00001_fax
ram1_infax_jonathan_00002_fax

A log file is maintained for sent and received faxes, giving caller number, pages, time, baud rate, resolution etc.

qfax can receive in a number of modes.

Manual receive

Answer fax after manual pickup of phone. This would be used when you have a normal voice line shared with your fax modem. You pick up the phone, hear a fax tone and then start qfax in this mode. When you hear qfax negotiating with the remote modem, put down the handset.

Caution you may need to invoke qfax from a ram disk to avoid disk I/O related problems on low end SMS/QDOS systems.

ex qfax;'[-p] [-v] [-x] [-l logfile] [-i ini] [-e N] [-P poll] -R'
ex qfax;'[-v] [-x] [-l logfile] [-i ini] [-e N] [-P poll] -r pattern'

          -v, -l, -x, -i, -e function as for send
-R
receives using qfax file naming conventions.
-r
pattern receives to `pattern_001', `pattern_002' etc
-p
Print the fax on completion (after any move if VIA is defined) You must have defined PRINT = in `qfax_dat' and use -p to print.
-P
defines the name of a fax file that you will transmit when polled.

Automatic Answer

Let the modem answer the phone after a given number of rings. qfax uses its internal file naming convention. qfax can either exit after a single fax, or continue to answer and receive until you RJOB it, or let qfax ask you want you want to do.

ex qfax;'[-p] [-v] [-x] [-l logfile] [-i ini] [-e N] [-P poll] -w 2'
ex qfax;'[-p] [-v] [-x] [-l logfile] [-i ini] [-e N] [-P poll] -W 3'
ex qfax;'[-p] [-v] [-x] [-l logfile] [-i ini] [-e N] [-P poll] -m 3'

where -v, -l, -x, -i, -e, -P function as above
-p
Print the fax on completion (after any move if VIA is defined). You must have defined `PRINT =' in `qfax_dat' and use `-p' to print.
-w N
answers after N rings (2 in the above example). Program terminates after receiving.
-W N
answers after N rings (3 above), after receiving, the program waits for another call.
-m N
answers after N rings (3 above), after receiving, the program waits for another call. You are asked if you want to answer as fax or voice. This is described below as `Monitor' mode.

Shared

In this mode qfax assumes that another program has answered the phone and issued a modem `ATA' command to go online. This parent program has then received a `+FCON' (Class Two FAX connect) message and forked (i.e. invoked using the equivalent of EX/EW) the qfax program. qfax may then be invoked in one of two modes.

-g
When qfax is invoked -g. it assumes that the parent program has closed the serial port. qfax will open the serial port, perform fax specific initialisation and then receive the fax. After reception, qfax will close the serial port and exit, it supplies an exit status of 0 for success, non-zero on error.

ex qfax;'[-p] [-v] [-x] [-i ini] [-e N] [-l logfile0]
[-P poll] -g'

where -v, -l, -x, -e, -i, -p, -P function as above

-G
When qfax is invoked -G, it assumes that the parent has passed the open serial channel as standard SMS/QDOS stack channels, with an additional channel(s) for log messages. The stdin channel is the open serial channel, the stderr channel for verbose qfax messages, the stdout channel may be nul or a temporary (gash) file. qfax will not close the serial port on exit; but will honour exit baud settings and supplies an exit status of 0 for success, non-zero on error.

ew qfax,#c4,nul,#c1;[-p] [-v] [-x] [-i ini] [-e N] [-l log]
[-P poll] -G
where -v, -l, -x, -e, -i, -p, -P function as above

open #4, 'ser2hr'
open #5, 'con'
...
ew qfax,#4,#5,nul;'-p -v -G'
...
close #4
close #5

With QBOX BBS, the something like the following may be specified:.

win1_qfax %>>nul %>ram1_fax_log %< -xvG

The stderr channel is used for the verbose qfax status message; the stdout channel is used for the two information messages.

Connect at 9600 bps to xxxx xxxxxx (SomeLuckyPerson)
Sending:0, connect time 40 secs, [xxxx xxxxxx] (SomeLuckyPerson)

You may choose to supply either a stdout or stderr channel depending on the volume of messages required.

Addition information is given in section QFAX and QBOX.

qfax MONITOR mode

This is only applicable if you use the QJump Pointer Environment (PE). qfax has a `-m (monitor)' option. This takes a "number of rings" parameter, just like `-W (wait)', but when ring is detected, a popup window is displayed, with the legend `QFAX Answer ?' and options of `Yes' and `No'.

There are then (at least) the following possibilities.

This facility is only available if you are using the Pointer Environment.

Polling (responding)

Through the receive mechanism, qfax can also respond to poll requests and send a fax to a caller. You indicate your ability to respond to poll requests by defining your poll response fax file with the -P option. This file will be sent by any of the qfax receive modes when the phone is answered to a remote poll request. qfax may also receive a fax from the poller before sending its poll response fax if requested.

ex qfax;'-v -W 2 -P  ram7_qfaxpoll_fax'

In the example, qfax answers after two rings, will receive a fax if the caller sends one and will return the poll fax from the file ram7_qfaxpoll_fax if the caller makes a poll request.

qfax records the full path name of the last fax successfully received, in a file `INDIR_QFAX-LastFax' (INDIR being your top level inbound fax directory). The file just contains the full path name of the last received fax, terminated with LF (line feed). The qfv and printfax programs can easily access the last received fax.

qfax Server

It is possible to run qfax in `-m (monitor)' or `-W (wait)' modes, and issue commands to it via a "Client Server Manager" (CSM) interface. The interface allow you to send a fax without first removing `qfax', put it into a sleep mode, where it releases the serial channel (so you can use, say, QTPI), wake it from sleep (get the serial device back and wait/monitor again); qfax can send the results of commands back to a client application. A example PE qfax client application (qfaxClient) is supplied.

The qfax server commands are

send
send fax (can use aliases)
grab
as -g
sleep
close serial
wake
only valid after sleep, reopens serial
exit
exits qfax
poll
polls a remote, may also send and poll.

These are illustrated by examples below:


ex qfax;'-m 3'
(ex cview;'qfax -m 3')                   even better

client 'QFAX'                            send commands to qfax server
request 'QFAX','send jrh ram2_*_fax',a$  tell qfax to send
print a$                                 read result from qfax
(qfax returns command result)
(now qfax goes back to -m mode)
(qfax receives some faxes here)
...
request 'qfax','quit'                    tell qfax to stop
freeclient 'qfax'

The send command requires a phone number (or NAME/ALIAS) and a file. The poll command requires a phone number and optionally a file name if you wish to send as well.

send jrh ram2_f1_001 ram2_x_fax
send 00-968-699407 ram1_test_g3
poll 699407
poll 699407 ram1_demo_fax

When a `sleep' command has been issued, any commands other than `wake', `quit' and `exit' are ignored.

CSM is a system extension to facilitate simple, cooperative, client server applications. CSM is free and freely distributable and available from the usual freeware sources.

Using qfaxClient

qfaxClient is a simple PE application that can be used in conjunction with qfax in server mode.

Now move the pointer into the qfaxClient program.

Now, assuming you have an alias `jrh' set up and a fax file `ram1_test_fax', hit F3 and type send jrh ram_test_fax<RET>. qfax will start to send the fax, and when it's finished, a message will appear in the qfaxClient window to inform you. If a fax is received while qfaxClient is running, then you will also get a message.

You use all the qfax server commands (send, grab, sleep, wake, quit, exit) from the qfaxClient application.

Please note that qfaxClient is a simple, demonstration application. The `C' source code is available with the QFAX distribution. It is not a supported part of the QFAX suite.

QFAXINI

This keyword may be used in `qfax_dat' to define qfax options that are processed before any command line options. For example:

given QFAXINI = -p -l ram7_qfax_log -R -v -P ram7_poll_fax
then
ex qfax
is the same as
ex qfax;'-p -l ram7_qfax_log -R -v -P ram7_poll_fax'
and
ex qfax;'-W 3'
is the same as
ex qfax;'-p -l ram7_qfax_log -v -W 3 -P ram7_poll_fax'

The `-W 3' argument on the command line overrides the contradictory `-R' in the QFAXINI definition. The `-p' option would be ignored in:

ex qfax;'-s jh ram2_test_fax'

where `jh' is an alias and the full equivalent command might be:

ex qfax;'-l ram7_qfax_log -v -s 00-968-699407 ram2_test_fax'

Go to the first, previous, next, last section, table of contents.