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 out-
		 put.

       -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 fax-
       alter 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)