1drmaa_attributes(3) Grid Engine DRMAA drmaa_attributes(3)
2
6 drmaa_get_attribute_names, drmaa_get_vector_attribute_names,
7 drmaa_get_next_attr_name, drmaa_get_num_attr_names,
8 drmaa_release_attr_names - DRMAA job template attributes
9
11 #include "drmaa.h"
12 int drmaa_get_attribute_names(
14 drmaa_attr_names_t **values,
15 char *error_diagnosis,
16 size_t error_diag_len
17 );
18 int drmaa_get_vector_attribute_names(
20 drmaa_attr_names_t **values,
21 char *error_diagnosis,
22 size_t error_diag_len
23 );
24 int drmaa_get_next_attr_name(
26 drmaa_attr_names_t* values,
27 char *value,
28 int value_len
29 );
30 int drmaa_get_next_attr_value(
32 drmaa_attr_values_t* values,
33 char *value,
34 int value_len
35 );
36 int drmaa_get_num_attr_names(
38 drmaa_attr_names_t* values,
39 int *size
40 );
41 void drmaa_release_attr_names(
43 drmaa_attr_names_t* values
44 );
45
47 The drmaa_get_attribute_names() function returns into values a DRMAA
48 names string vector containing the set of supported non-vector DRMAA
49 job template attribute names. The set includes supported DRMAA reserved
50 attribute names and Grid Engine native attribute names. The names in
51 the names string vector can be extracted using
52 drmaa_get_next_attr_name(3). The number of names in the names string
53 vector can be determined using drmaa_get_num_attr_names(3). Note that
54 this function is only available in the 1.0 implementation. The caller
55 is responsible for releasing the names string vector returned into val‐
56 ues using drmaa_release_attr_names(3). Use drmaa_set_attribute(3) and
57 drmaa_get_attribute(3) for setting and inspecting non-vector
58 attributes.
59 drmaa_get_vector_attribute_names()
61 The drmaa_get_vector_attribute_names() function returns into values a
62 DRMAA names string vector containing the set of supported vector DRMAA
63 job template attribute names. The set includes supported DRMAA reserved
64 attribute names and Grid Engine native attribute names. The names in
65 the names string vector can be extracted using
66 drmaa_get_next_attr_name(3). The caller is responsible for releasing
67 the names string vector returned into values using
68 drmaa_release_attr_names(3). Use drmaa_set_vector_attribute(3) and
69 drmaa_get_vector_attribute(3) for setting and inspecting vector
70 attributes.
71 drmaa_get_next_attr_name()
73 Each time drmaa_get_next_attr_name() is called it returns into the buf‐
74 fer, value, up to value_len bytes of the next entry stored in the DRMAA
75 names string vector, values. Once the names list has been exhausted,
76 DRMAA_ERRNO_NO_MORE_ELEMENTS is returned.
77 drmaa_get_num_attr_names()
79 The drmaa_get_num_attr_names() returns into size the number of entries
80 in the DRMAA names string vector. This function is only available in
81 the 1.0 implementation.
82 drmaa_release_attr_names()
84 The drmaa_release_attr_names() function releases all resources associ‐
85 ated with the DRMAA names string vector, values.
86 Attribute Priorities
88 DRMAA job template attributes can be set from six different sources.
89 In order of precedence, from lowest to highest, these are: options set
90 by DRMAA automatically by default, options set in the sge_request(5)
91 file(s), options set in the script file, options set by the
92 drmaa_job_category attribute, options set by the drmaa_native_specifi‐
93 cation attribute, and options set through other DRMAA attributes.
94 By default DRMAA sets four options for all jobs. These are "-p 0", "-b
96 yes", "-shell no", and "-w e". This means that by default, all jobs
97 will have priority 0, all jobs will be treated as binary, i.e. no
98 scripts args will be parsed, all jobs will be executed without a wrap‐
99 per shell, and jobs which are unschedulable will cause a submit error.
100 The sge_request(5) file, found in the $GE_ROOT/$GE_CELL/common direc‐
102 tory, may contain options to be applied to all jobs. The .sge_request
103 file found in the user's home directory or the current working direc‐
104 tory may also contain options to be applied to certain jobs. See
105 sge_request(5) for more information.
106 If the sge_request(5) file contains "-b no" or if the
108 drmaa_native_specification attribute is set and contains "-b no", the
109 script file will be parsed for in-line arguments. Otherwise, no
110 scripts args will be interpreted. See qsub(1) for more information.
111 If the drmaa_job_category attribute is set, and the category it points
113 to exists in one of the qtask(5) files, the options associated with
114 that category will be applied to the job template. See qtask(5) and
115 the drmaa_job_category attribute below for more information.
116 If the drmaa_native_specification attribute is set, all options con‐
118 tained therein will be applied to the job template. See the
119 drmaa_native_specification below for more information.
120 Other DRMAA attributes will override any previous settings. For exam‐
122 ple, if the sge_request file contains "-j y", but the drmaa_join_files
123 attribute is set to "n", the ultimate result is that the input and out‐
124 put files will remain separate.
125 For various reasons, some options are silently ignored by DRMAA. Set‐
127 ting any of these options will have no effect. The ignored options
128 are: -cwd, -help, -sync, -t, -verify, -w w, and -w v. The -cwd option
129 can be re-enabled by setting the environment variable,
130 SGE_DRMAA_ALLOW_CWD. However, the -cwd option is not thread safe and
131 should not be used in a multi-threaded context.
132 Attribute Correlations
134 The following DRMAA attributes correspond to the following qsub(1)
135 options:
136 DRMAA Attribute qsub Option
138 -------------------------------------------------------
139 drmaa_remote_command script file
140 drmaa_v_argv script file args
141 drmaa_js_state = "drmaa_hold" -h
142 drmaa_v_env -v
143 drmaa_wd = $PWD -cwd
144 drmaa_job_category (qtsch qtask)*
145 drmaa_native_specification ALL*
146 drmaa_v_email -M
147 drmaa_block_email = "1" -m n
148 drmaa_start_time -a
149 drmaa_job_name -N
150 drmaa_input_path -i
151 drmaa_output_path -o
152 drmaa_error_path -e
153 drmaa_join_files -j
154 drmaa_transfer_files (prolog and epilog)*
155 * See the individual attribute description below
157
159 drmaa_remote_command - "<remote_command>"
160 Specifies the remote command to execute. The remote_command must be the
161 path of an executable that is available at the job's execution host.
162 If the path is relative, it is assumed to be relative to the working
163 directory, usually set through the drmaa_wd attribute. If working
164 directory is not set, the path is assumed to be relative to the user's
165 home directory.
166 The file pointed to by remote_command may either be an executable
168 binary or an executable script. If a script, it must include the path
169 to the shell in a #! line at the beginning of the script. By default,
170 the remote command will be executed directly, as by exec(2). To have
171 the remote command executed in a shell, such as to preserve environment
172 settings, use the drmaa_native_specification attribute to include the
173 "-shell yes" option. Jobs which are executed by a wrapper shell fail
174 differently from jobs which are executed directly. When a job which
175 contains a user error, such as an invalid path to the executable, is
176 executed by a wrapper shell, the job will execute successfully, but
177 exit with a return code of 1. When a job which contains such an error
178 is executed directly, it will enter the DRMAA_PS_FAILED state upon exe‐
179 cution.
180 drmaa_js_state - "{drmaa_hold|drmaa_active}"
182 Specifies the job state at submission. The string values 'drmaa_hold'
183 and 'drmaa_active' are supported. When 'drmaa_active' is used the job
184 is submitted in a runnable state. When 'drmaa_hold' is used the job is
185 submitted in user hold state (either DRMAA_PS_USER_ON_HOLD or
186 DRMAA_PS_USER_SYSTEM_ON_HOLD). This attribute is largely equivalent to
187 the qsub(1) submit option '-h'.
188 drmaa_wd - "<directory_name>"
190 Specifies the directory name where the job will be executed. A
191 '$drmaa_hd_ph$' placeholder at the beginning of the directory_name
192 denotes the remaining string portion as a relative directory name that
193 is resolved relative to the job user's home directory at the execution
194 host. When the DRMAA job template is used for bulk job submission (see
195 also drmaa_run_bulk_job(3)) the '$drmaa_incr_ph$' placeholder can be
196 used at any position within directory_name to cause a substitution with
197 the parametric job's index. The directory_name must be specified in a
198 syntax that is common at the host where the job is executed. If set to
199 a relative path and no placeholder is used, a path relative to the
200 user's home directory is assumed. If not set, the working directory
201 will default to the user's home directory. If set and the given direc‐
202 tory does not exist the job will enter the DRMAA_PS_FAILED state when
203 run.
204 Note that the working directory path is the path on the execution host.
206 If binary mode is disabled, an attempt to find the job script will be
207 made, relative to the working directory path. That means that the path
208 to the script must be the same on both the submission and execution
209 hosts.
210 drmaa_job_name - "<job_name>"
212 Specifies the job's name. Setting the job name is equivalent to use of
213 qsub(1) submit option '-N' with job_name as option argument.
214 drmaa_input_path - "[<hostname>]:<file_path>"
216 Specifies the standard input of the job. Unless set elsewhere, if not
217 explicitly set in the job template, the job is started with an empty
218 input stream. If the standard input is set it specifies the network
219 path of the job's input stream file.
220 When the 'drmaa_transfer_files' job template attribute is supported and
222 contains the character 'i', the input file will be fetched by Grid
223 Engine from the specified host or from the submit host if no hostname
224 is specified. When the 'drmaa_transfer_files' job template attribute is
225 not supported or does not contain the character 'i', the input file is
226 always expected at the host where the job is executed regardless of any
227 hostname specified.
228 If the DRMAA job template will be used for bulk job submission, (See
230 also drmaa_run_bulk_job(3)) the '$drmaa_incr_ph$' placeholder can be
231 used at any position within file_path to cause a substitution with the
232 parametric job's index. A '$drmaa_hd_ph$' placeholder at the beginning
233 of file_path denotes the remaining portion of the file_path as a rela‐
234 tive file specification resolved relative to the job user's home direc‐
235 tory at the host where the file is located. A '$drmaa_wd_ph$' place‐
236 holder at the beginning of file_path denotes the remaining portion of
237 the file_path as a relative file specification resolved relative to the
238 job's working directory at the host where the file is located. The
239 file_path must be specified in a syntax that is common at the host
240 where the file is located. If set and the file can't be read the job
241 enters the state DRMAA_PS_FAILED.
242 drmaa_output_path - "[<hostname>]:<file_path>"
244 Specifies the standard output of the job. If not explicitly set in the
245 job template, the whereabouts of the job's output stream is not
246 defined. If set, this attribute specifies the network path of the job's
247 output stream file.
248 When the 'drmaa_transfer_files' job template attribute is supported and
250 contains the character 'o', the output file will be transferred by Grid
251 Engine to the specified host or to the submit host if no hostname is
252 specified. When the 'drmaa_transfer_files' job template attribute is
253 not supported or does not contain the character 'o', the output file is
254 always kept at the host where the job is executed regardless of any
255 hostname specified.
256 If the DRMAA job template will be used for of bulk job submission (see
258 also drmaa_run_bulk_job(3)) the '$drmaa_incr_ph$' placeholder can be
259 used at any position within the file_path to cause a substitution with
260 the parametric job's index. A '$drmaa_hd_ph$' placeholder at the
261 beginning of file_path denotes the remaining portion of the file_path
262 as a relative file specification resolved relative to the job user's
263 home directory at the host where the file is located. A '$drmaa_wd_ph$'
264 placeholder at the beginning of the file_path denotes the remaining
265 portion of file_path as a relative file specification resolved relative
266 to the job's working directory at the host where the file is located.
267 The file_path must be specified in a syntax that is common at the host
268 where the file is located. If set and the file can't be written before
269 execution the job enters the state DRMAA_PS_FAILED.
270 drmaa_error_path - "[<hostname>]:<file_path>"
272 Specifies the standard error of the job. If not explicitly set in the
273 job template, the whereabouts of the job's error stream is not defined.
274 If set, this attribute specifies the network path of the job's error
275 stream file.
276 When the 'drmaa_transfer_files' job template attribute is supported and
278 contains the character 'e', the output file will be transferred by Grid
279 Engine to the specified host or to the submit host if no hostname is
280 specified. When the 'drmaa_transfer_files' job template attribute is
281 not supported or does not contain the character 'e', the error file is
282 always kept at the host where the job is executed regardless of any
283 hostname specified.
284 If the DRMAA job template will be used for of bulk job submission (see
286 also drmaa_run_bulk_job(3)) the '$drmaa_incr_ph$' placeholder can be
287 used at any position within the file_path to cause a substitution with
288 the parametric job's index. A '$drmaa_hd_ph$' placeholder at the
289 beginning of the file_path denotes the remaining portion of the
290 file_path as a relative file specification resolved relative to the job
291 user's home directory at the host where the file is located. A
292 '$drmaa_wd_ph$' placeholder at the beginning of the file_path denotes
293 the remaining portion of the file_path as a relative file specification
294 resolved relative to the job's working directory at the host where the
295 file is located. The file_path must be specified in a syntax that is
296 common at the host where the file is located. If set and the file can't
297 be written before execution the job enters the state DRMAA_PS_FAILED.
298 The attribute name is drmaa_error_path.
299 drmaa_join_files - "{y|n}"
302 Specifies if the job's error stream should be intermixed with the out‐
303 put stream. If not explicitly set in the job template the attribute
304 defaults to 'n'. Either 'y' or 'n' can be specified. If 'y' is speci‐
305 fied Grid Engine will ignore the value of the 'drmaa_error_path' job
306 template attribute and intermix the standard error stream with the
307 standard output stream as specified with 'drmaa_output_path'.
308 drmaa_v_argv - "argv1 argv2 ..."
310 Specifies the arguments to the job.
311 drmaa_job_category - "<category>"
313 Specifies the DRMAA job category. The category string is used by Grid
314 Engine as a reference into the qtask(5) file. Certain qsub(1) options
315 used in the referenced qtask file line are applied to the job template
316 before submission to allow site-specific resolving of resources and/or
317 policies. The cluster qtask file, the local qtask file, and the user
318 qtask file are searched. Job settings resulting from job template cate‐
319 gory are overridden by settings resulting from the job template
320 drmaa_native_specification attribute as well as by explicit DRMAA job
321 template settings.
322 In order to avoid collisions with command names in the qtask files, it
324 is recommended that DRMAA job category names take the form: <cate‐
325 gory_name>.cat.
326 The options -help, -sync, -t, -verify, and -w w|v are ignored. The
328 -cwd option is ignored unless the $SGE_DRMAA_ALLOW_CWD environment
329 variable is set.
330 drmaa_native_specification - "<native_specification>"
332 Specifies Grid Engine native qsub(1) options which will be interpreted
333 as part of the DRMAA job template. All options available to qsub(1)
334 command may be used in the native_specification, except for -help,
335 -sync, -t, -verify, and -w w|v. The -cwd option may only be used if
336 the SGE_DRMAA_ALLOW_CWD environment variable is set. This is because
337 the current parsing algorithm for -cwd is not thread-safe. Options set
338 in the native specification will be overridden by the corresponding
339 DRMAA attributes. See qsub(1) for more information on qsub options.
340 drmaa_v_env - "<name1>=<value1> <name2>=<value2> ...
342 Specifies the job environment. Each environment value defines the
343 remote environment. The value overrides the remote environment values
344 if there is a collision.
345 drmaa_v_email - "<email1> <email2> ...
347 Specifies e-mail addresses that are used to report the job completion
348 and status.
349 drmaa_block_email - "{0|1}"
351 Specifies whether e-mail sending shall blocked or not. By default
352 email is not sent. If, however, a setting in a cluster or user set‐
353 tings file or the email in association with job events, the
354 'drmaa_block_email' attribute will override that setting, causing no
355 email to be sent.
356 drmaa_start_time - "[[[[CC]YY/]MM/]DD] hh:mm[:ss] [{-|+}UU:uu]"
358 Specifies the earliest time when the job may be eligible to be run
359 where
360 CC is the first two digits of the year (century-1)
362 YY is the last two digits of the year
363 MM is the two digits of the month [01,12]
364 DD is the two digit day of the month [01,31]
365 hh is the two digit hour of the day [00,23]
366 mm is the two digit minute of the day [00,59]
367 ss is the two digit second of the minute [00,61]
368 UU is the two digit hours since (before) UTC
369 uu is the two digit minutes since (before) UTC
370 If the optional UTC-offset is not specified, the offset associated with
372 the local timezone will be used. If the day (DD) is not specified, the
373 current day will be used unless the specified hour:mm:ss has already
374 elapsed, in which case the next day will be used. Similarly for month
375 (MM), year (YY), and century-1 (CC). Example: The time: Sep 3 4:47:27
376 PM PDT 2002, could be represented as: 2002/09/03 16:47:27 -07:00.
377 drmaa_transfer_files - "[i][o][e]"
379 Specifies, which of the standard I/O files (stdin, stdout and stderr)
380 are to be transferred to/from the execution host. If not set, defaults
381 to "". Any combination of 'e', 'i' and 'o' may be specified. See
382 drmaa_input_path, drmaa_output_path and drmaa_error_path for informa‐
383 tion about how to specify the standard input file, standard output file
384 and standard error file. The file transfer mechanism itself must be
385 configured by the administrator (see sge_conf(5) ). When it is config‐
386 ured, the administrator has to enable drmaa_transfer_files. If it is
387 not configured, "drmaa_transfer_files" is not enabled and can't be
388 used.
389
391 SGE_DRMAA_ALLOW_CWD
392 Enables the parsing of the -cwd option from the
393 sge_request file(s), job category, and/or the native
394 specification attribute. This option is disabled by
395 default because the algorithm for parsing the -cwd
396 option is not thread-safe.
397 GE_ROOT Specifies the location of the Grid Engine standard con‐
399 figuration files.
400 GE_CELL If set, specifies the default Grid Engine cell to be
402 used. To address a Grid Engine cell Grid Engine uses (in
403 the order of precedence):
404 The name of the cell specified in the environment
406 variable GE_CELL, if it is set.
407 The name of the default cell, i.e. default.
409 GE_DEBUG_LEVEL If set, specifies that debug information should be writ‐
412 ten to stderr. In addition the level of detail in which
413 debug information is generated is defined.
414 GE_QMASTER_PORT
416 If set, specifies the tcp port on which ge_qmaster(8) is
417 expected to listen for communication requests. Most
418 installations will use a services map entry instead to
419 define that port.
420
422 Upon successful completion, drmaa_get_attribute_names(), drmaa_get_vec‐
423 tor_attribute_names(), and drmaa_get_next_attr_name() return
424 DRMAA_ERRNO_SUCCESS. Other values indicate an error. Up to
425 error_diag_len characters of error related diagnosis information is
426 then provided in the buffer error_diagnosis.
427
429 The drmaa_get_attribute_names(), drmaa_get_vector_attribute_names(),
430 and drmaa_get_next_attr_name() functions will fail if:
431 DRMAA_ERRNO_INTERNAL_ERROR
433 Unexpected or internal DRMAA error, like system call failure, etc.
434 DRMAA_ERRNO_DRM_COMMUNICATION_FAILURE
436 Could not contact DRM system for this request.
437 DRMAA_ERRNO_AUTH_FAILURE
439 The specified request is not processed successfully due to authoriza‐
440 tion failure.
441 DRMAA_ERRNO_INVALID_ARGUMENT
443 The input value for an argument is invalid.
444 DRMAA_ERRNO_NO_ACTIVE_SESSION
446 Failed because there is no active session.
447 DRMAA_ERRNO_NO_MEMORY
449 Failed allocating memory.
450 The drmaa_get_next_attr_name() will fail if:
452 DRMAA_ERRNO_INVALID_ATTRIBUTE_VALUE
454 When there are no more entries in the vector.
455
457 drmaa_jobtemplate(3)and drmaa_submit(3).
458GE 6.2u5 $Date: 2008/08/07 13:06:27 $ drmaa_attributes(3)