Provided by: hylafax-client_4.2.5-1_i386 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
       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:
              [   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)