NAME

Schedule::DRMAAc - Perl wrapper of the C binding of the DRMAA (Distributed Resource Managment Application API) specification.

SYNOPSIS

This module is a Perl wrapper for the C binding of the DRMAA
specification, which allows for the submission and control of jobs to one
or more Distributed Resource Management (DRM) systems (eg. SGE, Condor,
etc. ).

use DRMAA qw/ :all /;

( $error, $diagnosis ) = drmaa_init( undef ); die drmaa_strerror( $error ) . "\n" . $diagnosis if $error;

( $error, $jt, $diagnosis ) = drmaa_allocate_job_template(); die drmaa_strerror( $error ) . "\n" . $diagnosis if $error;

( $error, $diagnosis ) = drmaa_set_attribute( $jt, $DRMAA_REMOTE_COMMAND, '/bin/sleep' ); die drmaa_strerror( $error ) . "\n" . $diagnosis if $error;

( $error, $diagnosis ) = drmaa_set_vector_attribute( $jt, $DRMAA_V_ARGV, [ "1" ] ); # 1st argv param = 1 (to run for 1 second) die drmaa_strerror( $error ) . "\n" . $diagnosis if $error;

( $error, $jobid, $diagnosis ) = drmaa_run_job( $jt ); die drmaa_strerror( $error ) . "\n" . $diagnosis if $error;

my @job_constant = ( $DRMAA_JOB_IDS_SESSION_ALL ); ( $error, $diagnosis ) = drmaa_synchronize( \@job_constant , $DRMAA_TIMEOUT_WAIT_FOREVER, 0 ); die drmaa_strerror( $error ) . "\n" . $diagnosis if $error;

( $error, $diagnosis ) = drmaa_delete_job_template( $jt ); die drmaa_strerror( $error ) . "\n" . $diagnosis if $error;

AUTHOR

Tim Harsch harsch1@llnl.gov

NOTES

This module was created using SWIG on the drmaa.h file provided in SGE version 6.0. As such, certain behaviours of the module were decided by either the unerlying DRMAA library, or by SWIG's method of generating Perl to C wrapping functionality. Needless, to say the design of this Perl module's API is somewhat constrained by the underlying C library.

Nearly every function listed below has an $error and a $diagnosis returned from it. In nearly all cases $error will be $DRMAA_ERRNO_SUCCESS, and an error otherwise. The $error can be looked up via the drmaa_strerror function. And, $diagnosis provides further problem hints.

A useful line for checking the success of most of these functions is:

die drmaa_strerror( $error ) . "\n$diagnosis" if $error;

Because $error and $diagnosis are trivial they will not be mentioned again unless special meaning needs to be clarified.

This documentation was created using the DRMAA spec, SGE drmma.h and drmaa.c source files as a reference. Any ambiguities here can be cleared up by visiting those.

DESCRIPTION

$DRMAA_V_ARGV ( vector of strings )

These parameters are passed as arguments to the job.

$DRMAA_V_ENV ( vector of strings )

The environment values that define the remote environment. Each string complies with the format <name>=<value>. The values override the remote environment values if there are collisions. If the above is not possible, it is implementation dependent.

$DRMAA_V_EMAIL ( vector of strings )

The email address(es) used to report the job completion and status.

$DRMAA_REMOTE_COMMAND ( String )

The name (and optional path) of the job.  If a relative path is used,
it should be relative to $DRMAA_WD.

$DRMAA_JS_STATE ( "drmaa_active" or "drmaa_hold" )

A beginning state for the job to start as on the exec host

$DRMAA_WD ( String )

The directory where the job is executed

$DRMAA_JOB_CATEGORY ( String )

DRM specific value for site-specific policies

$DRMAA_NATIVE_SPECIFICATION ( String )

DRM specific value for site-specific policies"

$DRMAA_BLOCK_EMAIL ( 0 or 1 )

Send or Block email notifications from the DRM

$DRMAA_START_TIME [[[[CC]YY/]MM/]DD] hh:mm[:ss] [{-|+}UU:uu]

