1HYLAFAX-CLIENT(1)           General Commands Manual          HYLAFAX-CLIENT(1)
2
3
4

NAME

6       HylaFAX-client - introduction to HylaFAX client applications and usage
7

SYNOPSIS

9       sendfax [options] [files...]
10       sendpage [options] [message...]
11       faxstat [options]
12       faxrm [options]
13       faxalter [options] jobid...
14       fax2ps [options] [files...]
15

DESCRIPTION

17       HylaFAX  is  a  telecommunication  system for UNIX® systems.  Among the
18       features of HylaFAX are:
19
20       ·  HylaFAX runs as a network service; this means a modem may be  effec‐
21          tively shared by a large number of users.
22
23       ·  HylaFAX can be configured to work with a wide variety of modems on a
24          wide variety of systems.
25
26       ·  Access to the system can  be  restricted  by  the  administrator  to
27          selected hosts and/or users.
28
29       ·  Transmission  requests  may  be  processed  immediately (default) or
30          queued for processing at a later time, in the manner  of  the  at(1)
31          command.
32
33       ·  Remote  facsimile machines may be polled to retrieve publicly avail‐
34          able documents.
35
36       ·  POSTSCRIPT®, PDF, and TIFF Class F documents are passed directly  to
37          the  fax  server  for  transmission;  the system attempts to convert
38          other file formats to either POSTSCRIPT or TIFF through the  use  of
39          an extensible file typing and conversion facility.  In normal opera‐
40          tion ASCII-text, troff(1) output, and Silicon  Graphics  images  are
41          automatically  converted.  Additional file formats can be added; see
42          typerules(5F).
43
44       ·  The faxcover(1) program can be automatically  invoked  to  create  a
45          cover  page  for  each  facsimile,  using information deduced by the
46          sendfax command.  Alternatively, users may supply  their  own  cover
47          pages using their preferred tools.
48
49       ·  Facsimile are normally imaged in a system-default page size (usually
50          letter-size pages, 8.5" by 11", for sites in North America).  Alter‐
51          nate  page  sizes  can  be specified with a -s option to all HylaFAX
52          programs.  Well known page sizes include: ISO A3, ISO  A4,  ISO  A5,
53          ISO  A6,  ISO  B4,  North  American Letter, American Legal, American
54          Ledger, American Executive, Japanese  Letter,  and  Japanese  Legal.
55          Note  that  it  may  not  be permissible to image into the full page
56          area; the guaranteed reproducible  area  for  a  page  is  typically
57          smaller.   Also,  note that while arbitrary page sizes can be speci‐
58          fied, only a limited number of page dimensions are supported by  the
59          facsimile  protocol.  Thus if an odd-size facsimile is submitted for
60          transmission it may not be possible to determine if it can  be  sent
61          until  the fax server establishes communication with the remote fac‐
62          simile machine.
63
64       ·  Facsimile can be sent at low resolution (98  lines/inch)  or  medium
65          resolution  (196 lines/inch)—often called fine mode.  Documents with
66          mixed resolution pages are handled correctly.
67
68       ·  Users are notified by electronic mail if a job can not be  transmit‐
69          ted.  It is also possible to receive notification by mail when a job
70          has been completed successfully  and  each  time  that  the  job  is
71          requeued   for  retransmission.   Any  untransmitted  documents  are
72          returned to the sender by electronic mail in a form suitable for re-
73          submission.
74
75       ·  Support  is provided for broadcasting facsimile.  The HylaFAX server
76          software optimizes preparation of broadcast documents and the client
77          applications support the notion of a job group which permits a group
78          of jobs to be manipulated together.
79
80       ·  Support is provided for transmitting alpha-numeric messages to pager
81          devices  or  GSM  mobiles  using  the Simple Network Paging Protocol
82          (SNPP) and the IXO or UCP protocol (for message delivery).
83
84       The HylaFAX software is divided into two  packages:  software  used  on
85       client  machines and software used on machines where one or more modems
86       reside.  Client software includes:
87
88       ·  sendfax, a program to submit outgoing facsimile;
89
90       ·  sendpage,  a  program  to  submit  alpha-numeric  messages  to  SNPP
91          servers;
92
93       ·  faxstat, a program obtain status information about HylaFAX servers;
94
95       ·  faxrm, a program to remove jobs and documents;
96
97       ·  faxalter, a program to change parameters of queued jobs; and
98
99       ·  fax2ps, a program that converts facsimile documents to POSTSCRIPT so
100          that they may be viewed with a POSTSCRIPT previewer or printed on  a
101          POSTSCRIPT  printer  (this program is actually part of the companion
102          TIFF distribution that is used by HylaFAX).
103
104       Many systems also support submission of  outgoing  facsimile  by  elec‐
105       tronic  mail  and/or graphical interfaces to the sendfax program.  Such
106       facilities are site-dependent; consult  local  documentation  for  more
107       information.
108

