drmaa.h man page

src/drmaa.h — DRMAA library for Torque/PBS.

Synopsis

#include <stddef.h>
#include <stdio.h>

Functions

int drmaa_init (const char *contact, char *error_diagnosis, size_t error_diag_len)
The drmaa_init() function SHALL initialize DRMAA library and create a new DRMAA session, using the contact parameter, if provided, to determine to which DRMS to connect.
int drmaa_exit (char *error_diagnosis, size_t error_diag_len)
The drmaa_exit() function SHALL disengage from DRMAA library and allow the DRMAA library to perform any necessary internal cleanup.
int drmaa_get_attribute (drmaa_job_template_t *jt, const char *name, char *value, size_t value_len, char *error_diagnosis, size_t error_diag_len)
The function drmaa_get_attribute() SHALL fill the value buffer with up to value_len characters of the scalar attribute, name's, value in the given job template.
int drmaa_set_vector_attribute (drmaa_job_template_t *jt, const char *name, const char *value[], char *error_diagnosis, size_t error_diag_len)
The function drmaa_set_vector_attribute() SHALL set the vector attribute, name, in the job template, jt, to the value(s), value.
int drmaa_get_vector_attribute (drmaa_job_template_t *jt, const char *name, drmaa_attr_values_t **values, char *error_diagnosis, size_t error_diag_len)
The function drmaa_get_vector_attribute() SHALL store in values an opaque values string vector containing the values of the vector attribute, name's, value in the given job template.
int drmaa_get_attribute_names (drmaa_attr_names_t **values, char *error_diagnosis, size_t error_diag_len)
The function drmaa_get_attribute_names() SHALL return the set of supported scalar attribute names in an opaque names string vector stored in values.
int drmaa_get_vector_attribute_names (drmaa_attr_names_t **values, char *error_diagnosis, size_t error_diag_len)
The function drmaa_get_vector_attribute_names() SHALL return the set of supported vector attribute names in an opaque names string vector stored in values.
int drmaa_run_job (char *job_id, size_t job_id_len, const drmaa_job_template_t *jt, char *error_diagnosis, size_t error_diag_len)
The drmaa_run_job() function submits a single job with the attributes defined in the job template, jt.
int drmaa_run_bulk_jobs (drmaa_job_ids_t **jobids, const drmaa_job_template_t *jt, int start, int end, int incr, char *error_diagnosis, size_t error_diag_len)
The drmaa_run_bulk_jobs() function submits a set of parametric jobs which can be run concurrently.
int drmaa_control (const char *job_id, int action, char *error_diagnosis, size_t error_diag_len)
The drmaa_control() function SHALL enact the action indicated by action on the job specified by the job identifier, jobid.
int drmaa_job_ps (const char *job_id, int *remote_ps, char *error_diagnosis, size_t error_diag_len)
The drmaa_job_ps() function SHALL store in remote_ps the program status of the job identified by job_id.
int drmaa_synchronize (const char *job_ids[], signed long timeout, int dispose, char *error_diagnosis, size_t error_diag_len)
The drmaa_synchronize() function SHALL cause the calling thread to block until all jobs specified by job_ids have finished execution.
int drmaa_wait (const char *job_id, char *job_id_out, size_t job_id_out_len, int *stat, signed long timeout, drmaa_attr_values_t **rusage, char *error_diagnosis, size_t error_diag_len)
The drmaa_wait() function SHALL wait for a job identified by job_id to finish execution or fail.
const char * drmaa_strerror (int drmaa_errno)
The drmaa_strerror() function SHALL return the error string describing the DRMAA error number drmaa_errno.
int drmaa_get_contact (char *contact, size_t contact_len, char *error_diagnosis, size_t error_diag_len)
The drmaa_get_contact() function, if called before drmaa_init(), SHALL return a string containing a comma-delimited list of default DRMAA implementation contacts strings, one per DRM implementation provided.
int drmaa_version (unsigned int *major, unsigned int *minor, char *error_diagnosis, size_t error_diag_len)
The drmaa_version() function SHALL set major and minor to the major and minor versions of the DRMAA C binding specification implemented by the DRMAA implementation.
int drmaa_get_DRM_system (char *drm_system, size_t drm_system_len, char *error_diagnosis, size_t error_diag_len)
The drmaa_get_DRM_system() function, if called before drmaa_init(), SHALL return a string containing a comma-delimited list of DRM system identifiers, one per DRM system implementation provided.
int drmaa_get_DRMAA_implementation (char *drmaa_impl, size_t drmaa_impl_len, char *error_diagnosis, size_t error_diag_len)
The drmaa_get_DRMAA_implementation() function, if called before drmaa_init(), SHALL return a string containing a comma-delimited list of DRMAA implementations, one per DRMAA implementation provided.
void drmaa_set_logging_output (FILE *file)
Specify place where goes log messages from library when they were enabled at configure time.

