faxalter - alter parameters of a HylaFAX
job queued for transmission
changes the state of one or more HylaFAX
are queued for transmission.
Numerous parameters can be altered; see the options below.
is a number that identifies a
that has been submitted to HylaFAX; these numbers are printed by
when jobs are queued for transmission and can also be displayed with
Unprivileged users can alter the parameters of jobs that they own; clients
with administrative privileges on a server can manipulate any job (see the
The user may be specified by the
environment variable. By default,
contacts the facsimile server on the host specified in the
environment variable; but consult the
option for more information.
- -a time
Specify a new time to send a job.
The syntax for specifying a time is the same as used
- -C command
Issue the raw
as a line to the server.
- -d destination
Change the destination number to
- -h host
Force the server to be contacted on a specific
may be either a symbolic name or a network address.
IPv6 addresses are given in ``[xx:xx::x]:port'' format.
option is supplied,
environment variable to identify the HylaFAX server to contact.
If this variable is not set, then
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
attempts to contact a server on the machine where it is run.
Use administrative privileges;
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
- -m modem
Assign/reassign the jobs to the specified
Specifying ``any'' for
causes the jobs to be scheduled for any available modem.
Do not suspend or submit the job. This may be typically used in conjuction with
to query job details.
- -O config
as a configuration parameter specification that is interpreted
after reading the configuration file.
For example, ``-O Host:fax.example.com'' would set the
configuration parameter to ``fax.example.com'', overriding any setting in
the configuration file.
The jobs should be
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.
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
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.
options are shorthand for these notification schemes,
One can also leave off ``when'' when using the
option; e.g., ``done'' instead of ``when done''.
- -u user
Specify the login user name.
- -U pass:adminpass
Specify the login password and optionally the admin password preceded by a colon.
Trace the protocol exchanges between
and the remote
Tracing information is written to the standard output.
reads configuration information from the file
and then from the file
Configuration files follow the conventions described in
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:
The host to contact for service.
(Equivalent to the
Whether or not to use passive mode in communication with the server.
The network port to contact for service.
(Equivalent to the
The name of the communication protocol to use when contacting a server.
(Equivalent to the
Control protocol tracing.
(Equivalent to the
On complete success
returns 0. If there is a user-supplied syntax error then 1 is returned.
If a login to the server was unsuccessful then 2 is returned. If
some client-server job processing error occured then
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
uses the current time instead of querying the server for the
job's time to send.
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.
is interrupted during this time then jobs may be left suspended.
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.
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
notation for specifying times is questionable (it was done for