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 identity 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.''.

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''.

Automatically-generated cover pages may include the following information:

*

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 personal facsimile database file; ~/.faxdb. Note that this file is deprecated; it is described here only because it is still supported for compatiblity 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 building#;

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 encloseed in quote marks (``"''). The ``#'' character introduces a comment---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:

Experience indicates that the hierarchical nature of this database
format 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
/etc/hylafax/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, number, 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 programming
conventions (leading ``0x'' for hex, leading ``0'' for octal, otherwise
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 readable by normal users.
The
faxstat

program can be used to view the contents of the receive queue
directory:

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
encoding 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 program),
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 consult
(8C).

For documentation on the client-server fax protocol consult RFC XXXX
(to be filled in).

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.:

(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:

(note that the line was broken into several lines solely for presentation.)

The following command displays the status of the facsimile
server and any jobs queued for transmission:

The following command displays the status of the facsimile
server and any documents waiting in the receive queue on the
server machine:

The following command shows how to use an
FTP
client program to communicate directly with a HylaFAX server:

The following command shows how to use a Telnet client program
to communicate directly with an SNPP server:

/usr/bin/sendfax                for sending facsimile
/usr/bin/sendpage               for sending alpha-numeric pages
/usr/bin/fax2ps                 for converting facsimile to POSTSCRIPT
/usr/bin/faxalter               for altering queued jobs
/usr/bin/faxcover               for generating cover sheets
/usr/bin/faxmail                for converting email to POSTSCRIPT
/usr/bin/faxrm                  for removing queued jobs
/usr/bin/faxstat                for facsimile server status
/usr/sbin/sgi2fax               SGI image file converter
/usr/sbin/textfmt               ASCII text converter
/etc/hylafax/typerules          file type and conversion rules
/etc/hylafax/pagesizes          page size database
/etc/hylafax/faxcover.ps        prototype cover page
/etc/hylafax/dialrules          optional client dialstring rules
/var/spool/hylafax/tmp/sndfaxXXXXXXtemporary files

at(1),

fax2ps(1),

faxalter(1),

faxcover(1),

faxmail(1),

faxrm(1),

faxstat(1),

sgi2fax(1),

(8C),

viewfax(1),

(5F),

(5F),

(5F),

(5F),

services(4)