Detailed Description

DRMAA library for Torque/PBS.

Author:

Lukasz Ciesnik lukasz.ciesnik@gmail.com

Copyright (C) 2006 Poznan Supercomputing and Networking Center DSP team dsp-devel@hedera.man.poznan.pl

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

Documentation taken from:

Distributed Resource Management Application API C Bindings v1.0

Copyright (C) Global Grid Forum (2003). All Rights Reserved.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the GGF or other organizations, except as needed for the purpose of developing Grid Recommendations in which case the procedures for copyrights defined in the GGF Document process must be followed, or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by the GGF or its successors or assigns. This document and the information contained herein is provided on an 'AS IS' basis and THE GLOBAL GRID FORUM DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Function Documentation

int drmaa_run_job (char * job_id, size_t job_id_len, const drmaa_job_template_t * jt, char * error_diagnosis, size_t error_diag_len)

The drmaa_run_job() function submits a single job with the attributes defined in the job template, jt. Upon success, up to job_id_len characters of the submitted job's job identifier are stored in the buffer, job_id.

int drmaa_run_bulk_jobs (drmaa_job_ids_t ** jobids, const drmaa_job_template_t * jt, int start, int end, int incr, char * error_diagnosis, size_t error_diag_len)

The drmaa_run_bulk_jobs() function submits a set of parametric jobs which can be run concurrently. The attributes defined in the job template, jt are used for every parametric job in the set. Each job in the set is identical except for it's index. The first parametric job has an index equal to start. The next job has an index equal to start + incr, and so on. The last job has an index equal to start + n * incr, where n is equal to (end - start) / incr. Note that the value of the last job's index may not be equal to end if the difference between start and end is not evenly divisble by incr. The smallest valid value for start is 1. The largest valid value for end is 2147483647 ( $2^{31}-1$). The start value must be less than or equal to the end value, and only positive index numbers are allowed. The index number can be determined by the job in an implementation specific fashion. On success, an opaque job id string vector containing job identifiers for all submitted jobs SHALL be returned into job_ids. The job identifiers in the opaque job id string vector can be extracted using the drmaa_get_next_job_id() function. The caller is responsible for releasing the opaque job id string vector returned into job_ids using the drmaa_release_job_ids() function.

int drmaa_control (const char * job_id, int action, char * error_diagnosis, size_t error_diag_len)

The drmaa_control() function SHALL enact the action indicated by action on the job specified by the job identifier, jobid. The action parameter's value may be one of the following:

·
DRMAA_CONTROL_SUSPEND
·
DRMAA_CONTROL_RESUME
·
DRMAA_CONTROL_HOLD
·
DRMAA_CONTROL_RELEASE
·
DRMAA_CONTROL_TERMINATE The drmaa_control() function SHALL return after the DRM system has acknowledged the command, not necessarily after the desired action has been performed. If jobid is DRMAA_JOB_IDS_SESSION_ALL, this function SHALL perform the specified action on all jobs submitted during this session as of this function is called.

int drmaa_job_ps (const char * job_id, int * remote_ps, char * error_diagnosis, size_t error_diag_len)

The drmaa_job_ps() function SHALL store in remote_ps the program status of the job identified by job_id. The possible values of a program's staus are:

·
DRMAA_PS_UNDETERMINED
·
DRMAA_PS_QUEUED_ACTIVE
·
DRMAA_PS_SYSTEM_ON_HOLD
·
DRMAA_PS_USER_ON_HOLD
·
DRMAA_PS_USER_SYSTEM_ON_HOLD
·
DRMAA_PS_RUNNING
·
DRMAA_PS_SYSTEM_SUSPENDED
·
DRMAA_PS_USER_SUSPENDED
·
DRMAA_PS_DONE
·
DRMAA_PS_FAILED

Terminated jobs have a status of DRMAA_PS_FAILED.

int drmaa_synchronize (const char * job_ids[], signed long timeout, int dispose, char * error_diagnosis, size_t error_diag_len)

The drmaa_synchronize() function SHALL cause the calling thread to block until all jobs specified by job_ids have finished execution. If job_ids contains DRMAA_JOB_IDS_SESSION_ALL, then this function SHALL wait for all jobs submitted during this DRMAA session as of the point in time when drmaa_synchronize() is called. To avoid thread race conditions in multithreaded applications, the DRMAA implementation user should explicitly synchronize this call with any other job submission calls or control calls that may change the number of remote jobs.

