hylafax-client

HYLAFAX-CLIENT(1)            General Commands Manual           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
          effectively 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 available
          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 operation
          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).
          Alternate 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 specified, 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 facsimile 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 transmitted.
          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 electronic
       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 symbolic
       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/bin, the directory where the client
       application database files reside, /usr/lib/fax, and the directory where
       document conversion programs reside, /usr/lib/fax (the last two
       directories may be the same on your system).

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

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.
       ``1800GotMilk'' 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 prefixing strings that are required to place outgoing phone
       calls; e.g. dialing ``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
       faxcover(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
       transmitted.

       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 compatibility
       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
       enclosed 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:
              [   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 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 /usr/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,
       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:
              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 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 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
       presentation.)

       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
       communicate 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
       communicate 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/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/lib/fax/sgi2fax            SGI image file converter
       /usr/lib/fax/textfmt            ASCII text converter
       /usr/lib/fax/typerules          file type and conversion rules
       /usr/lib/fax/pagesizes          page size database
       /usr/lib/fax/faxcover.ps        prototype cover page
       /usr/lib/fax/dialrules          optional client dialstring rules
       /var/spool/hylafax/tmp/sndfaxXXXXXXtemporary files

SEE ALSO
       at(1), fax2ps(1), faxalter(1), faxcover(1), faxmail(1), faxrm(1),
       faxstat(1), sgi2fax(1), faxq(8C), viewfax(1), hylafax-server(5F),
       dialrules(5F), pagesizes(5F), typerules(5F), services(4)



                                   May 8, 1996                 HYLAFAX-CLIENT(1)