    NAME
         drmaa_synchronize,       drmaa_wait,        drmaa_wifexited,
         drmaa_wexitstatus,     drmaa_wifsignaled,    drmaa_wtermsig,
         drmaa_wcoredump, drmaa_wifaborted - Waiting for jobs to fin-
         ish

    SYNOPSIS
         #include "drmaa.h"

         int drmaa_synchronize(
              const char *job_ids[],
              signed long timeout,
              int dispose,
              char *error_diagnosis,
              size_t error_diag_len
         );

         int drmaa_wait(
              const char *job_id,
              char *job_id_out,
              size_t job_id_out_len,
              int *stat,
              signed long timeout,
              drmaa_attr_values_t **rusage,
              char *error_diagnosis,
              size_t error_diagnois_len
         );

         int drmaa_wifaborted(
              int *aborted,
              int stat,
              char *error_diagnosis,
              size_t error_diag_len
         );

         int drmaa_wifexited(
              int *exited,
              int stat,
              char *error_diagnosis,
              size_t error_diag_len
         );

         int drmaa_wifsignaled(
              int *signaled,
              int stat,
              char *error_diagnosis,
              size_t error_diag_len
         );

         int drmaa_wcoredump(
              int *core_dumped,
              int stat,
              char *error_diagnosis,
              size_t error_diag_len
         );

         int drmaa_wexitstatus(
              int *exit_status,
              int stat,
              char *error_diagnosis,
              size_t error_diag_len
         );

         int drmaa_wtermsig(
              char *signal,
              size_t signal_len,
              int stat,
              char *error_diagnosis,
              size_t error_diag_len
         );

    DESCRIPTION
         The drmaa_synchronize() function blocks the  calling  thread
         until  all jobs specified in job_ids have failed or finished
         execution. If job_ids contains  'DRMAA_JOB_IDS_SESSION_ALL',
         then  this function waits for all jobs submitted during this
         DRMAA session. The job_ids pointer array must be  NULL  ter-
         minated.

         To prevent blocking indefinitely in this  call,  the  caller
         may use the timeout, specifying how many seconds to wait for
         this call to complete before timing out. The  special  value
         DRMAA_TIMEOUT_WAIT_FOREVER  can be used to wait indefinitely
         for a result. The special value DRMAA_TIMEOUT_NO_WAIT can be
         used to return immediately. If the call exits before timeout
         seconds, all the specified jobs have completed or  the  cal-
         ling  thread  received  an  interrupt.   In  both cases, the
         return code is DRMAA_ERRNO_EXIT_TIMEOUT.

         The dispose parameter specifies how to treat reaping  infor-
         mation.  If  '0'  is  passed  to  this parameter, job finish
         information will still be available  when  drmaa_wait(3)  is
         used.  If  '1'  is  passed,  drmaa_wait(3) will be unable to
         access this job's finish information.

      drmaa_wait()
         The drmaa_wait() function blocks the calling thread until  a
         job fails or finishes execution.  This routine is modeled on
         the   wait4(3)    routine.    If    the    special    string
         'DRMAA_JOB_IDS_SESSION_ANY'  is  passed as job_id, this rou-
         tine will wait for any job from the session.  Otherwise  the
         job_id must be the job identifier of a job or array job task
         that was submitted during the session.

         To prevent blocking indefinitely in this  call,  the  caller
         may  use  timeout,  specifying  how many seconds to wait for
         this call to complete before timing out. The  special  value
         DRMAA_TIMEOUT_WAIT_FOREVER can be to wait indefinitely for a
         result. The special value DRMAA_TIMEOUT_NO_WAIT can be  used
         to  return  immediately.  If  the  call exits before timeout
         seconds have passed, all the specified jobs  have  completed
         or the calling thread received an interrupt.  In both cases,
         the return code is DRMAA_ERRNO_EXIT_TIMEOUT.

         The routine reaps jobs on a successful call, so  any  subse-
         quent   calls   to   drmaa_wait(3)  will  fail  returning  a
         DRMAA_ERRNO_INVALID_JOB error,  meaning  that  the  job  has
         already  been  reaped.  This error is the same as if the job
         were unknown. Returning due to  an  elapsed  timeout  or  an
         interrupt  does  not cause the job information to be reaped.
         This means that, in this  case,  it  is  possible  to  issue
         drmaa_wait(3) multiple times for the same job_id.

         If job_id_out is not a null pointer, then on return  from  a
         successful  drmaa_wait(3) call, up to job_id_out_len charac-
         ters from the job id of  the  failed  or  finished  job  are
         returned.

         If stat is not a null pointer, then on return  from  a  suc-
         cessful  drmaa_wait(3) call, the status of the job is stored
         in the integer pointed to by stat.  stat  indicates  whether
         job  failed  or finished and other information. The informa-
         tion encoded in  the  integer  value  can  be  accessed  via
         drmaa_wifaborted(3)  drmaa_wifexited(3) drmaa_wifsignaled(3)
         drmaa_wcoredump(3) drmaa_wexitstatus(3) drmaa_wtermsig(3).

         If rusage is not a null pointer, then on return from a  suc-
         cessful drmaa_wait(3) call, a summary of the  resources used
         by the terminated job is returned in form of a DRMAA  values
         string   vector. The entries in the DRMAA values string vec-
         tor can  be  extracted  using  drmaa_get_next_attr_value(3).
         Each string returned by drmaa_get_next_attr_value(3) will be
         of the  format  <name>=<value>,  where  <name>  and  <value>
         specify  name  and  amount of resources consumed by the job,
         respectively.  See accounting(5) for an explanation  of  the
         resource information.

      drmaa_wifaborted()
         The drmaa_wifaborted() function evaluates into  the  integer
         pointed  to by aborted a non-zero value if stat was returned
         from a job that ended before entering the running state.

      drmaa_wifexited()
         The drmaa_wifexited() function evaluates  into  the  integer
         pointed  to  by exited a non-zero value if stat was returned
         from a job that terminated normally. A zero value  can  also
         indicate  that  although the job has terminated normally, an
         exit status is not  available,  or  that  it  is  not  known
         whether   the   job   terminated  normally.  In  both  cases
         drmaa_wexitstatus(3) will not provide exit  status  informa-
         tion.  A  non-zero  value  returned in exited indicates more
         detailed   diagnosis   can   be   provided   by   means   of
         drmaa_wifsignaled(3),          drmaa_wtermsig(3)         and
         drmaa_wcoredump(3).

      drmaa_wifsignaled()
         The drmaa_wifsignaled() function evaluates into the  integer
         pointed to by signaled a non-zero value if stat was returned
         for a job that terminated due to the receipt of a signal.  A
         zero  value can also indicate that although the job has ter-
         minated due to the receipt of a signal, the  signal  is  not
         available, or it is not known whether the job terminated due
         to the receipt of a signal. In both cases  drmaa_wtermsig(3)
         will  not  provide  signal  information.  A  non-zero  value
         returned in signaled indicates  signal  information  can  be
         retrieved by means of drmaa_wtermsig(3).

      drmaa_wcoredump()
         If drmaa_wifsignaled(3) returned a  non-zero  value  in  the
         signaled parameter, the drmaa_wcoredump() function evaluates
         into the integer pointed to by core_dumped a non-zero  value
         if a core image of the terminated job was created.

      drmaa_wexitstatus()
         If drmaa_wifexited(3)  returned  a  non-zero  value  in  the
         exited parameter, the drmaa_wexitstatus() function evaluates
         into the integer pointed to by exit_code the exit code  that
         the  job  passed to exit(2) or the value that the child pro-
         cess returned from main.

      drmaa_wtermsig()
         If drmaa_wifsignaled(3) returned a  non-zero  value  in  the
         signaled  parameter, the drmaa_wtermsig() function evaluates
         into  signal  up  to  signal_len  characters  of  a   string
         representation  of the signal that caused the termination of
         the job. For signals declared by POSIX.1, the symbolic names
         are  returned  (e.g.,  SIGABRT,  SIGALRM).  For  signals not
         declared by POSIX, any other string may be returned.

    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
                        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_run_job(),
         drmaa_run_bulk_jobs(),  and  drmaa_get_next_job_id()  return
         DRMAA_ERRNO_SUCCESS. Other values indicate an error.  Up  to
         error_diag_len  characters of error related diagnosis infor-
         mation is then provided in the buffer error_diagnosis.

    ERRORS
         The  drmaa_synchronize(),  drmaa_wait(),  drmaa_wifexited(),
         drmaa_wexitstatus(),  drmaa_wifsignaled(), drmaa_wtermsig(),
         drmaa_wcoredump(), and drmaa_wifaborted() 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_synchronize() and drmaa_wait() functions will fail
         if:

      DRMAA_ERRNO_EXIT_TIMEOUT
         Time-out condition.

      DRMAA_ERRNO_INVALID_JOB
         The job specified by the does not exist.

         The drmaa_wait() will fail if:

      DRMAA_ERRNO_NO_RUSAGE
         This error code is returned by drmaa_wait() when a  job  has
         finished but no rusage and stat data could be provided.

    SEE ALSO
         drmaa_submit(3).