Basic xgrid Syntax

If you type man xgrid from within the Terminal application, you see an illustration of the syntax for the command-line tool. The first few lines are shown in Listing 3-1.

Listing 3-1  Excerpt from the xgrid man page

SYNOPSIS

        xgrid [-h[ostname] hostname] [-auth { Password | Kerberos }] [-p[assword] password]

        xgrid -job run [-gid grid-identifier] [-si stdin] [-in indir] [-so stdout] [-se stderr] [-out outdir]

        [-email email-address]

       cmd [arg1 [...]]

       xgrid -job submit [-gid grid-identifier] [-si stdin] [-in indir] [-dids jobid [, jobid]*]

       [-email email-address]

       cmd [arg1 [...]]

The first parameter is -h, followed by the host name or IP address of the controller.

Example: xgrid -h localhost

You can optionally include a method of authentication and a password.

The next parameter of interest is the job specification. You can either run a job synchronously, by passing -job run, or submit a job for asynchronous execution by passing -job submit. In either case, you must then specify a grid, and can optionally redirect the standard input and output.

If you submit a job asynchronously, rather than running it synchronously, you can include an email address to be notified when the job terminates.

Running a Job Synchronously

Here’s a very simple example that runs the cal program using a controller on the local host:

Listing 3-2  Running a job synchronously

xgrid -h localhost -job run /usr/bin/cal 2007

By specifying the full path, you prevent the executable file from being copied to the agent. Instead, it is run in place at the specified path location. No working directory is created.

By specifying run instead of submit, you tell xgrid to execute the command synchronously. The command line returns nothing until the job is complete.

Since the optional input and output specifications have been omitted, standard output is used for the results.

Submitting a Job for Asynchronous Execution

Now let’s look at a more complex example. It submits the file myscript with a group of files in an input directory. An email address is passed that will be used to notify someone at every job state change. The results are saved in files in an output directory, then the job is deleted:

Listing 3-3  Submitting a job asynchronously

$ xgrid -job submit -in ~/data/working -email somebody@apple.com myscript param1 param2

          { jobIdentifier = 27; }

          $ xgrid -job results -id 27 -so job.out -se job.err -out job-outdir

           $ xgrid -job delete -id 27

In this example, xgrid is told to execute the job asynchronously by passing submit instead of run.

Use the -in parameter to pass an input directory. This directory is copied to each agent and becomes the working directory on the agent’s host computer. You can include anything needed in the working directory, such as additonal input files, libraries, and executables. The executable file is run in this directory.

Next, specify the script to run, along with any input parameters. This completes the first line of input.

A job identifier is returned.

The next line of the example uses the job identifier to assign file names for the standard output, standard error, and job output for this particular job.

The last line deletes the job.

Submitting a Batch Job

Here’s how to submit a batch job, consisting of multiple tasks. If enough agents are available, all of the tasks are performed simultaneously. Otherwise, each available agent is assigned a task and the first agent to finish is assigned another task, and so on until all the tasks have been completed.

To submit a batch job, you must include a property list file, describing each task to be performed. The man page for xgrid describes the structure of the property list file, but here’s a helpful shortcut—submit each individual task as its own job initially, and let xgrid generate the property list file for you. When the task completes, you can retrieve the property list file. You can edit the list to modify a task, duplicating it as necessary, or concatenate the property list files of several tasks into one batch.

For example, if you submit the cal program as a job, it looks like this:

xgrid -job submit /usr/bin/cal  6 2007

The xgrid command returns a job ID. When the job completes, you can use the job identifier to retrieve the complete job specification, including the property list:

xgrid -job specification -id n

{

    jobSpecification = {

        applicationIdentifier = "com.apple.xgrid.cli";

        inputFiles = {};

        name = "/usr/bin/cal";

        submissionIdentifier = abc;

        taskSpecifications = {

            0 = {arguments = (6, 2007); command = "/usr/bin/cal"; };

       };

   };

}

Copy the returned job specification and save it using the .plist file suffix. You can then submit the file to Xgrid as part of a batch job specification. If the example above were named batch.plist, you could submit the job like this:

xgrid -job batch batch.plist

Before going any further with Xgrid programming, try breaking up your job into executable tasks and submitting them using the xgrid command-line utility. The experience will provide a great deal of useful information to you about how to plan and execute your program.