Provided by: hylafax-client_6.0.7-5build1_amd64 bug

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)