1FAXALTER(1)                 General Commands Manual                FAXALTER(1)
2
3
4

NAME

6       faxalter - alter parameters of a HylaFAX job queued for transmission
7

SYNOPSIS

9       faxalter [ -O config ] [ options ] id...
10

DESCRIPTION

12       faxalter  changes the state of one or more HylaFAX jobs that are queued
13       for transmission.  Numerous parameters can be altered; see the  options
14       below.
15
16       An  id  is  a  number  that identifies a job that has been submitted to
17       HylaFAX; these numbers are printed by sendfax(1) when jobs  are  queued
18       for  transmission  and can also be displayed with faxstat(1).  Unprivi‐
19       leged users can alter the parameters of jobs  that  they  own;  clients
20       with  administrative privileges on a server can manipulate any job (see
21       the -A option below).  The user may be specified by the  FAXUSER  envi‐
22       ronment  variable.   By default, faxalter contacts the facsimile server
23       on the host specified in the FAXSERVER environment variable;  but  con‐
24       sult the -h option for more information.
25

OPTIONS

27       -a time   Specify  a new time to send a job.  The syntax for specifying
28                 a time is the same as used by sendfax(1) (and at(1)).
29
30       -C command
31                 Issue the raw command as a line to the server.
32
33       -d destination
34                 Change the destination number to destination.
35
36       -h host   Force the server to be contacted on  a  specific  host.   The
37                 host  may  be  either  a  symbolic name or a network address.
38                 IPv6 addresses are given in ``[xx:xx::x]:port''  format.   If
39                 no  -h  option is supplied, faxalter uses the FAXSERVER envi‐
40                 ronment variable to identify the HylaFAX server  to  contact.
41                 If  this variable is not set, then faxalter checks for a set‐
42                 ting in the configuration files (first in the  per-user  file
43                 and  then  in  the  system-wide  file).   If all of the above
44                 fails, then faxalter attempts to  contact  a  server  on  the
45                 machine where it is run.
46
47       -A        Use  administrative  privileges; faxalter will prompt for the
48                 password to set administrative privileges.
49
50       -k time   Specify a new time to kill a job; the syntax is the  same  as
51                 used for the -a option.
52
53       -m modem  Assign/reassign  the jobs to the specified modem.  Specifying
54                 ``any'' for modem causes the jobs to  be  scheduled  for  any
55                 available modem.
56
57       -N        Do not suspend or submit the job.  This may be typically used
58                 in conjuction with -C to query job details.
59
60       -O config Treat config as a configuration parameter specification  that
61                 is  interpreted  after  reading  the configuration file.  For
62                 example, ``-O Host:fax.example.com'' would set the Host  con‐
63                 figuration  parameter  to ``fax.example.com'', overriding any
64                 setting in the configuration file.
65
66       -p        The jobs should be pushed; that is, they should  be  requeued
67                 with  a  time-to-send as the current time (this is equivalent
68                 to ``-a now'').
69
70       -P pri    Set the scheduling priority for the specified jobs.  The pri‐
71                 ority  is  an  integer value in the range 0-255; lower values
72                 give a job higher priority.  The default scheduling  priority
73                 for  a  job is 127 and priorities are recalculated after each
74                 attempt to process a job.
75
76       -r        Resubmits a job.  This will duplicate  any  job  that  is  in
77                 either  the  send queue or in the done queue.  When resubmit‐
78                 ting jobs that are past their killtime the -k  option  should
79                 also be used to specify a new time to kill the job.
80
81       -t tries  Set  the  maximum  number of times the server should call the
82                 remote fax machine.
83
84       -n scheme Select a notification scheme to use for the  specified  jobs.
85                 Possible schemes are: ``none'' for no notification (default),
86                 ``when done'' for notification when  the  job  is  completed,
87                 ``when  requeued''  for notification when the job is requeued
88                 after a failed transmission attempt.   The  -Q,  -D,  and  -R
89                 options are shorthand for these notification schemes, respec‐
90                 tively.  One can also leave off ``when'' when  using  the  -n
91                 option; e.g., ``done'' instead of ``when done''.
92
93       -u user   Specify the login user name.
94
95       -U pass:adminpass
96                 Specify  the login password and optionally the admin password
97                 preceded by a colon.
98
99       -v        Trace the protocol exchanges between faxalter and the  remote
100                 hfaxd  process.   Tracing information is written to the stan‐
101                 dard output.
102

CONFIGURATION PARAMETERS

104       faxalter   reads    configuration    information    from    the    file
105       /etc/hylafax/hyla.conf and then from the file ~/.hylarc.  Configuration
106       files follow the conventions described in hylafax-client(1).  The  fol‐
107       lowing configuration parameters are recognized:
108       Tag              Type       Default      Description
109       Host             string     localhost    host to contact for service
110       PassiveMode      boolean    false        whether or not to use passive mode
111       Port             integer    4559         port to use in contacting server
112       Protocol         string     tcp          protocol to use in contacting server
113       Timeout          integer    3600         timeout in seconds waiting for server response
114       Verbose          boolean    No           whether or not to enable protocol tracing
115
116       The configuration parameters are explained below:
117
118       Host      The  host  to  contact  for  service.   (Equivalent to the -h
119                 option.)
120
121       PassiveMode
122                 Whether or not to use passive mode in communication with  the
123                 server.
124
125       Port      The  network port to contact for service.  (Equivalent to the
126                 -h option.)
127
128       Protocol  The name of the communication protocol to use when contacting
129                 a  server.   (Equivalent  to the FAXSERVICE environment vari‐
130                 able.)
131
132       Timeout   The timeout, in seconds, to wait for a server response.
133
134       Verbose   Control protocol tracing.  (Equivalent to the -v option.)
135

RETURN VALUE

137       On complete success faxalter returns 0.  If there  is  a  user-supplied
138       syntax  error  then 1 is returned.  If a login to the server was unsuc‐
139       cessful then 2 is returned.  If some client-server job processing error
140       occured then faxalter returns 3.
141

NOTES

143       Setting  a  job's  killtime  without  also setting the time to send may
144       cause the wrong value for the killtime to be sent.  This is because the
145       killtime  is  calculated as the difference in time between the killtime
146       and time to send: and if the time to send is not specified, then faxal‐
147       ter  uses the current time instead of querying the server for the job's
148       time to send.
149
150       faxalter suspends a job before attempting to alter its state.  If a job
151       is  active  when  a  suspend request is made there may be a delay while
152       waiting for the job to enter a consistent state where it  can  be  sus‐
153       pended.   If  faxalter is interrupted during this time then jobs may be
154       left suspended.
155
156       faxalter requeues the job.  This means that the job will end up at  the
157       bottom  of  the  queue  for  the job's priority.  Thus, when queues are
158       heavy an adjustment of the job's killtime may  need  to  be  considered
159       when altering any other parameter.
160
161       faxalter  only  understands  how to alter a subset of the available job
162       parameters; there are many more client-controllable parameters that can
163       only  be  modified  by communicating directly with the server using the
164       underlying protocol.
165
166       The continued use of the at(1)-style notation for specifying  times  is
167       questionable (it was done for backwards compatibility).
168

SEE ALSO

170       hylafax-client(1), sendfax(1), faxrm(1), faxstat(1), hfaxd(8C)
171
172
173
174                                 July 11, 1996                     FAXALTER(1)
Impressum