drmaa_jobcontrol(3)            Grid Engine DRMAA           drmaa_jobcontrol(3)



NNAAMMEE
       drmaa_job_ps, drmaa_control, - Monitor and control jobs


SSYYNNOOPPSSIISS
       ##iinncclluuddee ""ddrrmmaaaa..hh""

       iinntt ddrrmmaaaa__jjoobb__ppss((
              ccoonnsstt cchhaarr **jjoobb__iidd,,
              iinntt **rreemmoottee__ppss,,
              cchhaarr **eerrrroorr__ddiiaaggnnoossiiss,,
              ssiizzee__tt eerrrroorr__ddiiaagg__lleenn
       ));;

       iinntt ddrrmmaaaa__ccoonnttrrooll((
              ccoonnsstt cchhaarr **jjoobbiidd,,
              iinntt aaccttiioonn,,
              cchhaarr **eerrrroorr__ddiiaaggnnoossiiss,,
              ssiizzee__tt eerrrroorr__ddiiaagg__lleenn
       ));;


DDEESSCCRRIIPPTTIIOONN
       The  drmaa_job_ps()  function returns the status of the Grid Engine job
       _j_o_b___i_d into the integer pointed to by _r_e_m_o_t_e___p_s. Possible return values
       are

              DRMAA_PS_UNDETERMINED        job status cannot be determined
              DRMAA_PS_QUEUED_ACTIVE       job is queued and active
              DRMAA_PS_SYSTEM_ON_HOLD      job is queued and in system hold
              DRMAA_PS_USER_ON_HOLD        job is queued and in user hold
              DRMAA_PS_USER_SYSTEM_ON_HOLD job is queued and in user and system hold
              DRMAA_PS_RUNNING             job is running
              DRMAA_PS_SYSTEM_SUSPENDED    job is system suspended
              DRMAA_PS_USER_SUSPENDED      job is user suspended
              DRMAA_PS_DONE                job finished normally
              DRMAA_PS_FAILED              job finished, but failed

       Jobs'  user  hold  and  user  suspend  states  can  be  controlled  via
       _d_r_m_a_a___c_o_n_t_r_o_l(3).  For affecting system hold and system suspend  states
       the appropriate Grid Engine interfaces must be used.

   ddrrmmaaaa__ccoonnttrrooll(())
       The  drmaa_control() function applies control operations on Grid Engine
       jobs.   _j_o_b_i_d  may   contain   either   an   Grid   Engine   jobid   or
       `DRMAA_JOB_IDS_SESSION_ALL'  to  refer to all jobs submitted during the
       DRMAA session opened using _d_r_m_a_a___i_n_i_t(3).  Legal values for _a_c_t_i_o_n  and
       their meanings are:

              DRMAA_CONTROL_SUSPEND        suspend the job
              DRMAA_CONTROL_RESUME         resume the job,
              DRMAA_CONTROL_HOLD           put the job on-hold
              DRMAA_CONTROL_RELEASE        release the hold on the job
              DRMAA_CONTROL_TERMINATE      kill the job

       The  DRMAA  suspend/resume  operations are equivalent to the use of `-s
       <jobid>' and `-us <jobid>' options with Grid Engine _q_m_o_d(1).  The DRMAA
       hold/release  operations  are  equivalent  to  the  use  of Grid Engine
       _q_h_o_l_d(1) and _q_r_l_s(1).  The DRMAA terminate operation is  equivalent  to
       the use of Grid Engine _q_d_e_l(1).  Only user hold and user suspend can be
       controlled via _d_r_m_a_a___c_o_n_t_r_o_l(3).  For affecting system hold and  system
       suspend states the appropriate Grid Engine interfaces must be used.


EENNVVIIRROONNMMEENNTTAALL VVAARRIIAABBLLEESS
       GGEE__RROOOOTT        Specifies  the location of the Grid Engine standard con-
                      figuration files.

       GGEE__CCEELLLL        If 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. ddeeffaauulltt.


       GGEE__DDEEBBUUGG__LLEEVVEELL If 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.

       GGEE__QQMMAASSTTEERR__PPOORRTT
                      If set, specifies the tcp port on which _g_e___q_m_a_s_t_e_r(8) is
                      expected to listen  for  communication  requests.   Most
                      installations  will  use a services map entry instead to
                      define that port.

RREETTUURRNN VVAALLUUEESS
       Upon successful completion, drmaa_job_ps(), and drmaa_control()  return
       DRMAA_ERRNO_SUCCESS.   Other   values   indicate   an   error.   Up  to
       _e_r_r_o_r___d_i_a_g___l_e_n characters of error  related  diagnosis  information  is
       then provided in the buffer, _e_r_r_o_r___d_i_a_g_n_o_s_i_s.


EERRRROORRSS
       The drmaa_job_ps(), and drmaa_control() will fail if:

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

   DDRRMMAAAA__EERRRRNNOO__DDRRMM__CCOOMMMMUUNNIICCAATTIIOONN__FFAAIILLUURREE
       Could not contact DRM system for this request.

   DDRRMMAAAA__EERRRRNNOO__AAUUTTHH__FFAAIILLUURREE
       The  specified request was not processed successfully due to authoriza-
       tion failure.

   DDRRMMAAAA__EERRRRNNOO__IINNVVAALLIIDD__AARRGGUUMMEENNTT
       The input value for an argument is invalid.

   DDRRMMAAAA__EERRRRNNOO__NNOO__AACCTTIIVVEE__SSEESSSSIIOONN
       Failed because there is no active session.

   DDRRMMAAAA__EERRRRNNOO__NNOO__MMEEMMOORRYY
       Failed allocating memory.

   DDRRMMAAAA__EERRRRNNOO__IINNVVAALLIIDD__JJOOBB
       The specified job does not exist.

       The drmaa_control() will fail if:

   DDRRMMAAAA__EERRRRNNOO__RREESSUUMMEE__IINNCCOONNSSIISSTTEENNTT__SSTTAATTEE
       The job is not suspended. The resume request will not be processed.

   DDRRMMAAAA__EERRRRNNOO__SSUUSSPPEENNDD__IINNCCOONNSSIISSTTEENNTT__SSTTAATTEE
       The job is not running and thus cannot be suspended.

   DDRRMMAAAA__EERRRRNNOO__HHOOLLDD__IINNCCOONNSSIISSTTEENNTT__SSTTAATTEE
       The job cannot be moved to a hold state.

   DDRRMMAAAA__EERRRRNNOO__RREELLEEAASSEE__IINNCCOONNSSIISSTTEENNTT__SSTTAATTEE
       The job is not in a hold state.


SSEEEE AALLSSOO
       _d_r_m_a_a___s_u_b_m_i_t(3)and _d_r_m_a_a___w_a_i_t(3).



GE 6.2u2                 $Date: 2004/11/12 15:40:05 $      drmaa_jobcontrol(3)
