1drmaa_attributes(3)            Grid Engine DRMAA           drmaa_attributes(3)
2
3
4

NAME

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

SYNOPSIS

11       #include "drmaa.h"
12
13       int drmaa_get_attribute_names(
14              drmaa_attr_names_t **values,
15              char *error_diagnosis,
16              size_t error_diag_len
17       );
18
19       int drmaa_get_vector_attribute_names(
20              drmaa_attr_names_t **values,
21              char *error_diagnosis,
22              size_t error_diag_len
23       );
24
25       int drmaa_get_next_attr_name(
26              drmaa_attr_names_t* values,
27              char *value,
28              int value_len
29       );
30
31       int drmaa_get_next_attr_value(
32              drmaa_attr_values_t* values,
33              char *value,
34              int value_len
35       );
36
37       int drmaa_get_num_attr_names(
38              drmaa_attr_names_t* values,
39              int *size
40       );
41
42       void drmaa_release_attr_names(
43              drmaa_attr_names_t* values
44       );
45

DESCRIPTION

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
60   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
72   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
78   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
83   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
87   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
95       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
101       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
107       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
112       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
117       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
121       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
126       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
133   Attribute Correlations
134       The following DRMAA attributes  correspond  to  the  following  qsub(1)
135       options:
136
137              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
156              * See the individual attribute description below
157

DRMAA JOB TEMPLATE ATTRIBUTES

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
167       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
181   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
189   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
205       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
211   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
215   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
221       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
229       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
243   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
249       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
257       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
271   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
277       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
285       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
300
301   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
309   drmaa_v_argv - "argv1 argv2 ..."
310       Specifies the arguments to the job.
311
312   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
323       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
327       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
331   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
341   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
346   drmaa_v_email - "<email1> <email2> ...
347       Specifies  e-mail  addresses that are used to report the job completion
348       and status.
349
350   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
357   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
361              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
371       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
378   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

ENVIRONMENTAL VARIABLES

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
398       GE_ROOT        Specifies  the location of the Grid Engine standard con‐
399                      figuration files.
400
401       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
405                             The name of the cell specified in the environment
406                             variable GE_CELL, if it is set.
407
408                             The name of the default cell, i.e. default.
409
410
411       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
415       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

RETURN VALUES

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

ERRORS

429       The  drmaa_get_attribute_names(),   drmaa_get_vector_attribute_names(),
430       and drmaa_get_next_attr_name() functions will fail if:
431
432   DRMAA_ERRNO_INTERNAL_ERROR
433       Unexpected or internal DRMAA error, like system call failure, etc.
434
435   DRMAA_ERRNO_DRM_COMMUNICATION_FAILURE
436       Could not contact DRM system for this request.
437
438   DRMAA_ERRNO_AUTH_FAILURE
439       The  specified  request is not processed successfully due to authoriza‐
440       tion failure.
441
442   DRMAA_ERRNO_INVALID_ARGUMENT
443       The input value for an argument is invalid.
444
445   DRMAA_ERRNO_NO_ACTIVE_SESSION
446       Failed because there is no active session.
447
448   DRMAA_ERRNO_NO_MEMORY
449       Failed allocating memory.
450
451       The drmaa_get_next_attr_name() will fail if:
452
453   DRMAA_ERRNO_INVALID_ATTRIBUTE_VALUE
454       When there are no more entries in the vector.
455

SEE ALSO

457       drmaa_jobtemplate(3)and drmaa_submit(3).
458
459
460
461
462GE 6.2u5                 $Date: 2008/08/07 13:06:27 $      drmaa_attributes(3)
Impressum