NAME

Command.pm - Model a command that is to be executed on the computational grid.

VERSION

This document refers to Command.pm $Revision: 8365 $.

DESCRIPTION

Warning: Do not use this module directly unless you absolutely know what you are doing. Please use the Grid::Request module instead. The POD provided here is purely for documentation purposes only and does not mean that this module should be used directly by end users.

The term DCE, as used in this documentation, shall be taken to mean "Distributed Computing Environment". This term is freely interchangeable with "HTC" (for High Throughput Computing) which you may also see run across.

Overview

This module is not designed for direct use. Please consult the documentation for Grid::Request.

Class and object methods

Grid::Request::Command->new(%args);

Description: This is the object constructor. Parameters are passed to the constructor in the form of a hash. Example:

my $req = Grid::Request::Command->new( opsys => "Linux",
                                       project => "SomeProject",
                                     );

Parameters: Only the project parameter is required when calling the constructor. Remaining parameters can be added with individual method calls.

Returns: $obj, a command object.

$obj->account([account]);

Description: The account attribute is used to affiliate a grid job with a particular account. Grid engines differ in their treatment of the account attribute.

Parameters: To use as a setter, the first parameter will be used to set (or reset) the account attribute for the command.

Returns: The currently set account (if called with no parameters).

$obj->block_size( [ $scalar | $code_ref ] );

Description: By default, Master/Worker jobs have a default block size of 100. That is to say, that each worker on the grid will process 100 elements of the overall pool of job invocations. However, this isn't always appropriate. The user may override the default block size by calling this method and setting the block size to an alternate value (a positive integer). The user may also provide an anonoymous subroutine (code reference) so that the block size can be computed dynamically. If choosing to pass a subroutine , the code will be passed two arguments: the command that will be invoked, and the number of elements that will be iterated over. The subroutine can then use these pieces of information to compute the block size. The subroutine MUST return a positive integer scalar or an exception will be thrown.

Parameters: A positive integer scalar, or an anonymous subroutine/code reference.

Returns: The block size scalar or code reference if called as an accessor (no-arguments). If the block size has not been explicitly set, then the default block size is returned. No return if called as a mutator.

$obj->add_param(@param_args);

Description: This is documented in Grid::Request (Request.pm).

Parameters: Scalar, list or hash, depending on what you are trying to achieve.

Returns: The currently set account (if called with no parameters).

$obj->class([$class]);

Description: This method is used to set and retrieve the command class attribute. Class describes the general purpose for a command or what is will be used for. For example, a command can be marked as a request for "engineering" or "marketing". Ad hoc commands will generally not use a class setting. If in doubt, leave the class attribute unset.

Parameters: With no parameters, this method functions as a getter. With one parameter, the method sets the command class. No validation is performed on the class passed in.

Returns: The currently set class (when called with no arguments).

$obj->command([$command]);

Description: This method is used to set or retrieve the executable that will be called for the request.

Parameters: With no parameters, this method functions as a getter. With one parameter, the method sets the command executable. Currently, this module does not attempt to verify whether the exeutable is actually present or whether permissions on the executable are appropriate.

Returns: The currently set executable (when called with no arguments).

$obj->email([$command]);

Description: This method is used to set or retrieve the email of the user submitting the command. The email is important for notifications and for tracking purposes in case something goes wrong.

Parameters: With no parameters, this method functions as a getter and returns the currently configured email address. If the command has not yet been submitted, the user may set or reset the email address by providing an argument. The address is not currently validated for RFC compliance.

Returns: The email address currently set, or undef if unset (when called with no arguments).

$obj->end_time()

Description: This method is used as a getter for the finish time of the command. If any other package (including main) attempts to set the end_time attribute with this method, an error will result.

Parameters: None.

Returns: The ending time of the command or undef if the end_time has not yet been established.

$obj->error([errorfile])

Description: This method allows the user to set, or if the command has not yet been submitted, to reset the error file for the command. The error file will be the place where all STDERR from the invocation of the executable will be written to. This file should be in a globally accessible location on the filesystem. The attribute may no longer be changed with this method once the command has been submitted.

Parameters: To set the error file, call this method with one parameter, which should be the path to the file where STDERR is to be written.

Returns: When called with no arguments, this method returns the currently set error file, or undef if not yet set.

$obj->getenv([1]);

Description: The getenv method is used to set whether the user environment should be replicated to the DCE or not. To replicate your environment, call this method with an argument that evaluates to true. Calling it with a 0 argument, or an expression that evaluates to false, will turn off environment replication. The default is NOT to replicate the user environment across the DCE.

Parameters: This method behaves as a getter when called with no arguments. If called with 1, or more arguments, the first will be used to set the attribute to either 1 or 0.

Returns: The current setting for getenv (if called with no arguments).

$obj->project([project]);

Description: The project attribute is used to affiliate usage of the Distributed Resource Manager (DRM) with a particular administrative project. This will allow for more effective control and allocation of resources, especially when high priority projects must be fulfilled. Therefore, the "project" is mandatory when the object is built with the constructor, however, the user may still change the project attribute as long as the job has not yet been submitted (after submission most attributes are locked).

Parameters: To use as a setter, the first parameter will be used to set (or reset) the project attribute for the command.

Returns: The currently set project (if called with no parameters).

$obj->input()

Description:

Parameters:

Returns:

$obj->initialdir([path]);

Description: This method sets the directory where the DCE will be chdired to before invoking the command. This is an optional parameter, and if the user leaves it unspecified, the default will be that the DCE will be chdired to the root directory "/" before beginning the command. Use of initialdir is encouraged to promote use of relative paths.

Parameters: A scalar holding the path to the directory the DCE should chdir to before invoking the executable (command).