The earliest time when the job may be eligible to be run.  The time
format is as follows:

[[[[CC]YY/]MM/]DD] hh:mm[:ss] [{-|+}UU:uu]

CC is the first two digits of the year (century-1)

YY is the last two digits of the year

MM is the two digits of the month [01,12]

DD is the two-digit day of the month [01,31]

hh is the two-digit hour of the day [00,23]

mm is the two-digit minute of the day [00,59]

ss is the two-digit second of the minute [00,61]

UU is the two-digit hours since (before) UTC

uu is the two-digit minutes since (before) UTC

If the optional UTC-offset is not specified, the offset
associated with the local timezone will be used. If the day (DD) is not
specified, the current day will be used unless the specified hour:mm:ss
has already elapsed, in which case the next day will be used. Similarly
for month (MM), year (YY), and century-1 (CC).  Example: The time: Sep 3
4:47:27 PM PDT 2002, could be represented as: 2002/09/03 16:47:27 -07:00

$DRMAA_JOB_NAME ( String )

The name of the job, used by the DRM to track the job.

$DRMAA_INPUT_PATH ( String )

Specifies the jobs' standard input. Unless set elsewhere, if not explicitly set in the job template, the job is started with an empty input stream. If set, specifies the network path of the jobs input stream file of the form [hostname]:file_path When the drmaa_transfer_files job template attribute is supported and contains the character 'i', the input file will be fetched by the underlying DRM system from the specified host or from the submit host if no hostname is specified. When the $DRMAA_TRANSFER_FILES job template attribute is not supported or does not contain the character 'i', the input file is always expected at the host where the job is executed, irrespective of whether hostname is specified. The $DRMAA_PLACEHOLDER_INC placeholder can be used at any position within the file_path of parametric job templates and will be substituted by the underlying DRM system with the parametric jobs' index. A $DRMAA_PLACEHOLDER_HD placeholder at the begin of the file_path denotes the remaining portion of the file_path as a relative file specification resolved relative to the job users home directory at the host where the file is located. A $DRMAA_PLACEHOLDER_WD placeholder at the begin of the file_path denotes the remaining portion of the file_path as a relative file specification resolved relative to the jobs working directory at the host where the file is located. The file_path must be specified in a syntax that is common at the host where the file is located. If set, and the file can't be read, the job enters the state $DRMAA_PS_FAILED.

e.g. ( $error, $diagnosis ) = drmaa_set_attribute( $jt, $DRMAA_INPUT_PATH, "myhost:$DRMAA_PLACEHOLDER_WD.i$DRMAA_PLACEHOLDER_INC" );

$DRMAA_OUTPUT_PATH ( String )

Specifies how to direct the jobs' standard output. If not explicitly set in the job template, the whereabouts of the jobs output stream is not defined. If set, specifies the network path of the jobs output stream file of the form [hostname]:file_path. When the drmaa_transfer_files job template attribute is supported and contains the character 'o', the output file is transferred by the underlying DRM system to the specified host or to the submit host if no hostname is specified. When the $DRMAA_TRANSFER_FILES job template attribute is not supported or does not contain the character 'o', the output file is always kept at the host where the job is executed irrespectively whether hostname is specified. The $DRMAA_PLACEHOLDER_INC placeholder can be used at any position within the file_path of parametric job templates and SHALL be substituted by the underlying DRM system with the parametric jobs' index. A $DRMAA_PLACEHOLDER_HD placeholder at the begin of the file_path denotes the remaining portion of the file_path as a relative file specification resolved relative to the job users home directory at the host where the file is located. A $DRMAA_PLACEHOLDER_WD placeholder at the begin of the file_path denotes the remaining portion of the file_path as a relative file specification resolved relative to the jobs working directory at the host where the file is located. The file_path must be specified in a syntax that is common at the host where the file is located. If set and the file can't be written before execution the job enters the state $DRMAA_PS_FAILED.

$DRMAA_ERROR_PATH ( String )

