drmaa2_jsession_run_bulk_jobs(3) - drmaa2_jsession_run_bulk_jobs, Submits an array job based on a template.

drmaa2_jsession_run_bulk_jobs(3)
DRMAA2
drmaa2_jsession_run_bulk_jobs(3)

NAME

drmaa2_jsession_run_bulk_jobs - drmaa2_jsession_run_bulk_jobs, Submits an array job based on a template.

SYNOPSIS

#include "drmaa2.h"

drmaa2_jarray drmaa2_jsession_run_bulk_jobs(const drmaa2_jsession jsession, const drmaa2_jtemplate jtemplate, long long begin_index, long long end_index, long long step, long long max_parallel);

DESCRIPTION

This function submits one or more jobs (in Univa(R) Grid Engine(TM) terminology an array job) which is based on the given job template in the given job session. For a successful array job submission the given job session needs to be open. The returned array job object can be used for monitoring and controlling the array job by either extracting the single jobs (job tasks) out of the job array or by using the job array functions directly.

A DRMAA2 job array is a set of jobs which are based on the same job template. It allows an efficient submission and handling of such jobs not only in the DRMAA2 application but also in Univa(R) Grid Engine(TM) itself. The DRMAA2 job array corresponds to the Univa(R) Grid Engine(TM) array job. The difference between the jobs is that specific environement variables ($SGE_TASK_ID) are set in order to identify the task number. The task number is for each job (which is an array job instance) different. The task ID is usually used to identify the data chunk the job has to work on or to identify which code should be executed.

The task numbers and the amount of jobs which should be part of the array job are determined by the parameters begin_index, end_index, step, and max_parallel.

begin_index: The job task id if the first job array job. Allowed values are 1 and higher.
end_index: The job task id of the last job of the array job. Allowed values are 1 and higher. It must be equal or higher than begin_index.
step: The incrementor / step size of the job task ids. A common value is 1 that mean that each job task id ranging from begin_index to end_index is used. It must be equal or higher than 1. If a higher value is used the second job task id isbegin_index` + step.
max_parallel: Influences how many job id tasks are allowed to run concurrently in parallel. Depending on the cluster load also less tasks can run. If DRMAA2_UNSET_NUM is used as limit, no limit is applied. Otherwise the number corresponds to the Univa(R) Grid Engine(TM) -tc parameter. It must be equal or greater than 1.

Resource limits and general resource requests which are not part of the job template or the Univa(R) Grid Engine(TM) job template enhancements (but which available in Univa(R) Grid Engine(TM) installation with the -l requests - like administrator defined resources), can be requested by using the resourceLimits dictionary which is part of the DRMAA2 job template.

RETURN VALUES

Returns a newly allocated DRMAA2 job array object or NULL in case any error happend. In case of an error the error ID and error text is stored in the context of the thread which submitted the job. The error can be read out by drmaa2_lasterror(3) and drmaa2_lasterror_text(3). The returned job object must be freed by drmaa2_jarray_free(3) after usage. The job array contains a list of DRMAA2 jobs (type drmaa2_j) which can be used for a fainer grained job control and job status fetching.

EXAMPLE

/* Create and open a new job session. */
drmaa2_jsession js = drmaa2_create_jsession("test_session", NULL);
drmaa2_jarray ja = NULL;

if (js != NULL) {
   /* create a new job template. */
   drmaa2_jtemplate jt = drmaa2_jtemplate_create();

   /* add the job characteristics */
   jt->jobName = strdup("test_job");
   jt->remoteCommand = strdup("sleep");
   /* since no allocated strings are used we don't need to specify a callback */
   args = drmaa2_list_create(DRMAA2_STRINGLIST, NULL);
   drmaa2_list_add(args, "60");
   jt->args = args;

   /* submit 100 sleeper jobs, limiting to run 10 sleepers at a time in parallel */
   jarray = drmaa2_jsession_run_bulk_jobs(js, jt, 1, 100, 10);
}

drmaa2_jarray_free(&jarray);
drmaa2_jtemplate_free(&jt);
...

AUTHOR