Schedule Maintenance Operation

$worker_box infobox

This command allows the system administrator to implement regularly-scheduled system maintenance operations, using CopiaFacts to launch a sequence of infobox commands. We recommend not employing this command on a 'live' system until the sequence of infoboxes has been thoroughly tested, because unpredictable results may occur if your infobox commands perform unsupported operations or do not terminate correctly.

This command is used in place of the $email_address, $fax_phone, $voice_phone and $poll_phone commands, which must not appear in the same .FS file. The .FS file must contain a suitable $fax_user command.

The parameter on this command is used as follows:

infobox specifies the infobox to transfer to start the maintenance operation

To use Worker Boxes you must first configure one or more CopiaFacts lines to handle worker operations.  This is done using the CopiaFacts configurator (CFHWL) to set up a line with 'Ops. with no voice/fax' under 'Other Board / E-mail Interface'  and checking 'Internal Admin Tasks' on the right hand side of the lines page. You may either create lines only for this purpose or you may add these settings to an existing fax or voice line, or e-mail thread.  The latter is recommended.  Worker boxes have no access to voice or fax resources and errors will occur if you visit a state which depends on such resources in your infobox sequence.

The Worker Box processing is initiated by placing a 'worker box' FS file in a TOSEND folder.  You can create the worker box either by using an editor such as COPIAEDIT or Notepad, or by generating it from another infobox sequence using a $type fsfile infobox.

There are three main ways of using a worker box: either as a single-shot operation, or repetitive operations controlled either by schedule or by explicit interval settings.  These methods are used as follows:

Single-shot worker box

In this scenario no schedule restrictions should be made on the COPIAFACTS lines page for the 'worker' operation type. Worker boxes will start execution when they are ready to be processed.

When you create a Worker FS file to initiate your task, it will normally be initiated as soon as it is found in the TOSEND folder in which you have placed it.  However you may include a $fax_send_date and/or $fax_send_time command to specify when it is to be initiated.

At the end of your infobox sequence you must transfer to state KILL_MAINT_OP (128).  This will ensure that the maintenance operation will only be performed on a single occasion.

Example:

FS file to cause an operation to be done at 7 pm today:

$worker_box startop

$fax_user @ffuser\fax.usr

$fax_send_time 19:00:00

Infobox operation to perform:

; file startop.iif

$type query

$run "cmd /c mybatch.cmd"

$next_box s:KILL_MAINT_OP

Repeated Worker Box controlled by schedule

In this scenario you should assign one or more CopiaFacts lines to handle worker operations, as described above. But in addition you should schedule these lines using the COPIAFACTS lines page to select a single quarter-hour period (in each day, or in each week) in which the worker line operation is enabled.

The worker box you create will run only in this one quarter-hour period.  It should not include any $fax_send_date or $fax_send_time commands.  If you have multiple tasks to perform, they must all be done in the selected period, which makes this method less flexible than the one described next.

It is possible to schedule a quarter-hour period every day, but then to process certain operations weekly by conditioning on the @DOW day-of-week value in your infobox sequence. See the example that follows.

At the end of your infobox sequence you must transfer to state FINISH_MAINT_OP (129).  This will ensure that the FS file is written back to the same TOSEND folder to be performed on the next occasion (e.g. the next day or the next week) that the single quarter-hour period is reached.
Values of variables you set in your infobox sequence will be preserved in the FS file.  So you should not expect them to be empty each time, and unless you actually intend to preserve a value such as a counter or a status, you may need to use $set_var to assign @EMPTY to the variable at the start of the sequence.

Example:

FS file to cause repeated operations to start:

$worker_box startop

$fax_user @ffuser\fax.usr

Infobox sequence to select daily, weekly or monthly operations:

; file startop.iif

$type decision

$set_var DAY @DATE2 1 2 ; collect DD from date

$if @DAY = 1

  $next_box monthly  ; infobox to run every month

$elseif @DOW = 7 ; Saturday

  $next_box weekly

$else

  $next_box daily

$endif

; file monthly.iif

$type decision

  ... monthly task

$if @DOW = 7  ; Saturday

  $next_box weekly

$else

  $next_box daily

$endif

; file weekly.iif

$type decision

   ... weekly task

$next_box daily

; file daily.iif