Specifies how to direct the jobs' standard error. If not explicitly set in the job template, the whereabouts of the jobs error stream is not defined. If set, specifies the network path of the jobs error stream file of the form [hostname]:file_path. When the drmaa_transfer_files job template attribute is supported and contains the character 'e', the output file will be transferred by the underlying DRM system to the specified host or to the submit host if no hostname is specified. When the $DRMAA_TRANSFER_FILES job template attribute is not supported or does not contain the character 'e', the error file is always kept at the host where the job is executed irrespectively of a possibly hostname specified. The $DRMAA_PLACEHOLDER_INC placeholder can be used at any position within the file_path of parametric job templates and SHALL be substituted by the underlying DRM system with the parametric jobs' index. A $DRMAA_PLACEHOLDER_HD placeholder at the begin of the file_path denotes the remaining portion of the file_path as a relative file specification resolved relative to the job users home directory at the host where the file is located. A $DRMAA_PLACEHOLDER_WD placeholder at the begin of the file_path denotes the remaining portion of the file_path as a relative file specification resolved relative to the jobs working directory at the host where the file is located. The file_path must be specified in a syntax that is common at the host where the file is located. If set and the file can't be written before execution the job enters the state $DRMAA_PS_FAILED.

$DRMAA_JOIN_FILES ( "y" or "n" )

Specifies if the error stream should be intermixed with the output stream. If not explicitly set in the job template the attribute defaults to 'n'. If 'y' is specified the underlying DRM system shall ignore the value of the drmaa_error_path attribute and intermix the standard error stream with the standard output stream as specified with $DRMAA_OUTPUT_PATH.

$DRMAA_TRANSFER_FILES ( any of 'e', 'i' and/or 'o' )

Specifies how to transfer files between hosts. If not explicitly set in the job template the attribute defaults to ''. Any combination of 'e', 'i' and 'o' MAY be specified. 'e' impacts the behavior of the $DRMAA_ERROR_PATH attribute. 'i' impacts the behavior of the $DRMAA_INPUT_PATH attribute. 'o' impacts the behavior of the $DRMAA_OUTPUT_PATH attribute.

$DRMAA_DEADLINE_TIME [[[[CC]YY/]MM/]DD] hh:mm[:ss] [{-|+}UU:uu]

(OPTIONAL: may not be supported by the DRM)

Specifies a deadline after which the DRMS will terminate a job. See $DRMAA_START_TIME for an explanation of the time format. If optional portions of the time specifications are omitted the start time is used for calculate, rather than the current day.

$DRMAA_WCT_HLIMIT [[h:]m:]s

(OPTIONAL: may not be supported by the DRM)

This attribute specifies how long the job may be in a running state before its limit has been exceeded, and therefore is terminated by the DRMS. The value of the attribute is of the form: [[h:]m:]s, where h is one or more digits representing hours m is one or more digits representing minutes s is one or more digits representing seconds

$DRMAA_WCT_SLIMIT [[h:]m:]s

(OPTIONAL: may not be supported by the DRM)

Like $DRMAA_WCT_SLIMIT, but this attribute is intended to assist the scheduler. If the time specified in insufficient, the drmaa-implementation may impose a scheduling penalty.

$DRMAA_DURATION_HLIMIT [[h:]m:]s

(OPTIONAL: may not be supported by the DRM)

This attribute specifies how long the job may be in a running state before its limit has been exceeded, and therefore is terminated by the DRMS. Suspended time does not count against this time. See $DRMAA_WCT_HLIMIT for time format.

$DRMAA_DURATION_SLIMIT [[h:]m:]s

(OPTIONAL: may not be supported by the DRM)

Like $DRMAA_DURATION_HLIMIT, but this attribute is intended to assist the scheduler. If the time specified in insufficient, the drmaa-implementation may impose a scheduling penalty.

drmaa_allocate_job_template

( $error, $jt, $diagnosis ) = drmaa_allocate_job_template();

$jt A variable to contain the job template.

purpose: Allocates a new job template. The job template can be altered via setting or clearing job attributes and then jobs launched using the template in $jt will inherit those behaviours.

