drmaa_jobcontrol(3)            Grid Engine DRMAA           drmaa_jobcontrol(3)



[1mNAME[0m
       drmaa_job_ps, drmaa_control, - Monitor and control jobs


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

       [1mint drmaa_job_ps([0m
              [1mconst char *job_id,[0m
              [1mint *remote_ps,[0m
              [1mchar *error_diagnosis,[0m
              [1msize_t error_diag_len[0m
       [1m);[0m

       [1mint drmaa_control([0m
              [1mconst char *jobid,[0m
              [1mint action,[0m
              [1mchar *error_diagnosis,[0m
              [1msize_t error_diag_len[0m
       [1m);[0m


[1mDESCRIPTION[0m
       The  drmaa_job_ps()  function returns the status of the Grid Engine job
       [4mjob_id[24m into the integer pointed to by [4mremote_ps[24m. 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
       [4mdrmaa_control[24m(3).  For affecting system hold and system suspend  states
       the appropriate Grid Engine interfaces must be used.

   [1mdrmaa_control()[0m
       The  drmaa_control() function applies control operations on Grid Engine
       jobs.   [4mjobid[24m  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 [4mdrmaa_init[24m(3).  Legal values for [4maction[24m  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 [4mqmod[24m(1).  The DRMAA
       hold/release  operations  are  equivalent  to  the  use  of Grid Engine
       [4mqhold[24m(1) and [4mqrls[24m(1).  The DRMAA terminate operation is  equivalent  to
       the use of Grid Engine [4mqdel[24m(1).  Only user hold and user suspend can be
       controlled via [4mdrmaa_control[24m(3).  For affecting system hold and  system
       suspend states the appropriate Grid Engine interfaces must be used.


[1mENVIRONMENTAL VARIABLES[0m
       [1mSGE_ROOT       [22mSpecifies  the location of the Grid Engine standard con-
                      figuration files.

       [1mSGE_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 SGE_CELL, if it is set.

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


       [1mSGE_DEBUG_LEVEL[0m
                      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.

       [1mSGE_QMASTER_PORT[0m
                      If  set,  specifies the tcp port on which [4msge_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_job_ps(), and drmaa_control()  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_job_ps(), and drmaa_control() 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 was 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.

   [1mDRMAA_ERRNO_INVALID_JOB[0m
       The specified job does not exist.

       The drmaa_control() will fail if:

   [1mDRMAA_ERRNO_RESUME_INCONSISTENT_STATE[0m
       The job is not suspended. The resume request will not be processed.

   [1mDRMAA_ERRNO_SUSPEND_INCONSISTENT_STATE[0m
       The job is not running and thus cannot be suspended.

   [1mDRMAA_ERRNO_HOLD_INCONSISTENT_STATE[0m
       The job cannot be moved to a hold state.

   [1mDRMAA_ERRNO_RELEASE_INCONSISTENT_STATE[0m
       The job is not in a hold state.


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




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