Description

With Futurama Console it is possible to execute batch jobs, which are modelled in a Futurama application, without the need to open the interface of the Futurama Editor. This is particularly useful when actions are involved that have to be executed many times, for example for a large set of participants. This normally takes up a lot of time while the Editor is not needed at all. Examples include making calculations for a large number of participants or generating a great many, individually tailored, documents. Because of the sheer length this kind of actions are often performed overnight. The results can then be processed further the following day.

A batch job is normally started by executing a command from either a .bat-file or from the DOS-prompt.

Executing commands

Commands are executed by a double-click of a .bat-file containing the command. It is, however, also possible to execute a command from the Dos prompt. The syntax is the same. In the .bat-file consecutively the path to the Futurama Editor followed by a sequence of arguments have to be stated. An example of the contents of a batchfile:

"C:\Program Files\Futurama\ActuIT.Futurama.Editor.exe" -b -fC:\inetpub\wwwroot\Futurama\Planner\website.xml -a1234

There are two locations where parameters can be set that have an impact when running jobs:

• Environment specific parameters: these parameters are located in the appSettings section of a configuration file (see for example 'Installation Futurama Editor'). This is the place to store connection strings, server names, file paths and other miscellaneous settings that can be used by a Futurama application. The items inside the appSettings are items that need to be configurable depending upon the environment. The parameters located in the in the config can be read using the Formula ReadConfigKey.
• Job specific parameters: these parameters (also known as arguments) are set when running the batch job. A number of arguments are available for running individual jobs. Futurama has a set of reserved Command Line Arguments. In addition it is possible to define custom arguments.

Reserved Command Line Arguments

Futurama intrinsically knows the following reserved Command Line Arguments: 

-f<filename>: states the name of the Futurama Document that has to be used. If the filename contains spaces then the name has to be surrounded by quotes. It is allowed to precede the filename by a path.

-b: adding this argument ensures that Futurama is opened in Batch modus (without the Futurama editor) interface.

-a<path to action>: this argument is only used when the argument -b is also used. It states the path to the Action that has to be executed. This Action can be located in either the Document itself or in a SubDocument of this Document. If the Action is located in the Document itself then the path to the Action is the same as the ID of the Action. For example, if the ID of the Action, that has to be executed, is 3 then the argument has to be -a3. If the Action is located in a SubDocument of the Document then the path is equal to the ID of the SubDocument followed by an underscore and the ID of the Action. For example, if the Action with ID=3 is located in a SubDocument which has ID=4 then the argument has to be -a4_3. If the Action is located in a SubDocument of a SubDocument of the Document then the path is extended in a similar way.

-u -l<path to file>: using this combination of arguments makes it possible to update Futurama Documents to a new version. The argument -u denotes that the update mode is used. The -l argument has to be followed by the path to the txt-file which contains the directorie(s) whose contents have to be updated.

Note: the arguments have to be separated only by a space and not by Enters. Otherwise the batch-file will not work.

Custom Command Line Arguments

Aside from the reserved Command Line Arguments it is possible to define custom arguments. Using these arguments additional parameters can be set in the application and used while running the batch job. To be able to use the values of custom arguments the application has to be able to 'read them. This can be accomplished by using the Formula ReadRequestParameter.

As an example of using custom arguments, suppose 10000 calculations have to be executed and it is decided to split these over two computers. Computer 1 is to be used for the first 5000 calculations while computer 2 is to be used for the final 5000 calculations. By defining the arguments -begin and -end it is possible to 'tell' the application which calculations have to be made. In the Futurama Document two Formulas ReadRequestParameter have to be defined to read the values of 'begin' and 'end' and a loop has to be constructed that loops from 'begin' to 'end'. By deploying the application to the two computers the arguments can be used to determine which calculations have to be executed on each. Computer 1 will then have -begin=1 and -end=5000 while computer 2 will use -begin=5001 and -end=10000.

The following notes apply to the use of custom arguments:

• the number of arguments is unlimited;
• except for the reserved arguments all names can be used to define an argument, but only letters and numbers are allowed;
• it is not obligatory to give an argument a value. If no value is given, the result of the Formula ReadRequestParameter will then be empty. Of course the application should not crash because of this.

Futurama Server

Running batch jobs is made even more convenient when making use of the module Futurama Server. Futurama Server provides a way to run batch jobs (also known as tasks) that take a long time in a way that allows the user to monitor the progress (in the Vision Management Site) as well as to stop the task.

Generating logfiles

While running a batch job it is often convenient to keep track of any errors and warnings that might occur. In addition it can be very handy to write custom messages to the log while running the job for example to keep track of the progress of the job. There a number of ways to accomplish this:

• Making use of the logging functionality of Futurama. Note that when running batch jobs the configuration file of the Editor is used. This file can be found in the same directory as the executable of the Editor.
• Custom messages can be created using LogMessages.
• When the command is run directly from the Command prompt i.e. not with a .bat file, it is possible to log the result of a batch job by logging to a textfile. This can be accomplished by adding '>>' followed by a desired filename e.g. '>>log.txt' to the command. Note that information in this logfile is not as detailed as when using the Futurama logging.

Resultcodes

After running a batch job it is possible to see whether errors and/or warnings have occured by verifying the so called Resultcode. The Resultcode can have a number between 0 and 3:

0 = no errors, no warnings have occured

1 = no errors, but warnings have occured

2 = errors, no warnings have occured

3 = errors and warnings have occured

The following code is an example of running a batch job followed by a message that informs the user of the outcome. Note that the path of the executable, the name of the document and the ID of the Action are fictional and will have to be replaced by the real values. Furthermore, the text of the messages can be altered to suit the users purpose.

REM----------BEGIN-----------

"C:\PathToFuturama\ActuIT.Futurama.Editor.exe" -fC:\PathToFile\document.xml -b -a4

@ECHO OFF

IF errorlevel 3 GOTO :WARNINGANDERROR
IF errorlevel 2 GOTO :ERROR
IF errorlevel 1 GOTO :WARNING
IF errorlevel 0 GOTO :MESSAGE

:MESSAGE
ECHO No errors or warnings have occured
GOTO :END

:WARNING
ECHO Warnings have occured
GOTO :END

:ERROR
ECHO Errors have occured
GOTO :END

:WARNINGANDERROR
ECHO Warnings and errors have occured
GOTO :END

:END
PAUSE
REM------------END-----------

Related Tutorials

-Creating a Console Application: This tutorial describes the development of a simple console application in Futurama.

-Generating documents: This tutorial describes how to generate multiple, individally tailored, documents with Futurama.

Feedback

If you have any questions about this subject or if you want to provide us feedback please send us an e-mail.