drmaa_control

( $error, $diagnosis ) = drmaa_control( $job_id, $action );

$job_id The job ID of the job to control

$action The action to perform on the job

The legal values for $action and their meanings are: $DRMAA_CONTROL_SUSPEND stop the job, $DRMAA_CONTROL_RESUME (re)start the job, $DRMAA_CONTROL_HOLD put the job on-hold, $DRMAA_CONTROL_RELEASE release the hold on the job $DRMAA_CONTROL_TERMINATE kill the job.

purpose: Start, stop, restart, or kill the job identified by $job_id. If $job_id is $DRMAA_JOB_IDS_SESSION_ALL, then this routine acts on all jobs *submitted* during this DRMAA session.

This routine will return once the action has been acknowledged by the DRM system, but does not necessarily wait until the action has been completed.

drmaa_delete_job_template

( $error, $diagnosis ) = drmaa_delete_job_template( $jt );

$jt The variable tracking the job template to be deleted.

purpose: Deallocate a job template. This routine has no effect on jobs.

drmaa_exit

( $error, $diagnosis ) = drmaa_exit();

purpose: Disengage from DRMAA library and allow the DRMAA library to perform * any necessary internal clean up. This routine will end the current DRMAA Session, but will not effect any jobs (e.g., queued and running jobs will remain queued and running).

drmaa_get_attribute

( $error, $value, $diagnosis ) = drmaa_get_attribute( $jt, $name );

$jt The job template containing attributes

$name The name of the attribute you want a value for.

purpose: If $name is an existing non-vector attribute name in the job template $jt, then the value of the attribute called $name is returned.

see also: non-vector attributes section above. drmaa_get_attribute_names, drmaa_set_attribute, drmaa_get_next_attr_name and drmaa_release_attr_names.

drmaa_get_attribute_names

( $error, $names, $daignosis ) = drmaa_get_attribute_names()

$names A variable to track the $names iterator

purpose: Returns the set of supported attribute names ( in the iterator $names ). This set will include supported DRMAA reserved attribute names *and* underlying DRM native attribute names.

see also: non-vector attributes section above. drmaa_set_attribute, drmaa_release_attr_names, drmaa_get_next_attr_name and drmaa_get_attribute

drmaa_get_contact

( $error, $contact, $diagnosis ) = drmaa_get_contact();

$contact A comma separated list of contacts

purpose: If called before drmaa_init(), it will return a comma delimited default DRMAA implementation contacts string, one per each DRM system provided implementation. If called after drmaa_init(), it will return the selected contact string. The output string is Implementation dependent.

drmaa_get_DRM_system

( $error, $DRM_system, $diagnosis ) = drmaa_version();

$DRM_system A comma separated list of DRM systems.

purpose: If called before drmaa_init(), it will return a comma delimited DRM systems string, one per each DRM system provided implementation. If called after drmaa_init(), it will return the selected DRM system. This string is implementation dependent.

drmaa_get_DRMAA_implementation

( $error, $DRMAA_impl, $diagnosis ) = drmaa_get_DRMAA_implementation();

$DRMAA_impl The DRMAA implementation.

purpose: Returns the DRMAA_implementation. If called before drmaa_init(), it returns a comma delimited DRMAA implementations string, one per each DRM system provided implementation. If called after drmaa_init(), it returns the selected DRMAA implementation. The output string is implementation dependent.

drmaa_get_next_attr_name

( $error, $name ) = drmaa_get_next_attr_name( $names );

$names The names iterator

purpose: Retrieves the next attribute name from the $names iterator. Returns $DRMAA_ERRNO_SUCCESS on success. Otherwise, the $names iterator has no more names to return.

see also: non-vector attributes section above. drmaa_set_attribute, drmaa_get_attribute_names, drmaa_release_attr_names and drmaa_get_attribute.

drmaa_get_next_attr_value

( $error, $value ) = drmaa_get_next_attr_value( $values );

$values The iterator containing the vector attribute values