GETTING STARTED

110       To  use  the HylaFAX client software on your machine you need to either
111       load the appropriate software on your machine, or you need to locate  a
112       machine  that  already has the client software installed and setup sym‐
113       bolic links to the appropriate directories.  If you choose the  latter,
114       then  beware  that  you  need links to three directories: the directory
115       where client applications reside, /usr/bin,  the  directory  where  the
116       client  application database files reside, /etc/hylafax, and the direc‐
117       tory where document conversion programs reside, /usr/sbin (the last two
118       directories may be the same on your system).
119
120       Once  the  software  is setup on your machine you need to locate a host
121       that has a facsimile server that you can use.  The host,  and  possibly
122       the  modem  on  the  host, should be defined in your environment in the
123       FAXSERVER variable.  For example, for csh users,
124
125              setenv FAXSERVER flake.asd
126
127       or for ksh or sh users,
128
129              FAXSERVER=flake.asd; export FAXSERVER
130
131       If there are multiple modems on your server then you may be assigned to
132       use  a  specific  modem.   For  example,  if  you  are to use the modem
133       attached to the ttym2 port on the server machine,  then  the  FAXSERVER
134       variable should be setup as
135
136              FAXSERVER=ttym2@flake.asd; export FAXSERVER
137
138       (Note: the SNPPSERVER environment variable is used instead of FAXSERVER
139       by the sendpage program;  consult sendpage(8C) for more information.)
140
141       Note also, that before you  can  submit  outgoing  facsimile  jobs  the
142       administrator  for the facsimile server may need to register your iden‐
143       tity in an access control list.  You will encounter the  message  ``530
144       User  %s  access  denied.''  if access to your server is controlled and
145       you are not properly registered or you may be prompted for  a  password
146       and then denied service with ``530 Login incorrect.''.
147

DIAL STRINGS

149       A  dial  string specifies how to dial the telephone in order to reach a
150       destination facsimile machine.  HylaFAX permits arbitrary strings to be
151       passed  to  the  facsimile server so that users can specify credit card
152       information, PBX routing information, etc.  Alphabetic  characters  are
153       automatically  mapped to their numeric key equivalents (e.g. ``1800Got‐
154       Milk'' becomes ``18004686455'').  Other characters can be included  for
155       readability;  anything  that  must  be  stripped will be removed by the
156       server before the dialing string is passed to the fax  modem.   Private
157       information  such  as credit card access codes are withheld from status
158       messages and publicly accessible log files (with proper configuration).
159       Facsimile servers also automatically insert any leading dialing prefix‐
160       ing strings that are required to place outgoing phone calls; e.g. dial‐
161       ing  ``9''  to get an outside line.  Additionally, if a phone number is
162       fully specified with the international direct  dialing  digits  (IDDD),
163       then  any  prefixing  long distance or international dialing codes that
164       are required to place the call will be inserted in the dial  string  by
165       the  server.   For example, ``+31.77.594.131'' is a phone number in the
166       Netherlands; it would be converted to ``0113177594131'' if the call  is
167       placed  in  the  United States.  The number ``+14159657824'' is a phone
168       number in California; if this number is called from within the 415 area
169       code  in the United States, then the server would automatically convert
170       this to ``9657824'' because in the San Francisco Bay Area, local  phone
171       calls must not include the area code and long distance prefixing code.
172
173       The  general  rule  in crafting dial strings is to specify exactly what
174       you would dial on your telephone; and, in addition,  the  actual  phone
175       number  can  be specified in a location-independent manner by using the
176       IDD syntax of ``+country-code local-part''.
177

