NAME

       drmaa_init, drmaa_exit - Start/finish Sun Grid Engine DRMAA session

SYNOPSIS

       #include "drmaa.h"

       int drmaa_init(
              const char *contact,
              char *error_diagnosis,
              size_t error_diag_len
       );

       int drmaa_exit(
              char *error_diagnosis,
              size_t error_diag_len
       );

DESCRIPTION

   drmaa_init()
       The  drmaa_init()  function  initializes  the  Sun  Grid  Engine DRMAA API library for all
       threads of the process and creates a new DRMAA session. This routine must be  called  once
       before  any  other  DRMAA  call, except for drmaa_version(3), drmaa_get_DRM_system(3), and
       drmaa_get_DRMAA_implementation(3).  Except  for  the  above  listed  functions,  no  DRMAA
       functions  may  be  called before the drmaa_init() function completes.  Any DRMAA function
       which  is  called   before   the   drmaa_init()   function   completes   will   return   a
       DRMAA_ERRNO_NO_ACTIVE_SESSION  error.  Contact is an implementation dependent string which
       may be used to specify which Sun Grid Engine cell to use. If contact is NULL, the  default
       Sun  Grid  Engine  cell  will  be  used.  In  the  1.0 implementation contact may have the
       following   value:   session=<session_id>.    To    determine    the    session_id,    the
       drmaa_get_contact(3)  function  should  be  called  after  the  session  has  already been
       initialized.  By passing the session=<session_id> string  to  the  drmaa_init()  function,
       instead  of  creating  a  new  session,  DRMAA  will  attempt  to reconnect to the session
       indicated by the session_id.  The result of reconnecting to a previous session is that all
       jobs  previously submitted in that session that are still running will be available in the
       DRMAA session.  Note, however, that jobs which ended before the call to  drmaa_init()  may
       not be available or may have no associated exit information or resource usage data.

   drmaa_exit()
       The  drmaa_exit()  function  closes  the  DRMAA session for all threads and must be called
       before process termination.  The drmaa_exit() function may be called only once by a single
       thread  in  the  process  and  may  only  be  called  after  the drmaa_init() function has
       completed.  Any DRMAA function, other  than  drmaa_init(3),  which  is  called  after  the
       drmaa_exit() function completes will return a DRMAA_ERRNO_NO_ACTIVE_SESSION error.

       The  drmaa_exit()  function  does necessary clean up of the DRMAA session state, including
       unregistering from the qmaster(8).  If  the  drmaa_exit()  function  is  not  called,  the
       qmaster  will  store  events  for the DRMAA client until the connection times out, causing
       extra work for the qmaster and consuming system resources.

       Submitted jobs are not affected by the drmaa_exit() function.

ENVIRONMENTAL VARIABLES

       SGE_ROOT       Specifies the location of the Sun Grid Engine standard configuration files.

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

                             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  the  sge_qmaster  is  expected  to
                      listen  for communication requests.  Most installations will use a services
                      map entry instead to define that port.

RETURN VALUES

       Upon successful completion,  drmaa_init()  and  drmaa_exit()  return  DRMAA_ERRNO_SUCCESS.
       Other  values  indicate  an  error.   Up  to  error_diag_len  characters  of error related
       diagnosis information is then provided in the buffer error_diagnosis.

ERRORS

       The drmaa_init() and drmaa_exit() 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.

       The drmaa_init() will fail if:

   DRMAA_ERRNO_INVALID_CONTACT_STRING
       Initialization failed due to invalid contact string.

   DRMAA_ERRNO_DEFAULT_CONTACT_STRING_ERROR
       Could not use the default contact string to connect to DRM system.

   DRMAA_ERRNO_DRMS_INIT_FAILED
       Initialization failed due to failure to init DRM system.

   DRMAA_ERRNO_ALREADY_ACTIVE_SESSION
       Initialization failed due to existing DRMAA session.

   DRMAA_ERRNO_NO_MEMORY
       Failed allocating memory.

       The drmaa_exit() will fail if:

   DRMAA_ERRNO_NO_ACTIVE_SESSION
       Failed because there is no active session.

   DRMAA_ERRNO_DRMS_EXIT_ERROR
       DRM system disengagement failed.

SEE ALSO

       drmaa_submit(3).