$value The next value in the iterator

purpose: Get next attribute value from vector attributes iterator

see also: vector attributes section above. drmaa_set_vector_attribute, drmaa_get_vector_attribute, drmaa_get_vector_attribute_names and drmaa_release_attr_values

drmaa_get_next_job_id

( $error, $jobid ) = drmaa_get_next_job_id( $jobids );

$jobids The structure containing a list of jobids.

$jobid The next job id.

purpose: Returns the next job id in the $jobids structure. $jobids is usually built up via successive calls to drmaa_run_job or via drmaa_run_bulk_jobs.

drmaa_get_vector_attribute

( $error, $values, $diagnosis ) = drmaa_get_vector_attribute( $jt, $name );

$jt The job template containing the vector attributes you are querying

$name The vector attribute you want the values of

$values The vector attributes iterator, contains all the values associated with the vector attribute $name

purpose: If $name is an existing vector attribute name in the job template $jt, then the values of $name are returned in $values and $error = $DRMAA_ERRNO_SUCCESS; otherwise, undef is returned for $values and $error = $DRMAA_ERRNO_INVALID_ATTRIBUTE_VALUE

see also: vector attributes section above. drmaa_set_vector_attribute, drmaa_get_vector_attribute_names, drmaa_get_next_attr_value and drmaa_release_attr_values

drmaa_get_vector_attribute_names

( $error, $names, $diagnosis ) = drmaa_get_vector_attribute_names();

$names names iterator ( use drmaa_get_next_attr_name to iterate )

purpose: Will return the set of supported attribute names who contain vector attributes. This set will include supported DRMAA reserved attribute names and DRM native attribute names.

see also: vector attributes section above. drmaa_set_vector_attribute, drmaa_get_vector_attribute, drmaa_get_next_attr_value and drmaa_release_attr_values

drmaa_init

( $error, $diagnosis ) = drmaa_init( $contact );

$contact The DRM system to be used. If $contact is undef, the default DRM system will be used provided there is only one DRMAA implementation.

purpose: Initialize DRMAA API library and create a new DRMAA Session.

drmaa_job_ps

( $error, $remoteps, $diagnosis ) = drmaa_job_ps( $jobid );

$remoteps The process state of the job. One of the following states:

$DRMAA_PS_UNDETERMINED process status cannot be determined

$DRMAA_PS_QUEUED_ACTIVE job is queued and active

$DRMAA_PS_SYSTEM_ON_HOLD job is queued and in system hold

$DRMAA_PS_USER_ON_HOLD job is queued and in user hold

$DRMAA_PS_USER_SYSTEM_ON_HOLD job is queued and in user and system hold

$DRMAA_PS_RUNNING job is running

$DRMAA_PS_SYSTEM_SUSPENDED job is system suspended

$DRMAA_PS_USER_SUSPENDED job is user suspended

$DRMAA_PS_USER_SYSTEM_SUSPENDED job is user and system suspended

$DRMAA_PS_DONE job finished normally

$DRMAA_PS_FAILED job finished, but failed (or terminated)

purpose: Get the program status of the job identified by $job_id.

drmaa_release_attr_names

drmaa_release_attr_names( $names );

purpose: Releases the $names iterator. The $names iterator can be used without restriction until it has been formerly released using this method, which also frees the memory of the iterator. It is good idea to coincide garbage collection of the $names scalar in Perl at the same time as releasing it via this method, to prevent possible illegal actions with the freed memory.

see also: non-vector attributes section above. drmaa_set_attribute, drmaa_get_attribute_names, drmaa_get_next_attr_name and drmaa_get_attribute.

drmaa_release_attr_values

drmaa_release_attr_values( $values )

$values The values iterator to be released.

purpose: Releases the $values iterator. The $values iterator can be used without restriction until it has been formerly released using this method, which also frees the memory of the iterator. It is good idea to coincide garbage collection of the $values scalar in Perl at the same time as releasing it via this method, to prevent possible illegal actions with the freed memory.

