In this chapter, we cover the subroutine.

WinCron subroutines work much like you would suspect. That is, one job calls another job ‘by name’ to run immediately.

Example:

##
# Reschedule a job to run every day and print "Hello World!"
{
# Name our job
-name my job

# Start now and increment the day field.
# This will cause the job to fire NOW, and tomorrow at the same time
-start -inc 1 0 0 0

# Call a subroutine to print "Hello World!"
-action -call hello_world_job
}

##
# This is the hello_world subroutine.
# This job neither takes nor modifies any global parameters
{
# Name our job will be ‘called’ by
-name hello_world_job

# Print Hello World!
# (or do whatever work you like)
-action -print "Hello World!"
}

So that’s it. Pretty simple really.
Called jobs may reside in the same script file as the caller, or in another script file. The interpreter resolves the reference dynamically at the time the job is called.

The last thing to mention is the -return directive.
While you have several options for returning from a job, none are very interesting until we start using subroutines for exception handling.

But basically, a return is usually the last directive in a subroutine. The return instructs the WinCron interpreter on how to proceed. The list of actions are: continue, stop, break and abort. These are the same actions that are allowed for onerror. The default action is continue if no -return directive is specified.

Please see the section on Using subroutines for exception handling for the full description of return types.

Example II: Using environment variables to communicate with subroutines.

##
# Reschedule a job to run every day and print "Hello World!"
{
# Name our job
-name my job

# Start now and increment the day field.
# This will cause the job to fire NOW, and tomorrow at the same time
-start -inc 1 0 0 0

# set an environment variable with the string to print
-action -set OUTPUT= "Hello World!”

# Call a subroutine to print "Hello World!”
-action -call hello_world_job
}

##
# This is the hello_world subroutine.
# This job takes prints the environment variable OUTPUT
{
# Name our job will be ‘called’ by
-name hello_world_job

# Print Hello World!
# (or do whatever work you like)
-action -print %OUTPUT%
}