FAXALTER(1)
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 sub-
mitted to HylaFAX; these numbers are printed by sendfax(1)
when jobs are queued for transmission and can also be dis-
played with faxstat(1). Unprivileged users can alter the
parameters of jobs that they own; clients with administra-
tive privileges on a server can manipulate any job. 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)).
-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.
-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 sent immediately (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 pri-
ority. The default scheduling priority for a
job is 127 and priorities are recalculated after
each attempt to process a 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 informa-
tion is written to the standard output.
CONFIGURATION PARAMETERS
faxalter reads configuration information from the file
/usr/local/lib/fax/hyla.conf and then from the file
~/.hylarc. Configuration files follow the conventions
described in hylafax(1). The following configuration
parameters are recognized:
Tag Type Default Description
Host string localhost host to contact for service
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.)
Port The network port to contact for service.
(Eqvuialent 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.)
BUGS
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 sus-
pended.
faxalter only understands how to alter a subset of the
available job parameters; there are many more client-con-
trollable parameters that can only be modified by communi-
cating directly with the server using the underlying pro-
tocol.
The continued use of the at(1)-style notation for specify-
ing times is questionable (it was done for backwards com-
patibility).
SEE ALSO
hylafax(1) sendfax(1) faxrm(1) faxstat(1) hfaxd(8C)