see also: vector attributes section above. drmaa_set_vector_attribute, drmaa_get_vector_attribute, drmaa_get_vector_attribute_names and drmaa_get_next_attr_value.

drmaa_release_job_ids

drmaa_release_job_ids( $jobids );

$jobids The structure containing a list of jobids.

purpose: This function releases the underlying structure $jobids. It does not affect any running jobs, but merely frees the $jobids structure.

drmaa_run_bulk_jobs

( $error, $jobids, $diagnosis ) = drmaa_run_bulk_jobs( $jobids, $jt, $start, $end, $incr )

$jobids A variable to contain a structure that will be filled with the job ids of the jobs that were created as result of calling this function.

$jt The job template containing the attributes to be used when running this set of parametric jobs.

$start The parametric job index to begin with.

$end The parametric job index to end with.

$incr The amount to increase the parametric job index, for each job created.

purpose: Submit a set of parametric jobs, dependent on the implied loop index, each with attributes defined in the job template $jt.

drmaa_run_job

( $error, $jobid, $diagnosis ) = drmaa_run_job( $jt )

$jt The variable that is the job template structure

$jobid The job ID returned by the DRM, ie an SGE array job can be of the form 123.4

The job identifier $job_id is string identical to that returned by the underlying DRM system.

drmaa_set_attribute

( $error, $diagnosis ) = drmaa_set_attribute( $jt, $name, $value );

$jt The variable that is the job template structure

$name The attribute name:

$value The value the attribute will be set to.

purpose: Adds ( $name, $value ) pair to non-vector attributes in job template $jt. Only non-vector attributes can be passed.

drmaa_set_attribute() returns $DRMAA_ERRNO_SUCCESS on success, otherwise: $DRMAA_ERRNO_INVALID_ATTRIBUTE_FORMAT, $DRMAA_ERRNO_INVALID_ARGUMENT, $DRMAA_ERRNO_NO_MEMORY, $DRMAA_ERRNO_INVALID_ATTRIBUTE_VALUE or $DRMAA_ERRNO_CONFLICTING_ATTRIBUTE_VALUES.

see also: non-vector attributes section above. drmaa_get_attribute_names, drmaa_get_next_attr_name, drmaa_get_attribute and drmaa_release_attr_names.

drmaa_strerror

$errstr = drmaa_strerror( $error );

$error Returned by most drmaa_* functions

$errstr A text representation of the $error value.

purpose: Returns the error message text associated with the error number. Returns undef if called with an invalid error number.

drmaa_set_vector_attribute

( $error, $diagnosis ) = drmaa_set_vector_attribute( $jt, $name, $values )

e.g. # put this script's first two ARGV values into $jt ( $error, $diagnosis ) = drmaa_set_vector_attribute( $jt, $DRMAA_V_ARGV, [ $ARGV[0], $ARGV[1] ] )

$jt The job template to set vector attributes on

$name The vector attribute name

$values A reference to an array of values to associate to $name

purpose: Adds the vector attribute $name and its list of values in the $values array reference, to the vector attributes of the job template $jt. drmaa_set_vector_attribute() returns $DRMAA_ERRNO_SUCCESS on success.

see also: vector attributes section above. drmaa_get_next_attr_value, drmaa_get_vector_attribute, drmaa_get_vector_attribute_names and drmaa_release_attr_values

drmaa_synchronize

( $error, $diagnosis ) = drmaa_synchronize( $job_ids, $timeout, $dispose );

e.g. my @job_constant = ( $DRMAA_JOB_IDS_SESSION_ALL ); ( $error, $diagnosis ) = drmaa_synchronize( \@job_constant, $DRMAA_ERRNO_EXIT_TIMEOUT, 0 );

$job_ids The list of jobs ids to synchronize with (or constant)

$timeout The amount of time to wait before returning

$dispose specifies how to treat reaping information: 0 do not reap, 1 "fake reap", i.e. dispose of the rusage data

