Langue: en

Version: Mar 27, 2006 (mandriva - 22/10/07)

Section: 8 (Commandes administrateur)


jobcontrols - per-job controls for HylaFAX servers


The HylaFAX configuration parameter JobControlCmd specifies the script that is used to apply per-job controls on job characteristics such as the time-of-day to place a call.

The controls program is passed the respective job ID number as the first and only argument.

The controls program should produce a simple line-based ASCII output containing a series of records of the form:

param: value

which is parsed the same manner as all HylaFAX config files. Parameter values are parsed exactly as specified in hylafax-config(5F); i.e. values with embedded whitespace may be enclosed in quote marks (``"'').

All output on a line following a ``#'' character is ignored.

The output order is important. The last parameter value in the output overrides any previous values in the output. Otherwise a default value is used from the faxq configuration file.

The following parameters may be output on a per-job basis; consult hylafax-config(5F) for a description of each parameter (except Modem, Priority, and RejectNotice which are described below).

 Tag                   Type       Default        Description
 MaxConcurrentCalls    integer    1              max concurrent jobs to process for a destination
 MaxDials              integer    unlimited      max phone calls to make to transmit a job
 MaxSendPages          integer    unlimited      max pages to permit in a send
 MaxTries              integer    3              max attempts to transmit a job
 Modem                 string     Any            ModemGroup to use for destination
 Priority              integer    -              priority to use for job
 RejectNotice          string     -              rejection notice for transmit job
 TimeOfDay             string     Any            default time-of-day restrictions
 VRes                  integer    -              Vertical resolution
 UseXVRes              integer    -              Usage of extended resolutions

The Modem parameter controls which ModemGroup is used in sending faxes to the destination. If the user assigns a ModemGroup for a specific job where all modems are outside of this ModemGroup matching a destination, then the value of Modem is overridden by the user's assignment. Likewise, if the user assigns a ModemGroup for a specific job where some, but not all, of the modems are included in this ModemGroup matching a destination, then the value of Modem is overridden by the inclusive set of modems found in both.

The Priority parameter controls the priority to assign to the job. This overrides any priority requested by the submitter.

The RejectNotice parameter controls whether or not to reject jobs to the destination. Jobs that are rejected are done so without placing a phone call and the associated message is returned to the job submitter. This facility can be used to disallow calling sensitive phone numbers; for example

     RejectNotice: "Calls to emergency numbers are not permitted"

The VRes parameter controls the vertical resolution. Possible values are 98 (normal resolution, equivalent to sendfax -l option) and 196 (fine resolution, equivalent to sendfax -m option).

The UseXVRes parameter is used to enable or disable the usage of extended resolutions supported by the receiver. Possible values are 1 (enable extended resolutions usage, equivalent to sendfax -G option) and 0 (disable extended resolutions usage). This parameter supersedes the usage of VRes.

In addition to the above parameters, any other parameters that are specified are automatically accumulated and passed to programs invoked by faxq, such as faxsend and pagesend. (Note that in a batched-jobs instance that these parameters will apply to all jobs in the batch.) This is a convenient mechanism for defining configuration parameters for all modems without having to modify each modem-specific configuration file. For example,

     SessionTracing: 0x4f

This mechanism also makes it easy to control transmit-related parameters according to the destination phone number. For example, to disable use of ECM and restrict the transmit speed when placing international phone calls one might use:

     DesiredBR: 3
     DesiredEC: 0
     DesiredDF: 1

The controls program will likely need to refer to the sendq file corresponding to the job in order to obtain information such as the number being dialed, the job owner, or the number of send attempts. For this purpose the parseQfile function has been placed in bin/common-functions to assist in this. For example:

     . etc/setup.cache
     . bin/common-functions
     case "$number-$owner-$tottries" in
         5551212-lee-3) echo "Class1ECMSupport: no";;
         *-sam-*) echo "LocalIdentifier: +1.800.555.1212";;
         911-*) echo "RejectNotice: \"Calls to 911 are not permitted\"";;
     exit 0


JobControlCmd is run each time the job moves into the run-queue ("READY" state), and all output is effective on each instance. If the administrator wishes to vary output based on the attempt sequence, then the q-file values should be consulted in the process. Furthermore, blind usage of options such as Priority could be confusing as it would essentially prevent a job from increasing or decreasing in job priority as usually expected after call attempts.


faxq(8C), hylafax-config(5F), re_format(7).