The timeout parameter value indicates how many seconds to remain blocked in this call waiting for results to become available, before returning with a DRMAA_ERRNO_EXIT_TIMEOUT error code. The value, DRMAA_TIMEOUT_WAIT_FOREVER, MAY be specified to wait indefinitely for a result. The value, DRMAA_TIMEOUT_NO_WAIT, MAY be specified to return immediately with a DRMAA_ERRNO_EXIT_TIMEOUT error code if no result is available. If the call exits before the timeout has elapsed, all the jobs have been waited on or there was an interrupt. The caller should check system time before and after this call in order to be sure of how much time has passed. The dispose parameter specifies how to treat the reaping of the remote job's internal data record, which includes a record of the job's consumption of system resources during its execution and other statistical information. If the dispose parameter's value is 1, the DRMAA implementation SHALL dispose of the job's data record at the end of the drmaa_synchroniize() call. If the dispose parameter's value is 0, the data record SHALL be left for future access via the drmaa_wait() method.

int drmaa_wait (const char * job_id, char * job_id_out, size_t job_id_out_len, int * stat, signed long timeout, drmaa_attr_values_t ** rusage, char * error_diagnosis, size_t error_diag_len)

The drmaa_wait() function SHALL wait for a job identified by job_id to finish execution or fail. If the special string, JOB_IDS_SESSION_ANY, is provided as the job_id, this function will wait for any job from the session to finish execution or fail. In this case, any job for which exit status information is available will satisfy the requirement, including jobs which preivously finished but have never been the subject of a drmaa_wait() call. This routine is modeled on the wait3 POSIX routine.

The timeout parameter value indicates how many seconds to remain blocked in this call waiting for a result, before returning with a DRMAA_ERRNO_EXIT_TIMEOUT error code. The value, DRMAA_TIMEOUT_WAIT_FOREVER, MAY be specified to wait indefinitely for a result. The value, DRMAA_TIMEOUT_NO_WAIT, MAY be specified to return immediately with a DRMAA_ERRNO_EXIT_TIMEOUT error code if no result is available. If the call exits before the timeout has elapsed, the job has been successfully waited on or there was an interrupt. The caller should check system time before and after this call in order to be sure of how much time has passed.

Upon success, drmaa_wait() fills job_id_out with up to job_id_out_len characters of the waited job's id, stat with the a code that includes information about the conditions under which the job terminated, and rusage with an array of <name>=<value> strings that describe the amount of resources consumed by the job and are implementation defined. The stat parameter is further described below. The rusage parameter's values may be accessed via drmaa_get_next_attr_value().

The drmaa_wait() function reaps job data records on a successful call, so any subsequent calls to drmaa_wait() will fail, returning a DRMAA_ERRNO_INVALID_JOB error code, meaning that the job's data record has already been reaped. This error code is the same as if the job were unknown. If drmaa_wait() exists due to a timeout, DRMAA_ERRNO_EXIT_TIMEOUT is returned and no rusage information is reaped. (The only case where drmaa_wait() can be successfully called on a single job more than once is when the previous call(s) to drmaa_wait() returned DRMAA_ERRNO_EXIT_TIMEOUT.)

The stat parameter, set by a successful call to drmaa_wait(), is used to retrieve further input about the exit condition of the waited job, identified by job_id_out, through the following functions: drmaa_wifexited(), drmaa_wexitstatus(), drmaa_wifsignaled(), drmaa_wtermsig(),drmaa_wcoredump() and drmaa_wifaborted().

int drmaa_get_contact (char * contact, size_t contact_len, char * error_diagnosis, size_t error_diag_len)

The drmaa_get_contact() function, if called before drmaa_init(), SHALL return a string containing a comma-delimited list of default DRMAA implementation contacts strings, one per DRM implementation provided. If called after drmaa_init(), drmaa_get_contacts() SHALL return the contact string for the DRM system for which the library has been initialized.

int drmaa_get_DRM_system (char * drm_system, size_t drm_system_len, char * error_diagnosis, size_t error_diag_len)

The drmaa_get_DRM_system() function, if called before drmaa_init(), SHALL return a string containing a comma-delimited list of DRM system identifiers, one per DRM system implementation provided. If called after drmaa_init(), drmaa_get_DRM_system() SHALL return the selected DRM system.

int drmaa_get_DRMAA_implementation (char * drmaa_impl, size_t drmaa_impl_len, char * error_diagnosis, size_t error_diag_len)

The drmaa_get_DRMAA_implementation() function, if called before drmaa_init(), SHALL return a string containing a comma-delimited list of DRMAA implementations, one per DRMAA implementation provided. If called after drmaa_init(), drmaa_get_DRMAA_implementation() SHALL return the selected DRMAA implementation.

void drmaa_set_logging_output (FILE * file)

Specify place where goes log messages from library when they were enabled at configure time. By default they are written to standard error stream.

Parameters:

file File to write to.

Author

Generated automatically by Doxygen for torque from the source code.

Info

Sat Apr 9 2016 Version 4.2.10 torque