Wait until all jobs specified by $job_ids have finished execution. If $job_ids is $DRMAA_JOB_IDS_SESSION_ALL, then this routine waits for all jobs *submitted* during this DRMAA session. The $timeout value is used to specify the number of seconds to wait for the job to fail finish before returning if a result is not immediately available. The value $DRMAA_TIMEOUT_WAIT_FOREVER can be used to specify that routine should wait indefinitely for a result. The value $DRMAA_TIMEOUT_NO_WAIT can be used to specify that the routine should return immediately if no result is available. If the call exits before $timeout, all the jobs have been waited on or there was an interrupt. If the invocation exits on $timeout, the return code is $DRMAA_ERRNO_EXIT_TIMEOUT. The caller should check system time before and after this call in order to check how much time has passed.

drmaa_synchronize() returns $DRMAA_ERRNO_SUCCESS on success, otherwise: $DRMAA_ERRNO_DRM_COMMUNICATION_FAILURE, $DRMAA_ERRNO_AUTH_FAILURE, $DRMAA_ERRNO_NO_MEMORY, $DRMAA_ERRNO_EXIT_TIMEOUT or $DRMAA_ERRNO_INVALID_JOB.

drmaa_wait

( $error, $job_id_out, $stat, $rusage, $diagnosis ) = drmaa_wait( $job_id, $timeout );

$job_id The job to wait and/or reap

$timeout The number of seconds to wait before returning

$job_id_out The job id which was waited, might be same as $job_id

$stat A value given to drmaa_w* funcs for more info

$rusage A values iterator, provides resources used info

purpose: This routine will wait for a job with $job_id to fail or finish execution. If the special string, $DRMAA_JOB_IDS_SESSION_ANY, is provided as the job_id, this routine will wait for any job from the session. This routine is modeled on the wait3 POSIX routine. The $timeout value is used to specify the number of seconds to wait for the job to fail or finish before returning if a result is not immediately available. The value $DRMAA_TIMEOUT_WAIT_FOREVER can be used to specify that routine should wait indefinitely for a result. The value $DRMAA_TIMEOUT_NO_WAIT may be specified that the routine should return immediately if no result is available. If the call exits before $timeout, the job has been waited on successfully or there was an interrupt. If the invocation exits on $timeout, the return code is $DRMAA_ERRNO_EXIT_TIMEOUT. The routine reaps jobs on a successful call, so any subsequent calls to drmaa_wait will fail returning $DRMAA_ERRNO_INVALID_JOB meaning that the job has already been reaped. This error is the same as if the job was unknown. Failing due to an elapsed $timeout has an effect that it is possible to issue drmaa_wait multiple times for the same job_id.

drmaa_wait() returns $DRMAA_ERRNO_SUCCESS on success, otherwise: $DRMAA_ERRNO_DRM_COMMUNICATION_FAILURE, $DRMAA_ERRNO_AUTH_FAILURE, $DRMAA_ERRNO_NO_RUSAGE, $DRMAA_ERRNO_NO_MEMORY, $DRMAA_ERRNO_EXIT_TIMEOUT or $DRMAA_ERRNO_INVALID_JOB.

When successful, the rusage information SHALL be provided as an array of
strings, where each string complies with the format <name>=<value>. The
string portion <value> contains the amount of resources consumed by the
job and is opaque.

The $stat drmaa_wait parameter is used in the drmaa_w* functions for providing more detailed information about job termination if available. An analogous set of macros is defined in POSIX for analyzing the wait3(2) OUT parameter 'stat'.

drmaa_synchronize() returns DRMAA_ERRNO_SUCCESS on success, otherwise: DRMAA_ERRNO_DRM_COMMUNICATION_FAILURE, DRMAA_ERRNO_AUTH_FAILURE, DRMAA_ERRNO_NO_RUSAGE, DRMAA_ERRNO_NO_MEMORY, DRMAA_ERRNO_EXIT_TIMEOUT or DRMAA_ERRNO_INVALID_JOB.

drmaa_wcoredump

( $error, $core_dumped, $diagnosis ) = drmaa_wcoredump( $stat );