NAME

XAS::Lib::Batch::Job - A class for the XAS environment

SYNOPSIS

 use XAS::Lib::Batch::Job;

 my $job = XAS::Lib::Batch::Job->new();

 my $id = $job->qsub(...);
 
 printf("job %s has started\n", $id);

 while (my $stat = $job->qstat(-job => $id)) {

     if ($stat->{job_state} eq 'C') {

         printf("job %s has finished\n", $id);

     }

     sleep 10;

 }

DESCRIPTION

This module provides an interface for manipulating jobs in a Batch System. Each available method is a wrapper around a given command. A command line is built, executed, and the return code is checked. If the return code is non-zero an exception is thrown. The exception will include the return code and the first line from stderr.

Since each method is a wrapper, there is a corresponding man page for the actual command. They should also be checked when problems arise.

METHODS

new

This method initializes the module and takes these parameters:

-interface

The command line interface to use. This defaults to 'XAS::Lib::Batch::Interface::Torque'.

qsub(...)

This method will submit a job to the batch system and returns the jobs ID. It takes the following parameters:

-jobname

The name of the job.

-queue

The queue to run the job on.

-email

The email address to send status reports too. There can be more then one address or this can be a mailing list.

-command

The command to run.

-jobfile

The name of the job file to use. This needs to be a Badger::Filesystem::File object.

-logfile

The log file to use. This needs to be a Badger::Filesystem::File object.

-rerunable

Wither the job is rerunnable, this is optional and default to no.

-join_path

Wither to join stdout and stderr into one log file, this is optional and defaults to 'oe'.

-account

The optional account to run under.

-attributes

The optinal attributes that may be applied to this job. This should be a comma seperated list of name value pairs.

-environment

The optional environment variables that may be defined for the job. This should be a comma sperated list of name value pairs.

-env_export

Wither to export the users environment.

-exclusive

The option to run this job exclusivily. Default is no.

-hold

The option to submit this job in a hold state.

-resources

Optional resources to associate with this job. This should be a comma seperated list of name value pairs.

-user

The optional user account to run this job under.

-host

The optional host to run this job on.

-mail_points

The optional mail points that the user will be notified at. Defaults to 'bea'.

-after

The optional time to run the job after. This must be a DateTime object.

-shell_path

The optional path to the jobs shell. Defaults to /bin/sh.

-work_path

The optional path to put work files. This must be a Badger::Filesystem::Directory. Defaults to /tmp.

-priority

The optional priority to run the job at. Defaults to 0.

qstat(...)

This method returns that status of a job. This status will be a hash reference of the parsed output on stdout. It takes the following paramters:

-job

The ID of the job, as returned from submit().

-host

The optional host that the job may be running on. Defaults to 'localhost'.

qdel(...)

This method will delete a job. It takes the following parameters:

-job

The ID of the job, as returned from submit().

-host

The optional host that the job may be running on. Defaults to 'localhost'.

-force

Wither to force the jobs deletion. Defaults to no.

-message

The optional message to be placed into the log file.

qsig(...)

This method will send a signal to a job. It takes the following parameters:

-job

The ID of the job, as returned from submit().

-host

The optional host that the job may be running on. Defaults to 'localhost'.

-signal

The signal to send to the job.

qhold(...)

This method will place a job into a hold status. It takes the following parameters:

-job

The ID of the job, as returned from submit().

-host

The optional host that the job may be running on. Defaults to 'localhost'.

-type

The type of hold to place on the job. They can be any of the following:

   user, other, system, none
 

If more then one type is used, they need to be comma seperated.

qrls(...)

This method will release a job that was placed into a hold status. It takes the following parameters:

-job

The ID of the job, as returned from submit().

-host

The optional host that the job may be running on. Defaults to 'localhost'.

-type

The type of hold to place on the job. They can be any of the following:

   user, other, system, none
 

If more then one type is used, they need to be comma seperated.

qmove(...)

This method will move a job from one queue to another. That queue may exist on another host. It takes the following parameters:

-job

The ID of the job, as returned from submit().

-queue

The queue to move the job too.

-host

The optional host that the job may be running on. Defaults to 'localhost'.

-dhost

The optional destination host that the queue is on.

qmsg(...)

This method will place a message into the log file of a job. It takes the following parameters:

-job

The ID of the job, as returned from submit().

-host

The optional host that the job may be running on. Defaults to 'localhost'.

-message

The message to be used.

-output

The log to place the message, It can be one of the following:

    E - stderr
    O - stdout

qrerun(...)

This method will attempt to rerun a job. It takes the following parameters:

-job

The ID of the job, as returned from submit().

-host

The optional host that the job may be running on. Defaults to 'localhost'.

qalter(...)

This method will alter the parameters of a job. It takes the following parameters:

-job

The ID of the job, as returned from submit().

-host

The optional host that the job may be running on. Defaults to 'localhost'.

-jobname

This will change the jobs name.

-rerunable

This will change the jobs rerunable status.

-email

This will change the jobs email destinations.

-account

This will change the jobs account.

-attributes

This will change the optional job attributes.

-exclusive

This will change wither the job has exclusive access to the server.

-resources

This will change the jobs optional resources.

-user

This will change the jobs user.

-mail_points

This will change the jobs mail points.

-shell_path

This will change the jobs shell.

-hold

This will hold the job.

-join_path

This will change the jobs join path.

-after

This will change the time that job will run after.

-out_path

This will changes the jobs output path, it must be a Badger::Filesystem::File object.

-error_path

This will changes the jobs error path, it must be a Badger::Filesystem::File object.

-priority

This will change the jobs priority.

SEE ALSO

XAS::Lib::Batch
XAS

AUTHOR

Kevin L. Esteb, <kevin@kesteb.us>

COPYRIGHT AND LICENSE

Copyright (c) 2015 Kevin L. Esteb

This is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0. For details, see the full text of the license at http://www.perlfoundation.org/artistic_license_2_0.