drmaa_attributes(3)            Grid Engine DRMAA           drmaa_attributes(3)



[1mNAME[0m
       drmaa_get_attribute_names,            drmaa_get_vector_attribute_names,
       drmaa_get_next_attr_name,                     drmaa_get_num_attr_names,
       drmaa_release_attr_names - DRMAA job template attributes


[1mSYNOPSIS[0m
       [1m#include "drmaa.h"[0m

       [1mint drmaa_get_attribute_names([0m
              [1mdrmaa_attr_names_t **values,[0m
              [1mchar *error_diagnosis,[0m
              [1msize_t error_diag_len[0m
       [1m);[0m

       [1mint drmaa_get_vector_attribute_names([0m
              [1mdrmaa_attr_names_t **values,[0m
              [1mchar *error_diagnosis,[0m
              [1msize_t error_diag_len[0m
       [1m);[0m

       [1mint drmaa_get_next_attr_name([0m
              [1mdrmaa_attr_names_t* values,[0m
              [1mchar *value,[0m
              [1mint value_len[0m
       [1m);[0m

       [1mint drmaa_get_next_attr_value([0m
              [1mdrmaa_attr_values_t* values,[0m
              [1mchar *value,[0m
              [1mint value_len[0m
       [1m);[0m

       [1mint drmaa_get_num_attr_names([0m
              [1mdrmaa_attr_names_t* values,[0m
              [1mint *size[0m
       [1m);[0m

       [1mvoid drmaa_release_attr_names([0m
              [1mdrmaa_attr_names_t* values[0m
       [1m);[0m


[1mDESCRIPTION[0m
       The  drmaa_get_attribute_names()  function  returns into [4mvalues[24m a DRMAA
       names string vector containing the set of  supported  non-vector  DRMAA
       job template attribute names. The set includes supported DRMAA reserved
       attribute names and Grid Engine native attribute names.  The  names  in
       the     names     string     vector     can    be    extracted    using
       [4mdrmaa_get_next_attr_name[24m(3).  The number of names in the  names  string
       vector  can be determined using [4mdrmaa_get_num_attr_names[24m(3).  Note that
       this function is only available in the 1.0 implementation.  The  caller
       is responsible for releasing the names string vector returned into [4mval-[0m
       [4mues[24m using [4mdrmaa_release_attr_names[24m(3).  Use [4mdrmaa_set_attribute[24m(3)  and
       [4mdrmaa_get_attribute[24m(3)    for   setting   and   inspecting   non-vector
       attributes.

   [1mdrmaa_get_vector_attribute_names()[0m
       The drmaa_get_vector_attribute_names() function returns into  [4mvalues[24m  a
       DRMAA  names string vector containing the set of supported vector DRMAA
       job template attribute names. The set includes supported DRMAA reserved
       attribute  names  and  Grid Engine native attribute names. The names in
       the    names    string    vector     can     be     extracted     using
       [4mdrmaa_get_next_attr_name[24m(3).   The  caller is responsible for releasing
       the    names    string    vector    returned    into    [4mvalues[24m    using
       [4mdrmaa_release_attr_names[24m(3).    Use  [4mdrmaa_set_vector_attribute[24m(3)  and
       [4mdrmaa_get_vector_attribute[24m(3)  for  setting   and   inspecting   vector
       attributes.


   [1mdrmaa_get_next_attr_name()[0m
       Each  time  drmaa_get_next_attr_name()  is  called  it returns into the
       buffer, [4mvalue[24m, up to [4mvalue_len[24m bytes of the next entry  stored  in  the
       DRMAA  names  string  vector,  [4mvalues[24m.   Once  the  names list has been
       exhausted, DRMAA_ERRNO_NO_MORE_ELEMENTS is returned.


   [1mdrmaa_get_num_attr_names()[0m
       The drmaa_get_num_attr_names() returns into [4msize[24m the number of  entries
       in  the  DRMAA names string vector.  This function is only available in
       the 1.0 implementation.


   [1mdrmaa_release_attr_names()[0m
       The drmaa_release_attr_names() function releases all resources  associ-
       ated with the DRMAA names string vector, [4mvalues[24m.


   [1mAttribute Priorities[0m
       DRMAA  job  template  attributes can be set from six different sources.
       In order of precedence, from lowest to highest, these are: options  set
       by  DRMAA  automatically  by default, options set in the [4msge_request[24m(5)
       file(s),  options  set  in  the  script  file,  options  set   by   the
       drmaa_job_category  attribute, options set by the drmaa_native_specifi-
       cation attribute, and options set through other DRMAA attributes.

       By default DRMAA sets four options for all jobs.  These are "-p 0", "-b
       yes",  "-shell  no",  and "-w e".  This means that by default, all jobs
       will have priority 0, all jobs will  be  treated  as  binary,  i.e.  no
       scripts  args will be parsed, all jobs will be executed without a wrap-
       per shell, and jobs which are unschedulable will cause a submit  error.

       The  [4msge_request[24m(5)  file, found in the $GE_ROOT/$GE_CELL/common direc-
       tory, may contain options to be applied to all jobs.  The  .sge_request
       file  found  in the user's home directory or the current working direc-
       tory may also contain options to  be  applied  to  certain  jobs.   See
       [4msge_request[24m(5) for more information.

       If   the   [4msge_request[24m(5)   file   contains   "-b   no"   or   if   the
       drmaa_native_specification attribute is set and contains "-b  no",  the
       script  file  will  be  parsed  for  in-line  arguments.  Otherwise, no
       scripts args will be interpreted.  See [4mqsub[24m(1) for more information.

       If the drmaa_job_category attribute is set, and the category it  points
       to  exists  in  one  of the [4mqtask[24m(5) files, the options associated with
       that category will be applied to the job template.   See  [4mqtask[24m(5)  and
       the drmaa_job_category attribute below for more information.

       If  the  drmaa_native_specification  attribute is set, all options con-
       tained  therein  will  be  applied  to  the  job  template.   See   the
       drmaa_native_specification below for more information.

       Other  DRMAA attributes will override any previous settings.  For exam-
       ple, if the sge_request file contains "-j y", but the  drmaa_join_files
       attribute is set to "n", the ultimate result is that the input and out-
       put files will remain separate.

       For various reasons, some options are silently ignored by DRMAA.   Set-
       ting  any  of  these  options will have no effect.  The ignored options
       are: -cwd, -help, -sync, -t, -verify, -w w, and -w v.  The -cwd  option
       can    be    re-enabled    by   setting   the   environment   variable,
       SGE_DRMAA_ALLOW_CWD.  However, the -cwd option is not thread  safe  and
       should not be used in a multi-threaded context.


   [1mAttribute Correlations[0m
       The  following  DRMAA  attributes  correspond  to the following [4mqsub[24m(1)
       options:

              DRMAA Attribute                  qsub Option
              -------------------------------------------------------
              drmaa_remote_command             script file
              drmaa_v_argv                     script file args
              drmaa_js_state = "drmaa_hold"    -h
              drmaa_v_env                      -v
              drmaa_wd = $PWD                  -cwd
              drmaa_job_category               (qtsch qtask)*
              drmaa_native_specification       ALL*
              drmaa_v_email                    -M
              drmaa_block_email = "1"          -m n
              drmaa_start_time                 -a
              drmaa_job_name                   -N
              drmaa_input_path                 -i
              drmaa_output_path                -o
              drmaa_error_path                 -e
              drmaa_join_files                 -j
              drmaa_transfer_files             (prolog and epilog)*

              * See the individual attribute description below


[1mDRMAA JOB TEMPLATE ATTRIBUTES[0m
   [1mdrmaa_remote_command - "<remote_command>"[0m
       Specifies the remote command to execute. The [4mremote_command[24m must be the
       path  of  an  executable that is available at the job's execution host.
       If the path is relative, it is assumed to be relative  to  the  working
       directory,  usually  set  through  the  drmaa_wd attribute.  If working
       directory is not set, the path is assumed to be relative to the  user's
       home directory.

       The  file  pointed  to  by  remote_command  may either be an executable
       binary or an executable script.  If a script, it must include the  path
       to  the shell in a #! line at the beginning of the script.  By default,
       the remote command will be executed directly, as by [4mexec[24m(2).   To  have
       the remote command executed in a shell, such as to preserve environment
       settings, use the drmaa_native_specification attribute to  include  the
       "-shell  yes"  option.  Jobs which are executed by a wrapper shell fail
       differently from jobs which are executed directly.  When  a  job  which
       contains  a  user  error, such as an invalid path to the executable, is
       executed by a wrapper shell, the job  will  execute  successfully,  but
       exit  with a return code of 1.  When a job which contains such an error
       is executed directly, it will enter the DRMAA_PS_FAILED state upon exe-
       cution.


   [1mdrmaa_js_state - "{drmaa_hold|drmaa_active}"[0m
       Specifies  the  job state at submission. The string values 'drmaa_hold'
       and 'drmaa_active' are supported. When 'drmaa_active' is used  the  job
       is submitted in a runnable state.  When 'drmaa_hold' is used the job is
       submitted  in  user  hold  state   (either   DRMAA_PS_USER_ON_HOLD   or
       DRMAA_PS_USER_SYSTEM_ON_HOLD).  This attribute is largely equivalent to
       the [4mqsub[24m(1) submit option '-h'.


   [1mdrmaa_wd - "<directory_name>"[0m
       Specifies the  directory  name  where  the  job  will  be  executed.  A
       '$drmaa_hd_ph$'  placeholder  at  the  beginning  of the [4mdirectory_name[0m
       denotes the remaining string portion as a relative directory name  that
       is  resolved relative to the job user's home directory at the execution
       host. When the DRMAA job template is used for bulk job submission  (see
       also  [4mdrmaa_run_bulk_job[24m(3))  the  '$drmaa_incr_ph$' placeholder can be
       used at any position within [4mdirectory_name[24m to cause a substitution with
       the  parametric job's index.  The [4mdirectory_name[24m must be specified in a
       syntax that is common at the host where the job is executed. If set  to
       a  relative  path  and  no  placeholder is used, a path relative to the
       user's home directory is assumed.  If not set,  the  working  directory
       will default to the user's home directory.  If set and the given direc-
       tory does not exist the job will enter the DRMAA_PS_FAILED  state  when
       run.

       Note that the working directory path is the path on the execution host.
       If binary mode is disabled, an attempt to find the job script  will  be
       made, relative to the working directory path.  That means that the path
       to the script must be the same on both  the  submission  and  execution
       hosts.


   [1mdrmaa_job_name - "<job_name>"[0m
       Specifies  the job's name. Setting the job name is equivalent to use of
       [4mqsub[24m(1) submit option '-N' with [4mjob_name[24m as option argument.


   [1mdrmaa_input_path - "[<hostname>]:<file_path>"[0m
       Specifies the standard input of the job. Unless set elsewhere,  if  not
       explicitly  set  in  the job template, the job is started with an empty
       input stream. If the standard input is set  it  specifies  the  network
       path of the job's input stream file.

       When the 'drmaa_transfer_files' job template attribute is supported and
       contains the character 'i', the input file  will  be  fetched  by  Grid
       Engine  from  the specified host or from the submit host if no [4mhostname[0m
       is specified. When the 'drmaa_transfer_files' job template attribute is
       not  supported or does not contain the character 'i', the input file is
       always expected at the host where the job is executed regardless of any
       [4mhostname[24m specified.

       If  the  DRMAA  job template will be used for bulk job submission, (See
       also [4mdrmaa_run_bulk_job[24m(3)) the '$drmaa_incr_ph$'  placeholder  can  be
       used  at any position within [4mfile_path[24m to cause a substitution with the
       parametric job's index. A '$drmaa_hd_ph$' placeholder at the  beginning
       of  [4mfile_path[24m denotes the remaining portion of the [4mfile_path[24m as a rela-
       tive file specification resolved relative to the job user's home direc-
       tory  at  the  host where the file is located. A '$drmaa_wd_ph$' place-
       holder at the beginning of [4mfile_path[24m denotes the remaining  portion  of
       the [4mfile_path[24m as a relative file specification resolved relative to the
       job's working directory at the host where  the  file  is  located.  The
       [4mfile_path[24m  must  be  specified  in  a syntax that is common at the host
       where the file is located. If set and the file can't be  read  the  job
       enters the state DRMAA_PS_FAILED.


   [1mdrmaa_output_path - "[<hostname>]:<file_path>"[0m
       Specifies  the standard output of the job. If not explicitly set in the
       job template, the  whereabouts  of  the  job's  output  stream  is  not
       defined. If set, this attribute specifies the network path of the job's
       output stream file.

       When the 'drmaa_transfer_files' job template attribute is supported and
       contains the character 'o', the output file will be transferred by Grid
       Engine to the specified host or to the submit host if  no  [4mhostname[24m  is
       specified.  When  the  'drmaa_transfer_files' job template attribute is
       not supported or does not contain the character 'o', the output file is
       always  kept  at  the  host where the job is executed regardless of any
       [4mhostname[24m specified.

       If the DRMAA job template will be used for of bulk job submission  (see
       also  [4mdrmaa_run_bulk_job[24m(3))  the  '$drmaa_incr_ph$' placeholder can be
       used at any position within the [4mfile_path[24m to cause a substitution  with
       the  parametric  job's  index.   A  '$drmaa_hd_ph$'  placeholder at the
       beginning of [4mfile_path[24m denotes the remaining portion of  the  [4mfile_path[0m
       as  a  relative  file specification resolved relative to the job user's
       home directory at the host where the file is located. A '$drmaa_wd_ph$'
       placeholder  at  the  beginning  of the [4mfile_path[24m denotes the remaining
       portion of [4mfile_path[24m as a relative file specification resolved relative
       to  the  job's working directory at the host where the file is located.
       The [4mfile_path[24m must be specified in a syntax that is common at the  host
       where  the file is located. If set and the file can't be written before
       execution the job enters the state DRMAA_PS_FAILED.


   [1mdrmaa_error_path - "[<hostname>]:<file_path>"[0m
       Specifies the standard error of the job. If not explicitly set  in  the
       job template, the whereabouts of the job's error stream is not defined.
       If set, this attribute specifies the network path of  the  job's  error
       stream file.

       When the 'drmaa_transfer_files' job template attribute is supported and
       contains the character 'e', the output file will be transferred by Grid
       Engine  to  the  specified host or to the submit host if no [4mhostname[24m is
       specified. When the 'drmaa_transfer_files' job  template  attribute  is
       not  supported or does not contain the character 'e', the error file is
       always kept at the host where the job is  executed  regardless  of  any
       [4mhostname[24m specified.

       If  the DRMAA job template will be used for of bulk job submission (see
       also [4mdrmaa_run_bulk_job[24m(3)) the '$drmaa_incr_ph$'  placeholder  can  be
       used  at any position within the [4mfile_path[24m to cause a substitution with
       the parametric job's  index.   A  '$drmaa_hd_ph$'  placeholder  at  the
       beginning  of  the  [4mfile_path[24m  denotes  the  remaining  portion  of the
       [4mfile_path[24m as a relative file specification resolved relative to the job
       user's  home  directory  at  the  host  where  the  file  is located. A
       '$drmaa_wd_ph$' placeholder at the beginning of the  [4mfile_path[24m  denotes
       the remaining portion of the [4mfile_path[24m as a relative file specification
       resolved relative to the job's working directory at the host where  the
       file  is  located.  The [4mfile_path[24m must be specified in a syntax that is
       common at the host where the file is located. If set and the file can't
       be  written  before execution the job enters the state DRMAA_PS_FAILED.
       The attribute name is drmaa_error_path.



   [1mdrmaa_join_files - "{y|n}"[0m
       Specifies if the job's error stream should be intermixed with the  out-
       put  stream.   If  not explicitly set in the job template the attribute
       defaults to 'n'. Either 'y' or 'n' can be specified. If 'y'  is  speci-
       fied  Grid  Engine  will ignore the value of the 'drmaa_error_path' job
       template attribute and intermix the  standard  error  stream  with  the
       standard output stream as specified with 'drmaa_output_path'.


   [1mdrmaa_v_argv - "argv1 argv2 ..."[0m
       Specifies the arguments to the job.


   [1mdrmaa_job_category - "<category>"[0m
       Specifies  the  DRMAA job category. The [4mcategory[24m string is used by Grid
       Engine as a reference into the [4mqtask[24m(5) file. Certain  [4mqsub[24m(1)  options
       used  in the referenced qtask file line are applied to the job template
       before submission to allow site-specific resolving of resources  and/or
       policies.   The  cluster qtask file, the local qtask file, and the user
       qtask file are searched. Job settings resulting from job template cate-
       gory  are  overridden  by  settings  resulting  from  the  job template
       drmaa_native_specification attribute as well as by explicit  DRMAA  job
       template settings.

       In  order to avoid collisions with command names in the qtask files, it
       is recommended that DRMAA job category  names  take  the  form:  <cate-
       gory_name>.cat.

       The  options  -help,  -sync,  -t, -verify, and -w w|v are ignored.  The
       -cwd option is  ignored  unless  the  $SGE_DRMAA_ALLOW_CWD  environment
       variable is set.


   [1mdrmaa_native_specification - "<native_specification>"[0m
       Specifies  Grid Engine native [4mqsub[24m(1) options which will be interpreted
       as part of the DRMAA job template.  All options  available  to  [4mqsub[24m(1)
       command  may  be  used  in  the [4mnative_specification[24m, except for -help,
       -sync, -t, -verify, and -w w|v.  The -cwd option may only  be  used  if
       the  SGE_DRMAA_ALLOW_CWD  environment variable is set.  This is because
       the current parsing algorithm for -cwd is not thread-safe.  Options set
       in  the  [4mnative[24m  [4mspecification[24m  will be overridden by the corresponding
       DRMAA attributes.  See [4mqsub[24m(1) for more information on qsub options.


   [1mdrmaa_v_env - "<name1>=<value1> <name2>=<value2> ...[0m
       Specifies the job  environment.  Each  environment  [4mvalue[24m  defines  the
       remote  environment.  The [4mvalue[24m overrides the remote environment values
       if there is a collision.


   [1mdrmaa_v_email - "<email1> <email2> ...[0m
       Specifies e-mail addresses that are used to report the  job  completion
       and status.


   [1mdrmaa_block_email - "{0|1}"[0m
       Specifies  whether  e-mail  sending  shall  blocked or not.  By default
       email is not sent.  If, however, a setting in a cluster  or  user  set-
       tings   file   or  the  email  in  association  with  job  events,  the
       'drmaa_block_email' attribute will override that  setting,  causing  no
       email to be sent.


   [1mdrmaa_start_time - "[[[[CC]YY/]MM/]DD] hh:mm[:ss] [{-|+}UU:uu]"[0m
       Specifies  the  earliest  time  when  the job may be eligible to be run
       where

              CC is the first two digits of the year (century-1)
              YY is the last two digits of the year
              MM is the two digits of the month [01,12]
              DD is the two digit day of the month [01,31]
              hh is the two digit hour of the day [00,23]
              mm is the two digit minute of the day [00,59]
              ss is the two digit second of the minute [00,61]
              UU is the two digit hours since (before) UTC
              uu is the two digit minutes since (before) UTC

       If the optional UTC-offset is not specified, the offset associated with
       the  local timezone will be used. If the day (DD) is not specified, the
       current day will be used unless the specified  hour:mm:ss  has  already
       elapsed,  in which case the next day will be used.  Similarly for month
       (MM), year (YY), and century-1 (CC).  Example: The time: Sep 3  4:47:27
       PM PDT 2002, could be represented as: 2002/09/03 16:47:27 -07:00.


   [1mdrmaa_transfer_files - "[i][o][e]"[0m
       Specifies,  which  of the standard I/O files (stdin, stdout and stderr)
       are to be transferred to/from the execution host. If not set,  defaults
       to  "".  Any  combination  of  'e',  'i' and 'o' may be specified.  See
       drmaa_input_path, drmaa_output_path and drmaa_error_path  for  informa-
       tion about how to specify the standard input file, standard output file
       and standard error file.  The file transfer mechanism  itself  must  be
       configured  by the administrator (see [4msge_conf[24m(5) ). When it is config-
       ured, the administrator has to enable drmaa_transfer_files.  If  it  is
       not  configured,  "drmaa_transfer_files"  is  not  enabled and can't be
       used.


[1mENVIRONMENTAL VARIABLES[0m
       [1mSGE_DRMAA_ALLOW_CWD[0m
                      Enables  the  parsing  of  the  -cwd  option  from   the
                      sge_request  file(s),  job  category,  and/or the native
                      specification attribute.  This  option  is  disabled  by
                      default  because  the  algorithm  for  parsing  the -cwd
                      option is not thread-safe.

       [1mGE_ROOT        [22mSpecifies the location of the Grid Engine standard  con-
                      figuration files.

       [1mGE_CELL        [22mIf  set,  specifies  the  default Grid Engine cell to be
                      used. To address a Grid Engine cell Grid Engine uses (in
                      the order of precedence):

                             The name of the cell specified in the environment
                             variable GE_CELL, if it is set.

                             The name of the default cell, i.e. [1mdefault[22m.


       [1mGE_DEBUG_LEVEL [22mIf set, specifies that debug information should be writ-
                      ten  to stderr. In addition the level of detail in which
                      debug information is generated is defined.

       [1mGE_QMASTER_PORT[0m
                      If set, specifies the tcp port on which [4mge_qmaster[24m(8) is
                      expected  to  listen  for  communication requests.  Most
                      installations will use a services map entry  instead  to
                      define that port.

[1mRETURN VALUES[0m
       Upon successful completion, drmaa_get_attribute_names(), drmaa_get_vec-
       tor_attribute_names(),    and     drmaa_get_next_attr_name()     return
       DRMAA_ERRNO_SUCCESS.   Other   values   indicate   an   error.   Up  to
       [4merror_diag_len[24m characters of error  related  diagnosis  information  is
       then provided in the buffer [4merror_diagnosis[24m.


[1mERRORS[0m
       The   drmaa_get_attribute_names(),  drmaa_get_vector_attribute_names(),
       and drmaa_get_next_attr_name() functions will fail if:

   [1mDRMAA_ERRNO_INTERNAL_ERROR[0m
       Unexpected or internal DRMAA error, like system call failure, etc.

   [1mDRMAA_ERRNO_DRM_COMMUNICATION_FAILURE[0m
       Could not contact DRM system for this request.

   [1mDRMAA_ERRNO_AUTH_FAILURE[0m
       The specified request is not processed successfully due  to  authoriza-
       tion failure.

   [1mDRMAA_ERRNO_INVALID_ARGUMENT[0m
       The input value for an argument is invalid.

   [1mDRMAA_ERRNO_NO_ACTIVE_SESSION[0m
       Failed because there is no active session.

   [1mDRMAA_ERRNO_NO_MEMORY[0m
       Failed allocating memory.

       The drmaa_get_next_attr_name() will fail if:

   [1mDRMAA_ERRNO_INVALID_ATTRIBUTE_VALUE[0m
       When there are no more entries in the vector.


[1mSEE ALSO[0m
       [4mdrmaa_jobtemplate[24m(3)and [4mdrmaa_submit[24m(3).




GE 6.2u2                 $Date: 2008/08/07 13:06:27 $      drmaa_attributes(3)
