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)

                                                  July 11, 1996                                      FAXALTER(1)