torque  4.2.8
 All Data Structures Files Functions Variables Groups
drmaa.h
Go to the documentation of this file.
1 /* $Id: drmaa.h,v 1.15 2006/09/08 18:18:08 ciesnik Exp $ */
52 #ifndef __DRMAA_H
53 #define __DRMAA_H
54 
55 #include <stddef.h>
56 #include <stdio.h>
57 
61 /* @{ */
62 
64 
66 
68 
69 typedef struct drmaa_job_ids_s drmaa_job_ids_t;
70 
71 #define DRMAA_ATTR_BUFFER 1024
72 #define DRMAA_CONTACT_BUFFER 1024
73 #define DRMAA_DRM_SYSTEM_BUFFER 1024
74 #define DRMAA_DRMAA_IMPL_BUFFER 1024
75 #define DRMAA_ERROR_STRING_BUFFER 1024
76 #define DRMAA_JOBNAME_BUFFER 1024
77 #define DRMAA_SIGNAL_BUFFER 32
78 
79 #define DRMAA_TIMEOUT_NO_WAIT 0
80 #define DRMAA_TIMEOUT_WAIT_FOREVER -1
81 #define DRMAA_PS_UNDETERMINED 0x00
82 #define DRMAA_PS_QUEUED_ACTIVE 0x10
83 #define DRMAA_PS_SYSTEM_ON_HOLD 0x11
84 #define DRMAA_PS_USER_ON_HOLD 0x12
85 #define DRMAA_PS_USER_SYSTEM_ON_HOLD 0x13
86 #define DRMAA_PS_RUNNING 0x20
87 #define DRMAA_PS_SYSTEM_SUSPENDED 0x21
88 #define DRMAA_PS_USER_SUSPENDED 0x22
89 #define DRMAA_PS_USER_SYSTEM_SUSPENDED 0x23
90 #define DRMAA_PS_DONE 0x30
91 #define DRMAA_PS_FAILED 0x40
92 #define DRMAA_CONTROL_SUSPEND 0
93 #define DRMAA_CONTROL_RESUME 1
94 #define DRMAA_CONTROL_HOLD 2
95 #define DRMAA_CONTROL_RELEASE 3
96 #define DRMAA_CONTROL_TERMINATE 4
97 #define DRMAA_JOB_IDS_SESSION_ALL "DRMAA_JOB_IDS_SESSION_ALL"
98 #define DRMAA_JOB_IDS_SESSION_ANY "DRMAA_JOB_IDS_SESSION_ANY"
99 
100 #define DRMAA_BLOCK_EMAIL "drmaa_block_email"
101 #define DRMAA_DEADLINE_TIME "drmaa_deadline_time"
102 #define DRMAA_DURATION_HLIMIT "drmaa_duration_hlimit"
103 #define DRMAA_DURATION_SLIMIT "drmaa_duration_slimit"
104 #define DRMAA_ERROR_PATH "drmaa_error_path"
105 #define DRMAA_INPUT_PATH "drmaa_input_path"
106 #define DRMAA_JOB_CATEGORY "drmaa_job_category"
107 #define DRMAA_JOB_NAME "drmaa_job_name"
108 #define DRMAA_JOIN_FILES "drmaa_join_files"
109 #define DRMAA_JS_STATE "drmaa_js_state"
110 #define DRMAA_NATIVE_SPECIFICATION "drmaa_native_specification"
111 #define DRMAA_OUTPUT_PATH "drmaa_output_path"
112 #define DRMAA_REMOTE_COMMAND "drmaa_remote_command"
113 #define DRMAA_START_TIME "drmaa_start_time"
114 #define DRMAA_TRANSFER_FILES "drmaa_transfer_files"
115 #define DRMAA_V_ARGV "drmaa_v_argv"
116 #define DRMAA_V_EMAIL "drmaa_v_email"
117 #define DRMAA_V_ENV "drmaa_v_env"
118 #define DRMAA_WCT_HLIMIT "drmaa_wct_hlimit"
119 #define DRMAA_WCT_SLIMIT "drmaa_wct_slimit"
120 #define DRMAA_WD "drmaa_wd"
121 
122 #define DRMAA_SUBMISSION_STATE_ACTIVE "drmaa_active"
123 #define DRMAA_SUBMISSION_STATE_HOLD "drmaa_hold"
124 #define DRMAA_PLACEHOLDER_HD "$drmaa_hd_ph$"
125 #define DRMAA_PLACEHOLDER_WD "$drmaa_wd_ph$"
126 #define DRMAA_PLACEHOLDER_INCR "$drmaa_incr_ph$"
127 
128 #define DRMAA_ERRNO_SUCCESS 0
129 #define DRMAA_ERRNO_INTERNAL_ERROR 1
130 #define DRMAA_ERRNO_DRM_COMMUNICATION_FAILURE 2
131 #define DRMAA_ERRNO_AUTH_FAILURE 3
132 #define DRMAA_ERRNO_INVALID_ARGUMENT 4
133 #define DRMAA_ERRNO_NO_ACTIVE_SESSION 5
134 #define DRMAA_ERRNO_NO_MEMORY 6
135 #define DRMAA_ERRNO_INVALID_CONTACT_STRING 7
136 #define DRMAA_ERRNO_DEFAULT_CONTACT_STRING_ERROR 8
137 #define DRMAA_ERRNO_NO_DEFAULT_CONTACT_STRING_SELECTED 9
138 #define DRMAA_ERRNO_DRMS_INIT_FAILED 10
139 #define DRMAA_ERRNO_ALREADY_ACTIVE_SESSION 11
140 #define DRMAA_ERRNO_DRMS_EXIT_ERROR 12
141 #define DRMAA_ERRNO_INVALID_ATTRIBUTE_FORMAT 13
142 #define DRMAA_ERRNO_INVALID_ATTRIBUTE_VALUE 14
143 #define DRMAA_ERRNO_CONFLICTING_ATTRIBUTE_VALUES 15
144 #define DRMAA_ERRNO_TRY_LATER 16
145 #define DRMAA_ERRNO_DENIED_BY_DRM 17
146 #define DRMAA_ERRNO_INVALID_JOB 18
147 #define DRMAA_ERRNO_RESUME_INCONSISTENT_STATE 19
148 #define DRMAA_ERRNO_SUSPEND_INCONSISTENT_STATE 20
149 #define DRMAA_ERRNO_HOLD_INCONSISTENT_STATE 21
150 #define DRMAA_ERRNO_RELEASE_INCONSISTENT_STATE 22
151 #define DRMAA_ERRNO_EXIT_TIMEOUT 23
152 #define DRMAA_ERRNO_NO_RUSAGE 24
153 #define DRMAA_ERRNO_NO_MORE_ELEMENTS 25
154 
155 #if defined(__cplusplus)
156 extern "C"
157  {
158 #endif
159 
160 
176  int drmaa_init(
177  const char *contact,
178  char *error_diagnosis, size_t error_diag_len
179  );
180 
191  int drmaa_exit(char *error_diagnosis, size_t error_diag_len);
192 
193 
194 
203  int drmaa_allocate_job_template(
205  char *error_diagnosis,
206  size_t error_diag_len
207  );
208 
214  int drmaa_delete_job_template(
216  char *error_diagnosis, size_t error_diag_len
217  );
218 
224  int drmaa_set_attribute(
226  const char *name, const char *value,
227  char *error_diagnosis, size_t error_diag_len
228  );
229 
237  const char *name, char *value, size_t value_len,
238  char *error_diagnosis, size_t error_diag_len
239  );
240 
249  const char *name, const char *value[],
250  char *error_diagnosis, size_t error_diag_len
251  );
252 
260  const char *name, drmaa_attr_values_t **values,
261  char *error_diagnosis, size_t error_diag_len
262  );
263 
264 
265 
274  drmaa_attr_names_t **values,
275  char *error_diagnosis, size_t error_diag_len
276  );
277 
286  drmaa_attr_names_t **values,
287  char *error_diagnosis, size_t error_diag_len
288  );
289 
308  /* @addtogroup drmaa_viter @{ */
309  int drmaa_get_next_attr_name(drmaa_attr_names_t* values,
310  char *value, size_t value_len);
311  int drmaa_get_next_attr_value(drmaa_attr_values_t* values,
312  char *value, size_t value_len);
313  int drmaa_get_next_job_id(drmaa_job_ids_t* values,
314  char *value, size_t value_len);
315  int drmaa_get_num_attr_names(drmaa_attr_names_t* values, size_t *size);
316  int drmaa_get_num_attr_values(drmaa_attr_values_t* values, size_t *size);
317  int drmaa_get_num_job_ids(drmaa_job_ids_t* values, size_t *size);
318  void drmaa_release_attr_names(drmaa_attr_names_t* values);
319  void drmaa_release_attr_values(drmaa_attr_values_t* values);
320  void drmaa_release_job_ids(drmaa_job_ids_t* values);
321  /* @} */
322 
329  int drmaa_run_job(
330  char *job_id, size_t job_id_len, const drmaa_job_template_t *jt,
331  char *error_diagnosis, size_t error_diag_len
332  );
333 
356  drmaa_job_ids_t **jobids,
357  const drmaa_job_template_t *jt,
358  int start, int end, int incr,
359  char *error_diagnosis,
360  size_t error_diag_len
361  );
362 
378  int drmaa_control(
379  const char *job_id, int action,
380  char *error_diagnosis, size_t error_diag_len
381  );
382 
400  int drmaa_job_ps(
401  const char *job_id, int *remote_ps,
402  char *error_diagnosis, size_t error_diag_len
403  );
404 
433  int drmaa_synchronize(
434  const char *job_ids[], signed long timeout, int dispose,
435  char *error_diagnosis, size_t error_diag_len
436  );
437 
483  int drmaa_wait(
484  const char *job_id,
485  char *job_id_out, size_t job_id_out_len, int *stat,
486  signed long timeout, drmaa_attr_values_t **rusage,
487  char *error_diagnosis, size_t error_diag_len
488  );
489 
490  int drmaa_wifexited(int *exited, int stat,
491  char *error_diagnosis, size_t error_diag_len);
492  int drmaa_wexitstatus(int *exit_status, int stat,
493  char *error_diagnosis, size_t error_diag_len);
494  int drmaa_wifsignaled(int *signaled, int stat,
495  char *error_diagnosis, size_t error_diag_len);
496  int drmaa_wtermsig(char *signal, size_t signal_len, int stat,
497  char *error_diagnosis, size_t error_diag_len);
498  int drmaa_wcoredump(int *core_dumped, int stat,
499  char *error_diagnosis, size_t error_diag_len);
500  int drmaa_wifaborted(int *aborted, int stat,
501  char *error_diagnosis, size_t error_diag_len);
502 
507  const char *drmaa_strerror(int drmaa_errno);
508 
517  int drmaa_get_contact(char *contact, size_t contact_len,
518  char *error_diagnosis, size_t error_diag_len);
519 
525  int drmaa_version(unsigned int *major, unsigned int *minor,
526  char *error_diagnosis, size_t error_diag_len);
527 
534  int drmaa_get_DRM_system(char *drm_system, size_t drm_system_len,
535  char *error_diagnosis, size_t error_diag_len);
536 
544  int drmaa_get_DRMAA_implementation(char *drmaa_impl, size_t drmaa_impl_len,
545  char *error_diagnosis, size_t error_diag_len);
546 
547 #if defined(__cplusplus)
548  } /* extern "C" */
549 
550 #endif
551 
552 /* @} */
553 
554 
555 /*
556  * Functions outside of DRMAA specification.
557  */
558 
564 void drmaa_set_logging_output(FILE *file);
565 
566 #endif /* __DRMAA_H */
567 
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...
Definition: session.c:310
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...
Definition: util.c:207
Definition: drmaa_impl.h:86
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 c...
Definition: util.c:230
void drmaa_set_logging_output(FILE *file)
Specify place where goes log messages from library when they were enabled at configure time...
Definition: error.c:86
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...
Definition: session.c:343
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 ...
Definition: util.c:219
Definition: drmaa_impl.h:91
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 a...
Definition: session.c:68
Definition: drmaa_impl.h:96
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 j...
Definition: session.c:451
const char * drmaa_strerror(int drmaa_errno)
The drmaa_strerror() function SHALL return the error string describing the DRMAA error number drmaa_e...
Definition: error.c:126
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.
Definition: session.c:47
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 contai...
Definition: session.c:396
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...
Definition: wait.c:159
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...
Definition: submit.c:48
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...
Definition: submit.c:60
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 ...
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_...
Definition: session.c:529
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 ...
Definition: util.c:43
Job template data.
Definition: drmaa_impl.h:73
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 c...
Definition: util.c:188
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 na...
Definition: util.c:52