HYLAFAX-CLIENT(1)HYLAFAX-CLIENT(1)NAME
HylaFAX-client - introduction to HylaFAX client applications and usage
SYNOPSIS
sendfax [options] [files...]
sendpage [options] [message...]
faxstat [options]
faxrm [options]
faxalter [options] jobid...
fax2ps [options] [files...]
DESCRIPTION
HylaFAX is a telecommunication system for UNIX® systems. Among the
features of HylaFAX are:
· HylaFAX runs as a network service; this means a modem may be effec‐
tively shared by a large number of users.
· HylaFAX can be configured to work with a wide variety of modems on a
wide variety of systems.
· Access to the system can be restricted by the administrator to
selected hosts and/or users.
· Transmission requests may be processed immediately (default) or
queued for processing at a later time, in the manner of the at(1)
command.
· Remote facsimile machines may be polled to retrieve publicly avail‐
able documents.
· POSTSCRIPT®, PDF, and TIFF Class F documents are passed directly to
the fax server for transmission; the system attempts to convert
other file formats to either POSTSCRIPT or TIFF through the use of
an extensible file typing and conversion facility. In normal opera‐
tion ASCII-text, troff(1) output, and Silicon Graphics images are
automatically converted. Additional file formats can be added; see
typerules(5F).
· The faxcover(1) program can be automatically invoked to create a
cover page for each facsimile, using information deduced by the
sendfax command. Alternatively, users may supply their own cover
pages using their preferred tools.
· Facsimile are normally imaged in a system-default page size (usually
letter-size pages, 8.5" by 11", for sites in North America). Alter‐
nate page sizes can be specified with a -s option to all HylaFAX
programs. Well known page sizes include: ISO A3, ISO A4, ISO A5,
ISO A6, ISO B4, North American Letter, American Legal, American
Ledger, American Executive, Japanese Letter, and Japanese Legal.
Note that it may not be permissible to image into the full page
area; the guaranteed reproducible area for a page is typically
smaller. Also, note that while arbitrary page sizes can be speci‐
fied, only a limited number of page dimensions are supported by the
facsimile protocol. Thus if an odd-size facsimile is submitted for
transmission it may not be possible to determine if it can be sent
until the fax server establishes communication with the remote fac‐
simile machine.
· Facsimile can be sent at low resolution (98 lines/inch) or medium
resolution (196 lines/inch)—often called fine mode. Documents with
mixed resolution pages are handled correctly.
· Users are notified by electronic mail if a job can not be transmit‐
ted. It is also possible to receive notification by mail when a job
has been completed successfully and each time that the job is
requeued for retransmission. Any untransmitted documents are
returned to the sender by electronic mail in a form suitable for
resubmission.
· Support is provided for broadcasting facsimile. The HylaFAX server
software optimizes preparation of broadcast documents and the client
applications support the notion of a job group which permits a group
of jobs to be manipulated together.
· Support is provided for transmitting alpha-numeric messages to pager
devices or GSM mobiles using the Simple Network Paging Protocol
(SNPP) and the IXO or UCP protocol (for message delivery).
The HylaFAX software is divided into two packages: software used on
client machines and software used on machines where one or more modems
reside. Client software includes:
· sendfax, a program to submit outgoing facsimile;
· sendpage, a program to submit alpha-numeric messages to SNPP
servers;
· faxstat, a program obtain status information about HylaFAX servers;
· faxrm, a program to remove jobs and documents;
· faxalter, a program to change parameters of queued jobs; and
· fax2ps, a program that converts facsimile documents to POSTSCRIPT so
that they may be viewed with a POSTSCRIPT previewer or printed on a
POSTSCRIPT printer (this program is actually part of the companion
TIFF distribution that is used by HylaFAX).
Many systems also support submission of outgoing facsimile by elec‐
tronic mail and/or graphical interfaces to the sendfax program. Such
facilities are site-dependent; consult local documentation for more
information.
GETTING STARTED
To use the HylaFAX client software on your machine you need to either
load the appropriate software on your machine, or you need to locate a
machine that already has the client software installed and setup sym‐
bolic links to the appropriate directories. If you choose the latter,
then beware that you need links to three directories: the directory
where client applications reside, /usr/local/bin, the directory where
the client application database files reside, /usr/local/lib/fax, and
the directory where document conversion programs reside,
/usr/local/sbin (the last two directories may be the same on your sys‐
tem).
Once the software is setup on your machine you need to locate a host
that has a facsimile server that you can use. The host, and possibly
the modem on the host, should be defined in your environment in the
FAXSERVER variable. For example, for csh users,
setenv FAXSERVER flake.asd
or for ksh or sh users,
FAXSERVER=flake.asd; export FAXSERVER
If there are multiple modems on your server then you may be assigned to
use a specific modem. For example, if you are to use the modem
attached to the ttym2 port on the server machine, then the FAXSERVER
variable should be setup as
FAXSERVER=ttym2@flake.asd; export FAXSERVER
(Note: the SNPPSERVER environment variable is used instead of FAXSERVER
by the sendpage program; consult sendpage(8C) for more information.)
Note also, that before you can submit outgoing facsimile jobs the
administrator for the facsimile server may need to register your iden‐
tity in an access control list. You will encounter the message ``530
User %s access denied.'' if access to your server is controlled and
you are not properly registered or you may be prompted for a password
and then denied service with ``530 Login incorrect.''.
DIAL STRINGS
A dial string specifies how to dial the telephone in order to reach a
destination facsimile machine. HylaFAX permits arbitrary strings to be
passed to the facsimile server so that users can specify credit card
information, PBX routing information, etc. Alphabetic characters are
automatically mapped to their numeric key equivalents (e.g. ``1800Got‐
Milk'' becomes ``18004686455''). Other characters can be included for
readability; anything that must be stripped will be removed by the
server before the dialing string is passed to the fax modem. Private
information such as credit card access codes are withheld from status
messages and publicly accessible log files (with proper configuration).
Facsimile servers also automatically insert any leading dialing prefix‐
ing strings that are required to place outgoing phone calls; e.g. dial‐
ing ``9'' to get an outside line. Additionally, if a phone number is
fully specified with the international direct dialing digits (IDDD),
then any prefixing long distance or international dialing codes that
are required to place the call will be inserted in the dial string by
the server. For example, ``+31.77.594.131'' is a phone number in the
Netherlands; it would be converted to ``0113177594131'' if the call is
placed in the United States. The number ``+14159657824'' is a phone
number in California; if this number is called from within the 415 area
code in the United States, then the server would automatically convert
this to ``9657824'' because in the San Francisco Bay Area, local phone
calls must not include the area code and long distance prefixing code.
The general rule in crafting dial strings is to specify exactly what
you would dial on your telephone; and, in addition, the actual phone
number can be specified in a location-independent manner by using the
IDD syntax of ``+country-code local-part''.
COVER PAGES
The sendfax program can automatically generate a cover page for each
outgoing facsimile. Such cover pages are actually created by the fax‐
cover(1) program by using information that is deduced by sendfax and
information that is supplied on the command line invocation of sendfax.
Users may also request that sendfax not supply a cover page and then
provide their own cover page as part of the data that is to be trans‐
mitted.
Automatically-generated cover pages may include the following informa‐
tion:
· the sender's name, affiliation, geographic location, fax number, and
voice telephone number;
· the recipient's name, affiliation, geographic location, fax number,
and voice telephone number;
· text explaining what this fax is ``regarding'';
· text commentary;
· the local date and time that the job was submitted;
· the number of pages to be transmitted.
Certain of this information is currently obtained from a user's per‐
sonal facsimile database file; ~/.faxdb. Note that this file is depre‐
cated; it is described here only because it is still supported for com‐
patibility with older versions of the software.
The .faxdb file is an ASCII file with entries of the form
keyword : value
where keyword includes:
Name a name associated with destination fax machine;
Company a company name;
Location in-company locational information, e.g. a build‐
ing#;
FAX-Number phone number of fax machine;
Voice-Number voice telephone number.
Data is free format. Whitespace (blank, tab, newline) can be freely
interspersed with tokens. If tokens include whitespace, they must be
enclosed in quote marks (``"''). The ``#'' character introduces a com‐
ment—everything to the end of the line is discarded.
Entries are collected into aggregate records by enclosing them in
``[]''. Records can be nested to create a hierarchy that that supports
the inheritance of information—unspecified information is inherited
from parent aggregate records.
For example, a sample file might be:
[ Company: "Silicon Graphics, Inc."
Location: "Mountain View, California"
[ Name: "Sam Leffler" FAX-Number: +1.415.965.7824 ]
]
which could be extended to include another person at Silicon Graphics
with the following:
[ Company: "Silicon Graphics, Inc."
Location: "Mountain View, California"
[ Name: "Sam Leffler" FAX-Number: +1.415.965.7824 ]
[ Name: "Paul Haeberli" FAX-Number: +1.415.965.7824 ]
]
Experience indicates that the hierarchical nature of this database for‐
mat makes it difficult to maintain with automated mechanisms. As a
result it is being replaced by other, more straightforward databases
that are managed by programs that front-end the sendfax program.
CONFIGURATION FILES
HylaFAX client applications can be tailored on a per-user and per-site
basis through configuration files. Per-site controls are placed in the
file /usr/local/lib/fax/hyla.conf, while per-user controls go in
~/.hylarc. In addition a few programs that have many parameters that
are specific to their operation support an additional configuration
file; these files are identified in their manual pages.
Configuration files have a simple format and are entirely ASCII. A
configuration parameter is of the form
tag: value
where a tag identifies a parameter and a value is either a string, num‐
ber, or boolean value. Comments are introduced by the ``#'' character
and extend to the end of the line. String values start at the first
non-blank character after the ``:'' and continue to the first non-
whitespace character or, if whitespace is to be included, may be
enclosed in quote marks (``"''). String values enclosed in quote marks
may also use the standard C programming conventions for specifying
escape codes; e.g. ``\n'' for a newline character and ``\xxx'' for an
octal value. Numeric values are specified according to the C program‐
ming conventions (leading ``0x'' for hex, leading ``0'' for octal, oth‐
erwise decimal). Boolean values are case insensitive. For a true
value, either ``Yes'' or ``On'' should be used. For a false value, use
``No'' or ``Off''.
RECEIVED FACSIMILE
Incoming facsimile are received by facsimile servers and deposited in a
receive queue directory on the server machine. Depending on the
server's configuration, files in this directory may or may not be read‐
able by normal users. The faxstat program can be used to view the con‐
tents of the receive queue directory:
hyla% faxstat -r
HylaFAX scheduler on hyla.chez.sgi.com: Running
Modem ttyf2 (+1 510 999-0123): Running and idle
Protect Page Owner Sender/TSI Recvd@ Filename
-rw-r-- 9 fax 1 510 5268781 05Jan96 fax00005.tif
-rw-r-- 8 fax 1 510 5268781 07Jan96 fax00009.tif
-rw-r-- 2 fax 1 510 5268781 07Jan96 fax00010.tif
-rw-r-- 3 fax +14159657824 08Jan96 fax00011.tif
-rw-r-- 2 fax +14159657824 08Jan96 fax00012.tif
Consult the faxstat manual page for a more detailed description of this
information.
Received facsimile are stored as TIFF Class F files. These files are
bilevel images that are encoded using the CCITT T.4 or CCITT T.6 encod‐
ing algorithms. The fax2ps(1) program can be used to view and print
these files. A file can be viewed by converting it to POSTSCRIPT and
then viewing it with a suitable POSTSCRIPT previewing program, such as
xpsview(1) (Adobe's Display POSTSCRIPT-based viewer), ghostview(1) (a
public domain previewer), or image viewer programs such as viewfax(1)
(public domain), faxview(1) (another public domain TIFF viewer pro‐
gram), xv(1) (shareware and/or public domain), or xtiff(1) (a program
included in the public domain TIFF software distribution). Consult
your local resources to figure out what tools are available for viewing
and printing received facsimile.
CLIENT-SERVER PROTOCOL
HylaFAX client applications communicate with servers using either a
special-purpose communications protocol that is modeled after the
Internet File Transfer Protocol (FTP) or, when submitting alpha-numeric
pages, the Simple Network Paging Protocol (SNPP), specified in RFC
1861. All client programs support a -v option that can be used to
observe the protocol message exchanges. In some situations it may be
more effective to communicate directly with a HylaFAX server using the
client-server protocol. This can be accomplished with an FTP or Telnet
client application; though an FTP client is recommended because it
implements the protocol needed to obtain server status information.
For information on the server-side support provided with HylaFAX con‐
sult hfaxd(8C). For documentation on the client-server fax protocol
consult RFC XXXX (to be filled in).
EXAMPLES
This section gives several examples of command line usage; consult the
manual pages for the individual commands for information on the options
and program operation.
The following command queues the file zall.ps for transmission to John
Doe at the number (123)456-7890 using fine mode; the server will
attempt to send it at 4:30 A.M.:
sendfax -a "0430" -m -d "John Doe@1.123.456.7890" zall.ps
(the leading ``1.'' is supplied to dial area code ``123'' in the United
States.)
The following command generates a one-page facsimile that is just a
cover page:
faxcover -t "John Doe" -n "(123)456-7890"
-c "Sorry John, I forgot the meeting..." |
sendfax -n -d "(123)456-7890"
(note that the line was broken into several lines solely for presenta‐
tion.)
The following command displays the status of the facsimile server and
any jobs queued for transmission:
faxstat -s
The following command displays the status of the facsimile server and
any documents waiting in the receive queue on the server machine:
faxstat -r
The following command shows how to use an FTP client program to commu‐
nicate directly with a HylaFAX server:
hyla% ftp localhost hylafax
Connected to localhost.
220 hyla.chez.sgi.com server (HylaFAX (tm) Version 4.0beta005) ready.
Name (localhost:sam):
230 User sam logged in.
Remote system type is UNIX.
Using binary mode to transfer files.
ftp> dir sendq
200 PORT command successful.
150 Opening new data connection for "sendq".
208 126 S sam 5268781 0:3 1:12 16:54 No local dialtone
226 Transfer complete.
ftp> quote jkill 208
200 Job 208 killed.
ftp> dir doneq
200 PORT command successful.
150 Opening new data connection for "doneq".
208 126 D sam 5268781 0:3 1:12 No local dialtone
226 Transfer complete.
ftp> quote jdele 208
200 Job 208 deleted; current job: (default).
ftp> dir docq
200 PORT command successful.
150 Opening new data connection for "docq".
-rw---- 1 sam 11093 Jan 21 16:48 doc9.ps
226 Transfer complete.
ftp> dele docq/doc9.ps
250 DELE command successful.
ftp> dir recvq
200 PORT command successful.
150 Opening new data connection for "recvq".
-rw-r-- 4 fax 1 510 5268781 30Sep95 faxAAAa006uh
-rw-r-- 9 fax +14159657824 11Nov95 faxAAAa006nC
-rw---- 25 fax +14159657824 Fri08PM fax00016.tif
226 Transfer complete.
ftp> quit
221 Goodbye.
The following command shows how to use a Telnet client program to com‐
municate directly with an SNPP server:
hyla% telnet melange.esd 444
Trying 192.111.25.40...
Connected to melange.esd.sgi.com.
Escape character is '^]'.
220 melange.esd.sgi.com SNPP server (HylaFAX (tm) Version 4.0beta010) ready.
login sam
230 User sam logged in.
help
214 The following commands are recognized (* =>'s unimplemented).
214 2WAY* ALER* DATA HOLD LOGI MSTA* PING RTYP* STAT
214 ABOR CALL* EXPT* KTAG* MCRE* NOQU* QUIT SEND SUBJ
214 ACKR* COVE* HELP LEVE MESS PAGE RESE SITE
250 Direct comments to FaxMaster@melange.esd.sgi.com.
page 5551212
250 Pager ID accepted; provider: 1800SkyTel pin: 5551212 jobid: 276.
send
250 Message processing completed.
quit
221 Goodbye.
Connection closed by foreign host.
FILES
/usr/local/bin/sendfax for sending facsimile
/usr/local/bin/sendpage for sending alpha-numeric pages
/usr/local/bin/fax2ps for converting facsimile to POSTSCRIPT
/usr/local/bin/faxalter for altering queued jobs
/usr/local/bin/faxcover for generating cover sheets
/usr/local/bin/faxmail for converting email to POSTSCRIPT
/usr/local/bin/faxrm for removing queued jobs
/usr/local/bin/faxstat for facsimile server status
/usr/local/sbin/sgi2fax SGI image file converter
/usr/local/sbin/textfmt ASCII text converter
/usr/local/lib/fax/typerules file type and conversion rules
/usr/local/lib/fax/pagesizes page size database
/usr/local/lib/fax/faxcover.ps prototype cover page
/usr/local/lib/fax/dialrules optional client dialstring rules
/var/spool/hylafax/tmp/sndfaxXXXXXX temporary files
SEE ALSOat(1), fax2ps(1), faxalter(1), faxcover(1), faxmail(1), faxrm(1), faxs‐
tat(1), sgi2fax(1), faxq(8C), viewfax(1), hylafax-server(5F), dial‐
rules(5F), pagesizes(5F), typerules(5F), services(4)
May 8, 1996 HYLAFAX-CLIENT(1)