Returns: When called with no arguments, returns the currently set initialdir, or undef if not yet set.

$obj->name([name]);

Description: The name attribute for command objects is optional and is provided as a convenience to users of the DCE to name their commands.

Parameters: A scalar name for the command. Note that the name will be encoded for packaging into XML, so the user is advised to refrain from using XML sensitivie characters such as > and <.

Returns: When called with no arguments, returns the current name, or undef if not yet set. The name cannot be changed once a request is submitted.

$obj->opsys($os[,$os2,..,$osn]);

Description: The default operating system that commands will be run on is Linux. Users can choose to submit commands to other operating systems in the DCE by using this method. Available operating systems are "Linux", "Solaris", "Linux64", "Solaris64". Multiple operating systems can be specified in a comma seperated list "Linux,Solaris". An attempt to set the opsys attribute to anything else results in an error.

Parameters: A comma seperated list of one or more of the following "Linux", "Solaris" when called as a setter (with one argument).

Returns: When called with no arguments, returns the operating system the command will be run on, which defaults to "Linux".

$obj->max_time($seconds);

Description: The maximum amount of time to wait for completion of this command on the grid in seconds. If not max_time is provided for a command the default behavior is to wait indefinitely for its completion.

Parameters: $seconds, a scalar integer.

Returns: When called as a getter, the method returns the number of seconds configured. When called as a setter, the method returns undef.

$obj->output([path]);

Description: Sets the path for the output file, which would hold all of the output directed to STDOUT by the invocation of the command on the DCE. This method functions as a setter and getter.

Parameters: A path to a file. The file must be globally accessible on the filesystem in order to work, otherwise, the location may not be accessible to compute nodes on the DCE. This attribute may not be changed once a command is submitted.

Returns: When called with no arguments, the method returns the currently set path for the output file, or undef if not yet set.

$obj->params();

Description: Retrieve the list of currently registered parameters for the command.

Parameters: None.

Returns: The method returns a list of hash references.

$obj->priority([priority]);

Description: Use this method to set the optional priority attribute on the command object. The priority setting is used to help allocate the appropriate resources to the request if and when they are available. Higher priority commands may displace lower priority commands.

Parameters: Scalar priority value.

Returns: The current priority, or undef if unset.

$obj->start_time([time]);

Description: This method is only intended to be used as a getter by end users. If any attempt is made to set the start_time attribute of the command object elsewhere, an error will occur.

Parameters: None.

Returns: $time, the start time (scalar) that the DCE began processing the command.

$obj->state([state]);

Description: This method is only intended to be used as a getter by end users. If any attempt is made to set the "state" attribute of the command object elsewhere, an error will occur. Valid states are:

INIT
INTERRUPTED
FAILURE
FINISHED
RUNNING
SUSPENDED
UNKNOWN
WAITING

Parameters: None.

Returns: $state, the current state of the command.

$obj->tempdir([tempdir]);

Description: This method may be used to set or retrieve the path to the directory where temporary files are stored for the HTC request system. Temporary files are sometimes created when the user passes the add_param method an array with the type set to ARRAY. The system processes this by writing each element of the array to a temporary file so that the server processing the request may consult the file and iterate over each entry.

Parameters: A scalar holding the path to the temporary directory. Additional arguments will cause a warning and will be ignored.

Returns: When called with no arguments, returns the currently set temporary directory, or undef if not yet set.

$obj->times([times]);

Description: Sometimes it may be desirable to execute a command more than one time. For instance, a user may choose to execute a particular command many times, with each invocation operating on a different input file. This technique allows for very powerful parallelization of commands. The times method establishes how many times the command should be invoked.

Parameters: An integer number may be passed in to set the times attribute on the command object. If no argument is passed, the method functions as a getter and returns the currently set "times" attribute, or undef if unset. The setting cannot be changed after the request has been submitted.

Returns: $times, when called with no arguments.

$obj->runtime([runtime]);

Description: Use this method to set the optional runtime attribute on the command object. The runtime setting helps to schedule the request relatively faster.

Parameters: Scalar runtime value.

Returns: The current runtime, or undef if unset.

$obj->evictable([evictable]);

Description: Use this method to set the optional evictable attribute on the command object. The evictable setting helps to schedule the request on an appropriate machine on the grid.

Parameters: Scalar runtime value.

Returns: The current runtime, or undef if unset.

$obj->to_xml();

Description: Requests are packaged into XML before they are submitted. To inspect the XML produced, users can call this method, which will return the XML in the form of a string (scalar).

Parameters: None.

Returns: $xml, a string representation of the command object in XML as it would be transmitted to the High Throughput Computing (HTC) infrastructure.

ENVIRONMENT

This module does not read or set any environment variables. However, if the getenv attribute is set, the user environment is replicated to the compute node before the executable is invoked.

DIAGNOSTICS

"Mandatory 'project' attribute not provided."

The project attribute is mandatory when creating a Command object.

"When specifying ARRAY as the type, the VALUE must be an array reference."

An attempt was made to pass something other than an array reference as a VALUE when using a type of "ARRAY". When using "ARRAY", the add_param method assumes that "VALUE" contains an array reference. Adjust your call to add_param() accordingly, and try again.

'value' must be specified.

When using the add_param method with named arguments (by passing a hash reference) the "value" key must be specified.

"Could not close temporary file filehandle."

The filehandle for a temporary file could not be closed.

"Temp dir tempdir, does not exist and could not be created."

The configured location of the directory to contain temporary files does not exist, and the system could not create it either. Check the filesystem and permissions.

BUGS

Description of known bugs (and any workarounds). Usually also includes an invitation to send the author bug reports.

SEE ALSO

File::Temp
File::Path
IO::Scalar
Log::Log4perl
Sys::Hostname
XML::Writer