faxalter

FAXALTER(1)                  General Commands Manual                 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 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
       /usr/lib/fax/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(8C)



                                  July 11, 1996                      FAXALTER(1)