$type decision

  ... daily task

$next_box s:FINISH_MAINT_OP

Repeated Worker Box controlled by specified interval times

In this scenario you should assign one or more CopiaFacts lines to handle worker operations, as described above.  The line schedule must be left open so that worker boxes can be run at any time.  The scheduling of worker box execution is done by means of the $fax_send_date and/or $fax_send_time commands, coupled with setting either the control variable WORKER_DAY_INTERVAL or the control variable WORKER_MINUTE_INTERVAL.  It is an error to set both of these variables.

At the end of your infobox sequence you must transfer to state FINISH_MAINT_OP (129).  This will ensure that the FS file is written back to the same TOSEND folder to be performed after the specified interval.
Values of variables you set in your infobox sequence will be preserved in the FS file.  So you should not expect them to be empty each time, and unless you actually intend to preserve a value such as a counter or a status, you may need to use $set_var to assign @EMPTY to the variable at the start of the sequence.

Examples:

To set a worker box to run at 5pm every day:

$worker_box daily5      ; use infobox daily5.iif

$fax_user @ffuser\fax.usr

$fax_send_time 17:00:00          ; always start at 5pm

$var_def WORKER_DAY_INTERVAL 1   ; start every day

To set a worker box to run at 5pm every week:

$worker_box weekly5      ; use infobox weekly5.iif

$fax_user @ffuser\fax.usr

$fax_send_time 17:00:00         ; always start at 5pm

$var_def WORKER_DAY_INTERVAL 7  ; run at weekly intervals

To set a worker box to run at noon every Sunday:

$worker_box sunday       ; use infobox sunday.iif

$fax_user @ffuser\fax.usr

$fax_send_date ..........       ; enter the date next Sunday

$fax_send_time 12:00:00         ; always start at 12pm

$var_def WORKER_DAY_INTERVAL 7  ; run at weekly intervals

To set a worker box to run at 1 am every month, starting on 1st December 2006:

$worker_box monthly1     ; use infobox monthly1.iif

$fax_user @ffuser\fax.usr

$fax_send_date 12/01/2006

$fax_send_time 01:00:00          ; always start at 5pm

$var_def WORKER_DAY_INTERVAL 31  ; increment month

To set a worker box to run every twenty minutes:

$worker_box twenty       ; use infobox twenty.iif

$fax_user @ffuser\fax.usr

$var_def WORKER_MINUTE_INTERVAL 20

Notes

The worker box mechanism using the ..._INTERVAL control variables will write $fax_send_date and $fax_send_time commands into the FS file when it is written back for re-submission. These commands control when the FS file is next available for processing. Note that on a busy system the FS file may not be selected for processing until after the specified time.

If WORKER_DAY_INTERVAL is defined and no $fax_send_time command is present in the FS file, the $fax_send_time will be set to the time at which the FS file is first processed, and will remain set to this time as each daily interval proceeds.

If WORKER_MINUTE_INTERVAL is defined the existing $fax_send_date and $fax_send_time commands in the FS file are ignored and the new generated $fax_send_date and $fax_send_time commands are based on the current date and time at which the FS file is processed.

The WORKER_DAY_INTERVAL can be any value between 1 and 31.  Values over 28 are special and cause the month of the fax send date (if initially specified) to be incremented by one and the day to remain unchanged.  Values of 28 and below cause the current date to be incremented by the specified interval and used as the next send date.  Selecting a day interval of 31 and an  initial starting date of later in a month than the 28th will cause the starting date to be changed to the 28th.

The WORKER_MINUTE_INTERVAL can be any value between 1 and 1439.

To terminate a repeating infobox sequence, either delete the FS file or arrange to transfer to state KILL_MAINT_OP instead of FINISH_MAINT_OP.  The schedule of a specific worker box can be amended at any time (except while it is actually being processed) by editing the FS file in COPIAEDIT or Notepad.

If no CopiaFacts node is available to process the workerbox FS file, it waits until one is available and only runs once, after which it is rescheduled (if specified) following the normal rules.  If you wish to know how many times the task has been executed, assign an initial value in the FS file ($var_def WORKCOUNT 0) and then increment it in the IIF file ($set_var WORKCOUNT +1). The incremented variable will be written back to the FS file ready for the next scheduled operation.