In the last chapter we added day skipping to our job.
Our job now prints "Hello World!" every day, except on Saturday and Sunday.

Many jobs though, should only be run between certain hours of the day.
For instance, 8:00 AM to 5:00 PM (bankers hours.)

A couple of new directives allow excluding blocks of time within a day.
-suspend [ date / time specification ]
-resume [ date / time specification ]

For a complete explanation of the arguments to the suspend and resume directives, see the documentation:
-suspend

Let us now expand our job to only run between 8:00 AM and 5:00 PM

# Schedule job to run each hour, between the 8:00 AM and 5:00 PM,
# except Saturday and Sunday,
{
# Name our job
-name my job

# Start now and increment the hour field.
# This will cause the job to fire each hour starting now
-start -inc 0 1 0 0

# Skip Saturday and Sunday
-skip -week 7,1

# Suspend all processing before 8:00 AM
# (Start suspending at 12:00 AM and resume at 8:00 AM)
-suspend -time 12:00:00 AM
-resume -time 8:00:00 AM

# Suspend all processing after 5:00 PM
# This suspension will run until the 24 hour clock
# rolls-over at 12:00 AM
-suspend -time 5:00:00 PM

# if it is between 8am and 5pm, do our job.
# Print Hello World!
# (Or do whatever real work you wish)
-action -print "Hello World!"
}

Now because the suspend and resume directives use a reference counter, it is easy to have multiple exclusion blocks per a job, as well as nested exclusion blocks. (If you don’t know what I’m talking about, it’s ok, you probably don’t need this advanced functionality anyway.)

Chapter D – Running only during certain hours, Part II

Both -suspend and -resume are interesting and powerful features, and therefore warrant a bit more discussion.

The documentation for -suspend and -resume claim that a suspend count is maintained and that the -suspend directive increments the count and that the -resume decrements the count.
This is fine. But wouldn’t this mean that the calls to -suspend and -resume must be balanced?
Well, not exactly.

You see, the suspend count is calculated, used, and discarded each time the job is considered.
This keeps unbalanced -suspend and -resume pairs from stacking up large suspend counts (either positive or negative.)
So it’s not strictly necessary to keep the two paired.

Lets look more closely at the example code at the top of this chapter:

##
# The following three statements insure a job will only fire between
# 8:00 AM and 5:00 PM (Bankers hours)
##
-suspend -time 12:00:00 AM
-resume -time 8:00:00 AM
-suspend -time 5:00:00 PM

Given the above instructions, lets evaluate a few example cases to see what happens:

Its 6:00 PM and the WinCron engine is evaluating the job to see if it should fire.
The engine first loops over all the -suspend directives to see which ones are <= the current time. If a -suspend time is <= the current time, the suspend count is incremented.
So, in the case where it’s 6:00 PM, both -suspend directives apply. I.e.,
6:00 PM is greater than both 12:00 AM and 5:00 PM.

Our suspend count at this point is 2.

The engine now loops over all the -resume directives to see which ones are <= the current time. If a -resume time is <= the current time, the suspend count is decrement.
In this case, the -resume at 8:00 AM applies, decrementing the suspend count by 1, but still leaving the suspend count = 1 and therefore leaving the system suspended.

Here’s the pseudo code:

Current time = 6:00 PM;
// first increment the suspend count
If (12:00 AM <= current time) then suspend count = suspend count + 1
If (5:00 PM <= current time) then suspend count = suspend count + 1

// Now decrement the suspend count
If (8:00 AM <= current time) then suspend count = suspend count - 1

Result: The suspend count = 1 and therefore the system is suspended.

Let’s try another one:

Current time = 4:00 PM;
// first increment the suspend count
If (12:00 AM <= current time) then suspend count = suspend count + 1
If (5:00 PM <= current time) then suspend count = suspend count + 1

// Now decrement the suspend count
If (8:00 AM <= current time) then suspend count = suspend count - 1

Result: The suspend count = 0 and therefore the system is not suspended.

So you can see that using -suspend and -resume are very powerful and can be used to finely tune the granularity of job execution.

See the sample scripts that ship with WinCron for examples of -suspend and -resume.