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)