1FAXALTER(1) General Commands Manual FAXALTER(1)
2
6 faxalter - alter parameters of a HylaFAX job queued for transmission
7
9 faxalter [ -O config ] [ options ] id...
10
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 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
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 -C command
31 Issue the raw command as a line to the server.
32 -d destination
34 Change the destination number to destination.
35 -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 -A Use administrative privileges; faxalter will prompt for the
48 password to set administrative privileges.
49 -k time Specify a new time to kill a job; the syntax is the same as
51 used for the -a option.
52 -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 -N Do not suspend or submit the job. This may be typically used
58 in conjuction with -C to query job details.
59 -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 -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 -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 -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 -t tries Set the maximum number of times the server should call the
82 remote fax machine.
83 -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 -u user Specify the login user name.
94 -U pass:adminpass
96 Specify the login password and optionally the admin password
97 preceded by a colon.
98 -v Trace the protocol exchanges between faxalter and the remote
100 hfaxd process. Tracing information is written to the stan‐
101 dard output.
102
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 The configuration parameters are explained below:
117 Host The host to contact for service. (Equivalent to the -h
119 option.)
120 PassiveMode
122 Whether or not to use passive mode in communication with the
123 server.
124 Port The network port to contact for service. (Equivalent to the
126 -h option.)
127 Protocol The name of the communication protocol to use when contacting
129 a server. (Equivalent to the FAXSERVICE environment vari‐
130 able.)
131 Timeout The timeout, in seconds, to wait for a server response.
133 Verbose Control protocol tracing. (Equivalent to the -v option.)
135
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
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 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 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 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 The continued use of the at(1)-style notation for specifying times is
167 questionable (it was done for backwards compatibility).
168
170 hylafax-client(1), sendfax(1), faxrm(1), faxstat(1), hfaxd(8C)
171 July 11, 1996 FAXALTER(1)