NAME¶
faxalter - alter parameters of a
HylaFAX job queued for transmission
SYNOPSIS¶
faxalter [
options ]
id...
DESCRIPTION¶
faxalter changes the state of one or more
HylaFAX jobs that are
queued for transmission. Numerous parameters can be altered; see the options
below.
An
id is a number that identifies a
job that has been submitted to
HylaFAX; these numbers are printed by
sendfax(1) when jobs are
queued for transmission and can also be displayed with
faxstat(1).
Unprivileged users can alter the parameters of jobs that they own; clients
with administrative privileges on a server can manipulate any job (see the
-A option below). The user may be specified by the
FAXUSER
environment variable. By default,
faxalter contacts the facsimile
server on the host specified in the
FAXSERVER environment variable; but
consult the
-h option for more information.
OPTIONS¶
- -a time
- Specify a new time to send a job. The syntax for specifying
a time is the same as used by sendfax(1) (and at(1)).
- -d destination
- Change the destination number to destination.
- -h host
- Force the server to be contacted on a specific host.
The host may be either a symbolic name or a network address. If no
-h option is supplied, faxalter uses the
FAXSERVER environment variable to identify the
HylaFAX server to contact. If this variable is not set, then
faxalter checks for a setting in the configuration files (first in
the per-user file and then in the system-wide file). If all of the above
fails, then faxalter attempts to contact a server on the machine
where it is run.
- -A
- Use administrative privileges; faxalter will prompt
for the password to set administrative privileges.
- -k time
- Specify a new time to kill a job; the syntax is the same as
used for the -a option.
- -m modem
- Assign/reassign the jobs to the specified modem.
Specifying ``any'' for modem causes the jobs to be scheduled for
any available modem.
- -p
- The jobs should be pushed; that is, they should be
requeued with a time-to-send as the current time (this is equivalent to
``-a now'').
- -P pri
- Set the scheduling priority for the specified jobs. The
priority is an integer value in the range 0-255; lower values give a job
higher priority. The default scheduling priority for a job is 127 and
priorities are recalculated after each attempt to process a job.
- -r
- Resubmits a job. This will duplicate any job that is in
either the send queue or in the done queue. When resubmitting jobs that
are past their killtime the -k option should also be used to
specify a new time to kill the job.
- -t tries
- Set the maximum number of times the server should call the
remote fax machine.
- -n scheme
- Select a notification scheme to use for the specified jobs.
Possible schemes are: `` none'' for no notification (default), ``
when done'' for notification when the job is completed, `` when
requeued'' for notification when the job is requeued after a failed
transmission attempt. The -Q, -D, and -R options are
shorthand for these notification schemes, respectively. One can also leave
off `` when'' when using the -n option; e.g., ``
done'' instead of `` when done''.
- -v
- Trace the protocol exchanges between faxalter and
the remote hfaxd process. Tracing information is written to the
standard output.
- -Z range
- Change the page range to be faxed to range
CONFIGURATION PARAMETERS¶
faxalter reads configuration information from the file
/etc/hylafax/hyla.conf and then from the file
~/.hylarc.
Configuration files follow the conventions described in
hylafax-client(1). The following configuration parameters are
recognized:
Tag Type Default Description
Host string localhost host to contact for service
PassiveMode boolean false whether or not to use passive mode
Port integer 4559 port to use in contacting server
Protocol string tcp protocol to use in contacting server
Verbose boolean No whether or not to enable protocol tracing
The configuration parameters are explained below:
- Host
- The host to contact for service. (Equivalent to the
-h option.)
- PassiveMode
- Whether or not to use passive mode in communication with
the server.
- Port
- The network port to contact for service. (Equivalent to the
-h option.)
- Protocol
- The name of the communication protocol to use when
contacting a server. (Equivalent to the FAXSERVICE environment
variable.)
- Verbose
- Control protocol tracing. (Equivalent to the -v
option.)
NOTES¶
Setting a job's killtime without also setting the time to send may cause the
wrong value for the killtime to be sent. This is because the killtime is
calculated as the difference in time between the killtime and time to send:
and if the time to send is not specified, then
faxalter uses the
current time instead of querying the server for the job's time to send.
faxalter suspends a job before attempting to alter its state. If a job is
active when a suspend request is made there may be a delay while waiting for
the job to enter a consistent state where it can be suspended. If
faxalter is interrupted during this time then jobs may be left
suspended.
faxalter requeues the job. This means that the job will end up at the
bottom of the queue for the job's priority. Thus, when queues are heavy an
adjustment of the job's killtime may need to be considered when altering any
other parameter.
faxalter only understands how to alter a subset of the available job
parameters; there are many more client-controllable parameters that can only
be modified by communicating directly with the server using the underlying
protocol.
The continued use of the
at(1)-style notation for specifying times is
questionable (it was done for backwards compatibility).
SEE ALSO¶
hylafax-client(1),
sendfax(1),
faxrm(1),
faxstat(1),
hfaxd(8)