    NAME
         drmaa_allocate_job_template,      drmaa_delete_job_template,
         drmaa_set_attribute,                    drmaa_get_attribute,
         drmaa_set_vector_attribute,      drmaa_get_vector_attribute,
         drmaa_get_next_attr_value,  drmaa_release_attr_values - Grid
         Engine DRMAA job template handling

    SYNOPSIS
         #include "drmaa.h"

         int drmaa_allocate_job_template(
              drmaa_job_template_t **jt,
              char *error_diagnosis,
              size_t error_diag_len
         );

         int drmaa_delete_job_template(
              drmaa_job_template_t *jt,
              char *error_diagnosis,
              size_t error_diag_len
         );

         int drmaa_set_attribute(
              drmaa_job_template_t *jt,
              const char *name,
              const char *value,
              char *error_diagnosis,
              size_t error_diag_len
         );

         int drmaa_get_attribute(
              drmaa_job_template_t *jt,
              const char *name,
              char *value,
              size_t value_len,
              char *error_diagnosis,
              size_t error_diag_len
         );

         int drmaa_set_vector_attribute(
              drmaa_job_template_t *jt,
              const char *name,
              const char *value[],
              char *error_diagnosis,
              size_t error_diag_len
         );

         int drmaa_get_vector_attribute(
              drmaa_job_template_t *jt,
              const char *name,
              drmaa_attr_values_t **values,
              char *error_diagnosis,
              size_t error_diag_len
         );

         int drmaa_get_next_attr_value(
              drmaa_attr_values_t* values,
              char *value,
              int value_len
         );

         void drmaa_release_attr_values(
              drmaa_attr_values_t* values
         );

    DESCRIPTION
         The drmaa_allocate_job_template() function allocates  a  new
         DRMAA  job  template  into  jt. DRMAA job templates describe
         specifics of jobs that are submitted using  drmaa_run_job(3)
         and drmaa_run_bulk_jobs(3).

      drmaa_delete_job_template()
         The  drmaa_delete_job_template()   function   releases   all
         resources  associated  with  the DRMAA job template jt. Jobs
         that were submitted using the job template are not affected.

      drmaa_set_attribute()
         The drmaa_set_attribute() function stores  the  value  under
         name  for  the  referred  DRMAA job template, jt . Only non-
         vector attributes may be passed.

      drmaa_get_attribute()
         The drmaa_get_attribute() function returns into value up  to
         value_len  bytes  from  the string stored for the non-vector
         attribute, name, in the DRMAA job template, jt.

      drmaa_set_vector_attribute()
         The drmaa_set_vector_attribute() function stores the strings
         in value under name in the list of vector attributes for the
         refered DRMAA job template, jt . Only vector attributes  may
         be passed. The value pointer array must be NULL terminated.

      drmaa_get_vector_attribute()
         The  drmaa_get_vector_attribute()  function   returns   into
         values a DRMAA attribute string vector containing all string
         values stored in the vector attribute, name. The  values  in
         the  DRMAA  values  string  vector  can  be  extracted using
         drmaa_get_next_attr_value(3).  The caller is responsible for
         releasing  the  DRMAA  values  string  vector  returned into
         values using drmaa_release_attr_values(3).

      drmaa_get_next_attr_value()
         Each time drmaa_get_next_attr_value() is called  it  returns
         into value up to value_len bytes of the next entry stored in
         the DRMAA values string vector, values.

      drmaa_release_attr_values()
         The  drmaa_release_attr_values()   function   releases   all
         resources  associated  with  the DRMAA values string vector,
         values.

    ENVIRONMENTAL VARIABLES
         SGE_ROOT       Specifies the location  of  the  Grid  Engine
                        standard configuration files.

         SGE_CELL       If set, specifies  the  default  Grid  Engine
                        cell  to  be  used.  To address a Grid Engine
                        cell Grid Engine uses (in the order  of  pre-
                        cedence):

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

                             The  name  of  the  default  cell,  i.e.
                             default.

         SGE_DEBUG_LEVEL
                        If  set,  specifies  that  debug  information
                        should  be written to stderr. In addition the
                        level of detail in which debug information is
                        generated is defined.

         SGE_QMASTER_PORT
                        If set,  specifies  the  tcp  port  on  which
                        sge_qmaster(8) is expected to listen for com-
                        munication requests.  Most installations will
                        use  a  services  map entry instead to define
                        that port.

    RETURN VALUES
         Upon successful  completion,  drmaa_allocate_job_template(),
         drmaa_delete_job_template(),          drmaa_set_attribute(),
         drmaa_get_attribute(),         drmaa_set_vector_attribute(),
         drmaa_get_vector_attribute(),                            and
         drmaa_get_next_attr_value()   return    DRMAA_ERRNO_SUCCESS.
         Other  values indicate an error.  Up to error_diag_len char-
         acters of error related diagnosis information is  then  pro-
         vided in the buffer error_diagnosis.

    ERRORS
         The                           drmaa_allocate_job_template(),
         drmaa_delete_job_template(),          drmaa_set_attribute(),
         drmaa_get_attribute(),         drmaa_set_vector_attribute(),
         drmaa_get_vector_attribute(),                            and
         drmaa_get_next_attr_value() functions will fail if:

      DRMAA_ERRNO_INTERNAL_ERROR
         Unexpected  or  internal  DRMAA  error,  like  system   call
         failure, etc.

      DRMAA_ERRNO_DRM_COMMUNICATION_FAILURE
         Could not contact DRM system for this request.

      DRMAA_ERRNO_AUTH_FAILURE
         The specified request is not processed successfully  due  to
         authorization failure.

      DRMAA_ERRNO_INVALID_ARGUMENT
         The input value for an argument is invalid.

      DRMAA_ERRNO_NO_ACTIVE_SESSION
         Failed because there is no active session.

      DRMAA_ERRNO_NO_MEMORY
         Failed allocating memory.

         The drmaa_set_attribute()  and  drmaa_set_vector_attribute()
         will fail if:

      DRMAA_ERRNO_INVALID_ATTRIBUTE_FORMAT
         The format for the attribute value is invalid.

      DRMAA_ERRNO_INVALID_ATTRIBUTE_VALUE
         The value for the attribute is invalid.

      DRMAA_ERRNO_CONFLICTING_ATTRIBUTE_VALUES
         The value of this attribute is conflicting with a previously
         set attributes.

         The drmaa_get_attribute()  and  drmaa_get_vector_attribute()
         will fail if:

      DRMAA_ERRNO_INVALID_ATTRIBUTE_VALUE
         The specified attribute is not set in  the  DRMAA  job  tem-
         plate.

         The drmaa_get_next_attr_value() will fail if:

      DRMAA_ERRNO_INVALID_ATTRIBUTE_VALUE
         When there are no more entries in the vector.

    SEE ALSO
         drmaa_submit(3)and drmaa_attributes(3).