Provided by: hylafax-client_6.0.7-3.1_amd64 bug

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(5).

       •  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,  /etc/hylafax, and the directory where document conversion programs reside,
       /usr/sbin (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(8) 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 /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:
              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(8).   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/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

SEE ALSO

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

                                           May 8, 1996                          HYLAFAX-CLIENT(1)