COVER PAGES

179       The sendfax program can automatically generate a cover  page  for  each
180       outgoing  facsimile.  Such cover pages are actually created by the fax‐
181       cover(1) program by using information that is deduced  by  sendfax  and
182       information that is supplied on the command line invocation of sendfax.
183       Users may also request that sendfax not supply a cover  page  and  then
184       provide  their  own cover page as part of the data that is to be trans‐
185       mitted.
186
187       Automatically-generated cover pages may include the following  informa‐
188       tion:
189
190       ·  the sender's name, affiliation, geographic location, fax number, and
191          voice telephone number;
192
193       ·  the recipient's name, affiliation, geographic location, fax  number,
194          and voice telephone number;
195
196       ·  text explaining what this fax is ``regarding'';
197
198       ·  text commentary;
199
200       ·  the local date and time that the job was submitted;
201
202       ·  the number of pages to be transmitted.
203
204       Certain  of  this  information is currently obtained from a user's per‐
205       sonal facsimile database file; ~/.faxdb.  Note that this file is depre‐
206       cated; it is described here only because it is still supported for com‐
207       patibility with older versions of the software.
208
209       The .faxdb file is an ASCII file with entries of the form
210
211              keyword : value
212
213       where keyword includes:
214
215              Name          a name associated with destination fax machine;
216
217              Company       a company name;
218
219              Location      in-company locational information, e.g.  a  build‐
220                            ing#;
221
222              FAX-Number    phone number of fax machine;
223
224              Voice-Number  voice telephone number.
225
226       Data  is  free  format.  Whitespace (blank, tab, newline) can be freely
227       interspersed with tokens.  If tokens include whitespace, they  must  be
228       enclosed in quote marks (``"'').  The ``#'' character introduces a com‐
229       ment—everything to the end of the line is discarded.
230
231       Entries are collected into  aggregate  records  by  enclosing  them  in
232       ``[]''.  Records can be nested to create a hierarchy that that supports
233       the inheritance of  information—unspecified  information  is  inherited
234       from parent aggregate records.
235
236       For example, a sample file might be:
237              [   Company:   "Silicon Graphics, Inc."
238                  Location:  "Mountain View, California"
239                  [ Name: "Sam Leffler"     FAX-Number: +1.415.965.7824 ]
240              ]
241
242       which  could  be extended to include another person at Silicon Graphics
243       with the following:
244              [   Company:   "Silicon Graphics, Inc."
245                  Location:  "Mountain View, California"
246                  [ Name: "Sam Leffler"     FAX-Number: +1.415.965.7824 ]
247                  [ Name: "Paul Haeberli"   FAX-Number: +1.415.965.7824 ]
248              ]
249
250       Experience indicates that the hierarchical nature of this database for‐
251       mat  makes  it  difficult  to maintain with automated mechanisms.  As a
252       result it is being replaced by other,  more  straightforward  databases
253       that are managed by programs that front-end the sendfax program.
254

CONFIGURATION FILES

256       HylaFAX  client applications can be tailored on a per-user and per-site
257       basis through configuration files.  Per-site controls are placed in the
258       file  /etc/hylafax/hyla.conf,  while per-user controls go in ~/.hylarc.
259       In addition a few programs that have many parameters that are  specific
260       to  their  operation  support  an  additional configuration file; these
261       files are identified in their manual pages.
262
263       Configuration files have a simple format and  are  entirely  ASCII.   A
264       configuration parameter is of the form
265            tag: value
266       where a tag identifies a parameter and a value is either a string, num‐
267       ber, or boolean value.  Comments are introduced by the ``#''  character
268       and  extend  to  the end of the line.  String values start at the first
269       non-blank character after the ``:'' and  continue  to  the  first  non-
270       whitespace  character  or,  if  whitespace  is  to  be included, may be
271       enclosed in quote marks (``"'').  String values enclosed in quote marks
272       may  also  use  the  standard  C programming conventions for specifying
273       escape codes; e.g. ``\n'' for a newline character and ``\xxx''  for  an
274       octal  value.  Numeric values are specified according to the C program‐
275       ming conventions (leading ``0x'' for hex, leading ``0'' for octal, oth‐
276       erwise  decimal).   Boolean  values  are  case insensitive.  For a true
277       value, either ``Yes'' or ``On'' should be used.  For a false value, use
278       ``No'' or ``Off''.
279

RECEIVED FACSIMILE

281       Incoming facsimile are received by facsimile servers and deposited in a
282       receive queue directory  on  the  server  machine.   Depending  on  the
283       server's configuration, files in this directory may or may not be read‐
284       able by normal users.  The faxstat program can be used to view the con‐
285       tents of the receive queue directory:
286              hyla% faxstat -r
287              HylaFAX scheduler on hyla.chez.sgi.com: Running
288              Modem ttyf2 (+1 510 999-0123): Running and idle
289
290              Protect Page  Owner        Sender/TSI  Recvd@ Filename
291              -rw-r--    9  fax       1 510 5268781 05Jan96 fax00005.tif
292              -rw-r--    8  fax       1 510 5268781 07Jan96 fax00009.tif
293              -rw-r--    2  fax       1 510 5268781 07Jan96 fax00010.tif
294              -rw-r--    3  fax        +14159657824 08Jan96 fax00011.tif
295              -rw-r--    2  fax        +14159657824 08Jan96 fax00012.tif
296
297       Consult the faxstat manual page for a more detailed description of this
298       information.
299
300       Received facsimile are stored as TIFF Class F files.  These  files  are
301       Bi-level  images  that  are  encoded  using  the CCITT T.4 or CCITT T.6
302       encoding algorithms.  The fax2ps(1) program can be  used  to  view  and
303       print these files.  A file can be viewed by converting it to POSTSCRIPT
304       and then viewing it with a suitable POSTSCRIPT previewing program, such
305       as  xpsview(1)  (Adobe's Display POSTSCRIPT-based viewer), ghostview(1)
306       (a public domain previewer), or image viewer  programs  such  as  view‐
307       fax(1)  (public  domain), faxview(1) (another public domain TIFF viewer
308       program), xv(1) (shareware and/or public domain), or xtiff(1)  (a  pro‐
309       gram  included  in the public domain TIFF software distribution).  Con‐
310       sult your local resources to figure out what tools  are  available  for
311       viewing and printing received facsimile.
312

CLIENT-SERVER PROTOCOL

314       HylaFAX  client  applications  communicate  with servers using either a
315       special-purpose communications  protocol  that  is  modeled  after  the
316       Internet File Transfer Protocol (FTP) or, when submitting alpha-numeric
317       pages, the Simple Network Paging  Protocol  (SNPP),  specified  in  RFC
318       1861.   All  client  programs  support  a -v option that can be used to
319       observe the protocol message exchanges.  In some situations it  may  be
320       more  effective to communicate directly with a HylaFAX server using the
321       client-server protocol.  This can be accomplished with an FTP or Telnet
322       client  application;  though  an  FTP  client is recommended because it
323       implements the protocol needed to  obtain  server  status  information.
324       For  information  on the server-side support provided with HylaFAX con‐
325       sult hfaxd(8C).  For documentation on the  client-server  fax  protocol
326       consult RFC XXXX (to be filled in).
327

EXAMPLES

329       This  section gives several examples of command line usage; consult the
330       manual pages for the individual commands for information on the options
331       and program operation.
332
333       The  following command queues the file zall.ps for transmission to John
334       Doe at the number  (123)456-7890  using  fine  mode;  the  server  will
335       attempt to send it at 4:30 A.M.:
336              sendfax -a "0430" -m -d "John Doe@1.123.456.7890" zall.ps
337       (the leading ``1.'' is supplied to dial area code ``123'' in the United
338       States.)
339
340       The following command generates a one-page facsimile  that  is  just  a
341       cover page:
342              faxcover -t "John Doe" -n "(123)456-7890"
343                  -c "Sorry John, I forgot the meeting..." |
344                  sendfax -n -d "(123)456-7890"
345       (note  that the line was broken into several lines solely for presenta‐
346       tion.)
347
348       The following command displays the status of the facsimile  server  and
349       any jobs queued for transmission:
350              faxstat -s
351
352       The  following  command displays the status of the facsimile server and
353       any documents waiting in the receive queue on the server machine:
354              faxstat -r
355
356       The following command shows how to use an FTP client program to  commu‐
357       nicate directly with a HylaFAX server:
358              hyla% ftp localhost hylafax
359              Connected to localhost.
360              220 hyla.chez.sgi.com server (HylaFAX (tm) Version 4.0beta005) ready.
361              Name (localhost:sam):
362              230 User sam logged in.
363              Remote system type is UNIX.
364              Using binary mode to transfer files.
365              ftp> dir sendq
366              200 PORT command successful.
367              150 Opening new data connection for "sendq".
368              208  126 S    sam 5268781       0:3   1:12   16:54 No local dialtone
369              226 Transfer complete.
370              ftp> quote jkill 208
371              200 Job 208 killed.
372              ftp> dir doneq
373              200 PORT command successful.
374              150 Opening new data connection for "doneq".
375              208  126 D    sam 5268781       0:3   1:12         No local dialtone
376              226 Transfer complete.
377              ftp> quote jdele 208
378              200 Job 208 deleted; current job: (default).
379              ftp> dir docq
380              200 PORT command successful.
381              150 Opening new data connection for "docq".
382              -rw----   1      sam    11093 Jan 21 16:48 doc9.ps
383              226 Transfer complete.
384              ftp> dele docq/doc9.ps
385              250 DELE command successful.
386              ftp> dir recvq
387              200 PORT command successful.
388              150 Opening new data connection for "recvq".
389              -rw-r--    4  fax       1 510 5268781 30Sep95 faxAAAa006uh
390              -rw-r--    9  fax        +14159657824 11Nov95 faxAAAa006nC
391              -rw----   25  fax        +14159657824 Fri08PM fax00016.tif
392              226 Transfer complete.
393              ftp> quit
394              221 Goodbye.
395
396       The  following command shows how to use a Telnet client program to com‐
397       municate directly with an SNPP server:
398              hyla% telnet melange.esd 444
399              Trying 192.111.25.40...
400              Connected to melange.esd.sgi.com.
401              Escape character is '^]'.
402              220 melange.esd.sgi.com SNPP server (HylaFAX (tm) Version 4.0beta010) ready.
403              login sam
404              230 User sam logged in.
405              help
406              214 The following commands are recognized (* =>'s unimplemented).
407              214 2WAY*   ALER*   DATA    HOLD    LOGI    MSTA*   PING    RTYP*   STAT
408              214 ABOR    CALL*   EXPT*   KTAG*   MCRE*   NOQU*   QUIT    SEND    SUBJ
409              214 ACKR*   COVE*   HELP    LEVE    MESS    PAGE    RESE    SITE
410              250 Direct comments to FaxMaster@melange.esd.sgi.com.
411              page 5551212
412              250 Pager ID accepted; provider: 1800SkyTel pin: 5551212 jobid: 276.
413              send
414              250 Message processing completed.
415              quit
416              221 Goodbye.
417              Connection closed by foreign host.
418

FILES

420       /usr/bin/sendfax                for sending facsimile
421       /usr/bin/sendpage               for sending alpha-numeric pages
422       /usr/bin/fax2ps                 for converting facsimile to POSTSCRIPT
423       /usr/bin/faxalter               for altering queued jobs
424       /usr/bin/faxcover               for generating cover sheets
425       /usr/bin/faxmail                for converting email to POSTSCRIPT
426       /usr/bin/faxrm                  for removing queued jobs
427       /usr/bin/faxstat                for facsimile server status
428       /usr/sbin/sgi2fax               SGI image file converter
429       /usr/sbin/textfmt               ASCII text converter
430       /etc/hylafax/typerules          file type and conversion rules
431       /etc/hylafax/pagesizes          page size database
432       /etc/hylafax/faxcover.ps        prototype cover page
433       /etc/hylafax/dialrules          optional client dialstring rules
434       /var/spool/hylafax/tmp/sndfaxXXXXXXtemporary files
435

SEE ALSO

437       at(1), fax2ps(1), faxalter(1), faxcover(1), faxmail(1), faxrm(1), faxs‐
438       tat(1),  sgi2fax(1),  faxq(8C),  viewfax(1),  hylafax-server(5F), dial‐
439       rules(5F), pagesizes(5F), typerules(5F), services(4)
440
441
442
443                                  May 8, 1996                HYLAFAX-CLIENT(1)
Impressum