1JOBCONTROL(8C)                                                  JOBCONTROL(8C)


6       jobcontrols - per-job controls for HylaFAX servers


9       The  HylaFAX configuration parameter JobControlCmd specifies the script
10       that is used to apply per-job controls on job characteristics  such  as
11       the time-of-day to place a call.
13       The  controls  program  is  passed  the respective job ID number as the
14       first and only argument.
16       The controls program should produce a simple  line-based  ASCII  output
17       containing a series of records of the form:
18              param: value
19       which is parsed the same manner as all HylaFAX config files.  Parameter
20       values are parsed exactly as specified in hylafax-config(5F); i.e. val‐
21       ues with embedded whitespace may be enclosed in quote marks (``"'').
23       All output on a line following a ``#'' character is ignored.
25       The  output order is important.  The last parameter value in the output
26       overrides any previous values in the output.  Otherwise a default value
27       is used from the faxq configuration file.
29       The  following  parameters  may  be  output on a per-job basis; consult
30       hylafax-config(5F) for a description of each parameter  (except  Modem,
31       Priority, and RejectNotice which are described below).
32       Tag                   Type       Default      Description
33       MaxConcurrentCalls    integer    1            max concurrent jobs to process for a destination
34       MaxDials              integer    unlimited    max phone calls to make to transmit a job
35       MaxSendPages          integer    unlimited    max pages to permit in a send
36       MaxTries              integer    3            max attempts to transmit a job
37       Modem                 string     Any          ModemGroup to use for destination
38       Notify                string     -            notification override for job
39       PageSize              string     -            page size to use for job
40       Priority              integer    -            priority to use for job
41       Proxy                 string     -            proxy server to which the job should be delivered
42       ProxyUser             string     -            authentication username for the proxy server
43       ProxyPass             string     -            authentication password for the proxy server
44       ProxyMailbox          string     -            E-Mail address for job notification
45       ProxyNotification     string     none         notification request
46       ProxyJobTag           string     see below    jobtag for proxy job
47       ProxyLogMode          octal      0600         protection to use for logs retrieved from proxy server
48       ProxyTaglineFormat    string     -            impose tagline format for proxy job
49       ProxyTries            integer    -1           number of tries proxy should attempt
50       ProxyTSI              string     -            impose TSI for proxy job
51       ProxyDials            integer    -1           number of dials proxy should attempt
52       ProxyReconnects       integer    5            number of reconnections to proxy for any job submisison
53       RejectNotice          string     -            rejection notice for transmit job
54       RewriteFaxname        string     -            replace faxname in job request with this
55       RewriteFaxnumber      string     -            replace faxnumber in job request with this
56       TimeOfDay             string     Any          default time-of-day restrictions
57       VRes                  integer    -            Vertical resolution
58       UseXVRes              integer    -            Usage of extended resolutions
59       UseColor              integer    -            Usage of color
60       UseSSLFax             integer    -            Usage of SSL Fax
62       The  Modem parameter controls which ModemGroup is used in sending faxes
63       to the destination.  If the user assigns a ModemGroup for a  job  where
64       there  are  no common modems between that ModemGroup and the ModemGroup
65       assigned here by JobControlCmd, then the JobControlCmd value  of  Modem
66       is  overridden by the user's ModemGroup.  Likewise, if the user assigns
67       a ModemGroup for a specific job where some, but not all, of the  modems
68       are  included in this ModemGroup matching a destination, then the value
69       of Modem is overridden by the inclusive set of modems found in both.
71       The Notify  parameter  allows  an  override  of  whatever  notification
72       request the client requested in the job.  Options are ``none'',  ``when
73       requeued'', ``when done'', and ``when done+requeued''.
75       The PageSize parameter controls the page size for the job.  This  over‐
76       rides any page size requested by the submitter.  Page sizes are defined
77       in the pagesizes(5F) database.
79       The Priority parameter controls the priority  to  assign  to  the  job.
80       This overrides any priority requested by the submitter.
82       The  Proxy parameter controls to which host the job should be delivered
83       for transmission.  This should be a hostname  or  IP  address  and  may
84       include  the  modem  group  name  when formatted as the host option for
85       sendfax(1).  The proxy server should have login  access  permitted  for
86       the  originating  server  without a password if ProxyUser and ProxyPass
87       are not also provided.  Caution: actions such as job  removal  and  job
88       modification  (such  as those done by faxrm(1) or faxalter(1)) will not
89       currently propagate to the proxy and is a matter  for  future  develop‐
90       ment.   Therefore,  such  actions  should  be  made on the proxy server
91       directly.
93       The ProxyMailbox and ProxyNotification identify the e-mail address  and
94       the  notification mechanism for the proxied job.  (This does not change
95       the e-mail address or the notification mechanism  for  the  originating
96       job.)
98       The  ProxyJobTag  sets  the jobtag for the job on the proxy server.  By
99       default this is the jobid for the originating job.
101       The ProxyLogMode parameter specifies  the  file  mode  protection  that
102       should  be  used  for  the  logs that are able to be retrieved from the
103       proxy server.  (In order to retrieve logs the proxy server must  permit
104       it.)
106       The ProxyTaglineFormat sets the tagline format for the job on the proxy
107       server.  By default this is whatever was specified by the client.
109       The ProxyTries and ProxyDials parameters specify the number of  respec‐
110       tive  attempts  that  the proxy server should make.  The default is -1,
111       and any value less than 1 indicates that the  proxy  server  should  be
112       delegated all remaining attempts.
114       The  ProxyTSI sets the TSI for the job on the proxy server.  By default
115       this is whatever was specified by the client.
117       The ProxyReconnects parameter specifies  the  number  of  reconnections
118       that  should  be made to the proxy server in the event that the network
119       connection is lost.  Attempts are made no sooner than 60 seconds apart,
120       so to tolerate a network outage of 30 minutes ProxyReconnects should be
121       set to ``30'' or higher.
123       The RejectNotice parameter controls whether or not to  reject  jobs  to
124       the  destination.  Jobs that are rejected are done so without placing a
125       phone call and the associated message is returned to the job submitter.
126       This  facility can be used to disallow calling sensitive phone numbers;
127       for example
128           RejectNotice: "Calls to emergency numbers are not permitted"
130       The RewriteFaxname and RewriteFaxnumber  parameters  allow  the  ``fax‐
131       name''  and  ``faxnumber''  parameters  in  the  job request file to be
132       replaced and rewritten with the given values.
134       The VRes parameter controls the vertical  resolution.  Possible  values
135       are  98  (normal  resolution,  equivalent to sendfax -l option) and 196
136       (fine resolution, equivalent to sendfax -m option).
138       The UseColor parameter is used to enable or disable the usage of  color
139       as  supported  by  the  receiver.  Possible  values are 1 (enable color
140       usage, equivalent to sendfax -O usecolor:yes  option)  and  0  (disable
141       color   usage).   This  parameter  may  be  used  in  conjunction  with
142       DesiredDF: 6 in order to abort fax transmission if  the  receiver  does
143       not support color facsimile.
145       The  UseSSLFax  parameter is used to enable or disable the usage of SSL
146       Fax as supported by the receiver.  Possible values are 1 (enable) and 0
147       (disable).
149       The  UseXVRes  parameter  is  used  to  enable  or disable the usage of
150       extended resolutions supported by the receiver. Possible values  are  1
151       (enable  extended  resolutions  usage, equivalent to sendfax -G option)
152       and 0 (disable extended resolutions usage).  This parameter  supersedes
153       the usage of VRes.
155       In  addition  to  the  above  parameters, any other parameters that are
156       specified are automatically accumulated and passed to programs  invoked
157       by  faxq,  such  as faxsend and pagesend.  (Note that in a batched-jobs
158       instance that these parameters will apply to all jobs  in  the  batch.)
159       This  is  a  convenient mechanism for defining configuration parameters
160       for all modems without having to modify each modem-specific  configura‐
161       tion file.  For example,
162           SessionTracing: 0x4f
164       This  mechanism  also makes it easy to control transmit-related parame‐
165       ters according to the destination phone number.  For example,  to  dis‐
166       able  use  of ECM and restrict the transmit speed when placing interna‐
167       tional phone calls one might use:
168           DesiredBR: 3
169           DesiredEC: 0
170           DesiredDF: 1


173       Change (overlap) MaxDials parameter to 3 for all outgoing calls.
175       1. Create file bin/jobcontrol with the following content:
176          #!/bin/sh
177          echo "MaxDials:
178          exit 0
180       2. Ensure that bin/jobcontrol is marked as executable:
181           chmod +x bin/jobcontrol
183       3. Add  parameter  JobControlCmd  to  hylafax-config(5F);  (etc/config)
184       file:
185           JobControlCmd: bin/jobcontrol
187       The controls program will likely need to refer to the sendq file corre‐
188       sponding to the job in order to obtain information such as  the  number
189       being  dialed, the job owner, or the number of send attempts.  For this
190       purpose the parseQfile function has been placed in bin/common-functions
191       to assist in this.  For example:
193           #!/bin/sh
194           . etc/setup.cache
195           . bin/common-functions
196           QFILE=sendq/q$1
197           SetupPrivateTmp
198           parseQfile
199           case "$number-$owner-$tottries" in
200               5551212-lee-3) echo "Class1ECMSupport: no";;
201               *-sam-*) echo "LocalIdentifier: +1.800.555.1212";;
202               911-*) echo "RejectNotice: \"Calls to 911 are not permitted\"";;
203           esac
204           exit 0


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


217       faxq(8C), hylafax-config(5F), re_format(7).
221                                 Mar 27, 2006                   JOBCONTROL(8C)