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. With the DRMAA 1.0 library, once the
76 names list has been exhausted, DRMAA_ERRNO_NO_MORE_ELEMENTS is
77 returned. With the DRMAA 0.95 library, once the names list has been
78 exhausted, DRMAA_ERRNO_INVALID_ATTRIBUTE_VALUE is returned. In order
79 to use the DRMAA 0.95 library, you must define the DRMAA_95 macro,
80 either in your application directly or through a compiler flag, such as
81 -DDRMAA_95.
82 drmaa_get_num_attr_names()
84 The drmaa_get_num_attr_names() returns into size the number of entries
85 in the DRMAA names string vector. This function is only available in
86 the 1.0 implementation.
87 drmaa_release_attr_names()
89 The drmaa_release_attr_names() function releases all resources associ‐
90 ated with the DRMAA names string vector, values.
91 Attribute Priorities
93 DRMAA job template attributes can be set from six different sources.
94 In order of precedence, from lowest to highest, these are: options set
95 by DRMAA automatically by default, options set in the sge_request(5)
96 file(s), options set in the script file, options set by the
97 drmaa_job_category attribute, options set by the drmaa_native_specifi‐
98 cation attribute, and options set through other DRMAA attributes.
99 By default DRMAA sets four options for all jobs. These are "-p 0", "-b
101 yes", "-shell no", and "-w e". This means that by default, all jobs
102 will have priority 0, all jobs will be treated as binary, i.e. no
103 scripts args will be parsed, all jobs will be executed without a wrap‐
104 per shell, and jobs which are unschedulable will cause a submit error.
105 The sge_request(5) file, found in the $SGE_ROOT/$SGE_CELL/common direc‐
107 tory, may contain options to be applied to all jobs. The .sge_request
108 file found in the user's home directory or the current working direc‐
109 tory may also contain options to be applied to certain jobs. See
110 sge_request(5) for more information.
111 If the sge_request(5) file contains "-b no" or if the
113 drmaa_native_specification attribute is set and contains "-b no", the
114 script file will be parsed for in-line arguments. Otherwise, no
115 scripts args will be interpreted. See qsub(1) for more information.
116 If the drmaa_job_category attribute is set, and the category it points
118 to exists in one of the qtask(5) files, the options associated with
119 that category will be applied to the job template. See qtask(5) and
120 the drmaa_job_category attribute below for more information.
121 If the drmaa_native_specification attribute is set, all options con‐
123 tained therein will be applied to the job template. See the
124 drmaa_native_specification below for more information.
125 Other DRMAA attributes will override any previous settings. For exam‐
127 ple, if the sge_request file contains "-j y", but the drmaa_join_files
128 attribute is set to "n", the ultimate result is that the input and out‐
129 put files will remain separate.
130 For various reasons, some options are silently ignored by DRMAA. Set‐
132 ting any of these options will have no effect. The ignored options
133 are: -cwd, -help, -t, -verify, -w w, and -w v. The -cwd option can be
134 re-enabled by setting the environment variable, SGE_DRMAA_ALLOW_CWD.
135 However, the -cwd option is not thread safe and should not be used in a
136 multi-threaded context.
137 Attribute Correlations
139 The following DRMAA attributes correspond to the following qsub(1)
140 options:
141 DRMAA Attribute qsub Option
143 -------------------------------------------------------
144 drmaa_remote_command script file
145 drmaa_v_argv script file args
146 drmaa_js_state = "drmaa_hold" -h
147 drmaa_v_env -v
148 drmaa_wd = $PWD -cwd
149 drmaa_job_category (qtsch qtask)*
150 drmaa_native_specification ALL*
151 drmaa_v_email -M
152 drmaa_block_email = "1" -m n
153 drmaa_start_time -a
154 drmaa_job_name -N
155 drmaa_input_path -i
156 drmaa_output_path -o
157 drmaa_error_path -e
158 drmaa_join_files -j
159 drmaa_transfer_files (prolog and epilog)*
160 * See the individual attribute description below
162
164 drmaa_remote_command - "<remote_command>"
165 Specifies the remote command to execute. The remote_command must be the
166 path of an executable that is available at the job's execution host.
167 If the path is relative, it is assumed to be relative to the working
168 directory, usually set through the drmaa_wd attribute. If working
169 directory is not set, the path is assumed to be relative to the user's
170 home directory.
171 The file pointed to by remote_command may either be an executable
173 binary or an executable script. If a script, it must include the path
174 to the shell in a #! line at the beginning of the script. By default,
175 the remote command will be executed directly, as by exec(2). To have
176 the remote command executed in a shell, such as to preserve environment
177 settings, use the drmaa_native_specification attribute to include the
178 "-shell yes" option. Jobs which are executed by a wrapper shell fail
179 differently from jobs which are executed directly. When a job which
180 contains a user error, such as an invalid path to the executable, is
181 executed by a wrapper shell, the job will execute successfully, but
182 exit with a return code of 1. When a job which contains such an error
183 is executed directly, it will enter the DRMAA_PS_FAILED state upon exe‐
184 cution.
185 drmaa_js_state - "{drmaa_hold|drmaa_active}"
187 Specifies the job state at submission. The string values 'drmaa_hold'
188 and 'drmaa_active' are supported. When 'drmaa_active' is used the job
189 is submitted in a runnable state. When 'drmaa_hold' is used the job is
190 submitted in user hold state (either DRMAA_PS_USER_ON_HOLD or
191 DRMAA_PS_USER_SYSTEM_ON_HOLD). This attribute is largely equivalent to
192 the qsub(1) submit option '-h'.
193 drmaa_wd - "<directory_name>"
195 Specifies the directory name where the job will be executed. A
196 '$drmaa_hd_ph$' placeholder at the beginning of the directory_name
197 denotes the remaining string portion as a relative directory name that
198 is resolved relative to the job user's home directory at the execution
199 host. When the DRMAA job template is used for bulk job submission (see
200 also drmaa_run_bulk_job(3)) the '$drmaa_incr_ph$' placeholder can be
201 used at any position within directory_name to cause a substitution with
202 the parametric job's index. The directory_name must be specified in a
203 syntax that is common at the host where the job is executed. If set to
204 a relative path and no placeholder is used, a path relative to the
205 user's home directory is assumed. If not set, the working directory
206 will default to the user's home directory. If set and the given direc‐
207 tory does not exist the job will enter the DRMAA_PS_FAILED state when
208 run.
209 Note that the working directory path is the path on the execution host.
211 If binary mode is disabled, an attempt to find the job script will be
212 made, relative to the working directory path. That means that the path
213 to the script must be the same on both the submission and execution
214 hosts.
215 drmaa_job_name - "<job_name>"
217 Specifies the job's name. Setting the job name is equivalent to use of
218 qsub(1) submit option '-N' with job_name as option argument.
219 drmaa_input_path - "[<hostname>]:<file_path>"
221 Specifies the standard input of the job. Unless set elsewhere, if not
222 explicitly set in the job template, the job is started with an empty
223 input stream. If the standard input is set it specifies the network
224 path of the job's input stream file.
225 When the 'drmaa_transfer_files' job template attribute is supported and
227 contains the character 'i', the input file will be fetched by Grid
228 Engine from the specified host or from the submit host if no hostname
229 is specified. When the 'drmaa_transfer_files' job template attribute is
230 not supported or does not contain the character 'i', the input file is
231 always expected at the host where the job is executed regardless of any
232 hostname specified.
233 If the DRMAA job template will be used for bulk job submission, (See
235 also drmaa_run_bulk_job(3)) the '$drmaa_incr_ph$' placeholder can be
236 used at any position within file_path to cause a substitution with the
237 parametric job's index. A '$drmaa_hd_ph$' placeholder at the beginning
238 of file_path denotes the remaining portion of the file_path as a rela‐
239 tive file specification resolved relative to the job user's home direc‐
240 tory at the host where the file is located. A '$drmaa_wd_ph$' place‐
241 holder at the beginning of file_path denotes the remaining portion of
242 the file_path as a relative file specification resolved relative to the
243 job's working directory at the host where the file is located. The
244 file_path must be specified in a syntax that is common at the host
245 where the file is located. If set and the file can't be read the job
246 enters the state DRMAA_PS_FAILED.
247 drmaa_output_path - "[<hostname>]:<file_path>"
249 Specifies the standard output of the job. If not explicitly set in the
250 job template, the whereabouts of the job's output stream is not
251 defined. If set, this attribute specifies the network path of the job's
252 output stream file.
253 When the 'drmaa_transfer_files' job template attribute is supported and
255 contains the character 'o', the output file will be transferred by Grid
256 Engine to the specified host or to the submit host if no hostname is
257 specified. When the 'drmaa_transfer_files' job template attribute is
258 not supported or does not contain the character 'o', the output file is
259 always kept at the host where the job is executed regardless of any
260 hostname specified.
261 If the DRMAA job template will be used for of bulk job submission (see
263 also drmaa_run_bulk_job(3)) the '$drmaa_incr_ph$' placeholder can be
264 used at any position within the file_path to cause a substitution with
265 the parametric job's index. A '$drmaa_hd_ph$' placeholder at the
266 beginning of file_path denotes the remaining portion of the file_path
267 as a relative file specification resolved relative to the job user's
268 home directory at the host where the file is located. A '$drmaa_wd_ph$'
269 placeholder at the beginning of the file_path denotes the remaining
270 portion of file_path as a relative file specification resolved relative
271 to the job's working directory at the host where the file is located.
272 The file_path must be specified in a syntax that is common at the host
273 where the file is located. If set and the file can't be written before
274 execution the job enters the state DRMAA_PS_FAILED.
275 drmaa_error_path - "[<hostname>]:<file_path>"
277 Specifies the standard error of the job. If not explicitly set in the
278 job template, the whereabouts of the job's error stream is not defined.
279 If set, this attribute specifies the network path of the job's error
280 stream file.
281 When the 'drmaa_transfer_files' job template attribute is supported and
283 contains the character 'e', the output file will be transferred by Grid
284 Engine to the specified host or to the submit host if no hostname is
285 specified. When the 'drmaa_transfer_files' job template attribute is
286 not supported or does not contain the character 'e', the error file is
287 always kept at the host where the job is executed regardless of any
288 hostname specified.
289 If the DRMAA job template will be used for of bulk job submission (see
291 also drmaa_run_bulk_job(3)) the '$drmaa_incr_ph$' placeholder can be
292 used at any position within the file_path to cause a substitution with
293 the parametric job's index. A '$drmaa_hd_ph$' placeholder at the
294 beginning of the file_path denotes the remaining portion of the
295 file_path as a relative file specification resolved relative to the job
296 user's home directory at the host where the file is located. A
297 '$drmaa_wd_ph$' placeholder at the beginning of the file_path denotes
298 the remaining portion of the file_path as a relative file specification
299 resolved relative to the job's working directory at the host where the
300 file is located. The file_path must be specified in a syntax that is
301 common at the host where the file is located. If set and the file can't
302 be written before execution the job enters the state DRMAA_PS_FAILED.
303 The attribute name is drmaa_error_path.
304 drmaa_join_files - "{y|n}"
307 Specifies if the job's error stream should be intermixed with the out‐
308 put stream. If not explicitly set in the job template the attribute
309 defaults to 'n'. Either 'y' or 'n' can be specified. If 'y' is speci‐
310 fied Grid Engine will ignore the value of the 'drmaa_error_path' job
311 template attribute and intermix the standard error stream with the
312 standard output stream as specified with 'drmaa_output_path'.
313 drmaa_v_argv - "argv1 argv2 ..."
315 Specifies the arguments to the job.
316 drmaa_job_category - "<category>"
318 Specifies the DRMAA job category. The category string is used by Grid
319 Engine as a reference into the qtask(5) file. Certain qsub(1) options
320 used in the referenced qtask file line are applied to the job template
321 before submission to allow site-specific resolving of resources and/or
322 policies. The cluster qtask file, the local qtask file, and the user
323 qtask file are searched. Job settings resulting from job template cate‐
324 gory are overridden by settings resulting from the job template
325 drmaa_native_specification attribute as well as by explicit DRMAA job
326 template settings.
327 In order to avoid collisions with command names in the qtask files, it
329 is recommended that DRMAA job category names take the form: <cate‐
330 gory_name>.cat.
331 The options -help, -t, -verify, and -w w|v are ignored. The -cwd
333 option is ignored unless the $SGE_DRMAA_ALLOW_CWD environment variable
334 is set.
335 drmaa_native_specification - "<native_specification>"
337 Specifies Grid Engine native qsub(1) options which will be interpreted
338 as part of the DRMAA job template. All options available to qsub(1)
339 command may be used in the native_specification, except for -help, -t,
340 -verify, and -w w|v. The -cwd option may only be used if the
341 SGE_DRMAA_ALLOW_CWD environment variable is set. This is because the
342 current parsing algorithm for -cwd is not thread-safe. Options set in
343 the native specification will be overridden by the corresponding DRMAA
344 attributes. See qsub(1) for more information on qsub options.
345 drmaa_v_env - "<name1>=<value1> <name2>=<value2> ...
347 Specifies the job environment. Each environment value defines the
348 remote environment. The value overrides the remote environment values
349 if there is a collision.
350 drmaa_v_email - "<email1> <email2> ...
352 Specifies e-mail addresses that are used to report the job completion
353 and status.
354 drmaa_block_email - "{0|1}"
356 Specifies whether e-mail sending shall blocked or not. By default
357 email is not sent. If, however, a setting in a cluster or user set‐
358 tings file or the email in association with job events, the
359 'drmaa_block_email' attribute will override that setting, causing no
360 email to be sent.
361 drmaa_start_time - "[[[[CC]YY/]MM/]DD] hh:mm[:ss] [{-|+}UU:uu]"
363 Specifies the earliest time when the job may be eligible to be run
364 where
365 CC is the first two digits of the year (century-1)
367 YY is the last two digits of the year
368 MM is the two digits of the month [01,12]
369 DD is the two digit day of the month [01,31]
370 hh is the two digit hour of the day [00,23]
371 mm is the two digit minute of the day [00,59]
372 ss is the two digit second of the minute [00,61]
373 UU is the two digit hours since (before) UTC
374 uu is the two digit minutes since (before) UTC
375 If the optional UTC-offset is not specified, the offset associated with
377 the local timezone will be used. If the day (DD) is not specified, the
378 current day will be used unless the specified hour:mm:ss has already
379 elapsed, in which case the next day will be used. Similarly for month
380 (MM), year (YY), and century-1 (CC). Example: The time: Sep 3 4:47:27
381 PM PDT 2002, could be represented as: 2002/09/03 16:47:27 -07:00.
382 drmaa_transfer_files - "[i][o][e]"
384 Specifies, which of the standard I/O files (stdin, stdout and stderr)
385 are to be transferred to/from the execution host. If not set, defaults
386 to "". Any combination of 'e', 'i' and 'o' may be specified. See
387 drmaa_input_path, drmaa_output_path and drmaa_error_path for informa‐
388 tion about how to specify the standard input file, standard output file
389 and standard error file. The file transfer mechanism itself must be
390 configured by the administrator (see sge_conf(5) ). When it is config‐
391 ured, the administrator has to enable drmaa_transfer_files. If it is
392 not configured, "drmaa_transfer_files" is not enabled and can't be
393 used.
394
396 SGE_DRMAA_ALLOW_CWD
397 Enables the parsing of the -cwd option from the
398 sge_request file(s), job category, and/or the native
399 specification attribute. This option is disabled by
400 default because the algorithm for parsing the -cwd
401 option is not thread-safe.
402 SGE_ROOT Specifies the location of the Grid Engine standard con‐
404 figuration files.
405 SGE_CELL If set, specifies the default Grid Engine cell to be
407 used. To address a Grid Engine cell Grid Engine uses (in
408 the order of precedence):
409 The name of the cell specified in the environment
411 variable SGE_CELL, if it is set.
412 The name of the default cell, i.e. default.
414 SGE_DEBUG_LEVEL
417 If set, specifies that debug information should be writ‐
418 ten to stderr. In addition the level of detail in which
419 debug information is generated is defined.
420 SGE_QMASTER_PORT
422 If set, specifies the tcp port on which sge_qmaster(8)
423 is expected to listen for communication requests. Most
424 installations will use a services map entry instead to
425 define that port.
426
428 Upon successful completion, drmaa_get_attribute_names(), drmaa_get_vec‐
429 tor_attribute_names(), and drmaa_get_next_attr_name() return
430 DRMAA_ERRNO_SUCCESS. Other values indicate an error. Up to
431 error_diag_len characters of error related diagnosis information is
432 then provided in the buffer error_diagnosis.
433
435 The drmaa_get_attribute_names(), drmaa_get_vector_attribute_names(),
436 and drmaa_get_next_attr_name() functions will fail if:
437 DRMAA_ERRNO_INTERNAL_ERROR
439 Unexpected or internal DRMAA error, like system call failure, etc.
440 DRMAA_ERRNO_DRM_COMMUNICATION_FAILURE
442 Could not contact DRM system for this request.
443 DRMAA_ERRNO_AUTH_FAILURE
445 The specified request is not processed successfully due to authoriza‐
446 tion failure.
447 DRMAA_ERRNO_INVALID_ARGUMENT
449 The input value for an argument is invalid.
450 DRMAA_ERRNO_NO_ACTIVE_SESSION
452 Failed because there is no active session.
453 DRMAA_ERRNO_NO_MEMORY
455 Failed allocating memory.
456 The drmaa_get_next_attr_name() will fail if:
458 DRMAA_ERRNO_INVALID_ATTRIBUTE_VALUE
460 When there are no more entries in the vector.
461
463 drmaa_jobtemplate(3)and drmaa_submit(3).
464GE 6.1 $Date: 2007/07/19 08:17:16 $ drmaa_attributes(3)