Submission Interface - Usage

Overview

1. Modify your script/tool to call xgSubmit.exe and (optionally) xgWait.exe so that processes whose execution we wish to distribute are queued in the Grid Engine queue.
2. Run the script/tool with xgConsole.exe.

An Example

1. Run the application "Utest.exe" 5 times, each time with different input data. Each run creates an output file with the execution results.
2. When done, run "UReport.exe" which checks the script results and displays a summary report.

Our original script looks like this:

If we could get the script to execute the different "Utest.exe" runs in parallel (utilizing local and remote CPUs) we would achieve a substantial speed-up. Here is the modified version of the .bat file which achieves this using the Submission Interface:

Explanation

• xgSubmit.exe replaces calls to UTest.exe, replacing the standard execution with execution through XGE. Note that the original command line is given as input following the "/command" option, which should always be the last specified option. In this example, all "UTest.exe" calls are assigned the same group name - "UTest".
• xgWait.exe is called before "UReport.exe" is run in order to pause execution of the script until all tasks in the group "UTest" have completed (this is required since "UReport.exe" reads output data created by the "UTest.exe" tool). This makes it possible to define dependencies between different execution parts in scripts.

Running the script using xgConsole.exe

For a comprehensive overview of the xgConsole.exe command line options see this section.

xgSubmit.exe

xgSubmit.exe can be used to submit a single task or a set of tasks specified in a command file (for better performance when submitting a large group of tasks):

Single Task Submission Syntax

Note that the "/command" argument should always be specified last, followed by the command line to be submitted for execution.

Arguments:

• /group - The Group Identifier. If no group identified is given the submitted task will belong to a default group name.
• /wait - when specified, xgSubmit will only return control to the script when the submitted command has completed execution.
• /allowremote=[on|off] - when specified with "off", the submitted task will always run on the machine that initiated the build and will never be distributed to a remote Agent.
• /caption - when used, the specified caption will appear as the caption for the submitted tasks's progress bar in the Build Monitor Progress page.

Command File Submission Syntax

Note that the "/commandfile" argument should always be specified last, followed by the path to the file containing the commands to be submitted.

Arguments:

• /group - The Group Identifier. If no group identified is given the submitted task will belong to a default group name.
• /wait - when specified, xgSubmit will only return control to the script when the submitted command has completed execution.
• /allowremote=[on|off] - when specified with "off", the submitted task will always run on the machine that initiated the build and will never be distributed to a remote Agent.

Important note: Commands specified in the command file are executed independently, and not necessarily in the specified order. In order to create dependencies, use the /group argument in conjunction with xgWait.exe in your script.

xgWait.exe

The usage syntax is:

• /group - The Group Identifier(s) to wait for.
• /exitcode - Exit code for xgWait.exe to return once all tasks have completed. Specify "highest" or "lowest" in order to return respectively the highest or lowest exit code of all codes returned by the task processes, or specify a fixed numeric value.
• /silent - prevents xgWait.exe from writing to the standard output.
• /all - instead of using /group, /all can be used to wait until all tasks have completed.

Notes

• "xgWait.exe /all" is implicitly called at the end of the script/application's execution, in order to allow all tasks submitted with "xgSubmit.exe" to complete before returning control.