drmaa_jobcontrol(3)

💖 drmaa_jobcontrol(3) 💖

okay bestie, welcome to the Grid Engine DRMAA corner of the manual — this is drmaa_jobcontrol, page 3 of the Grid Engine DRMAA section, and it's literally the page where you learn to monitor and control your jobs. group chat energy, but make it Unix. 🦋

---

✨ NAME ✨

drmaa_job_ps, drmaa_control — monitor and control jobs, bestie. that's the whole job description. 💅

---

🌸 SYNOPSIS 🌸

#include "drmaa.h"

int drmaa_job_ps(
       const char *job_id,
       int *remote_ps,
       char *error_diagnosis,
       size_t error_diag_len
);

int drmaa_control(
       const char *jobid,
       int action,
       char *error_diagnosis,
       size_t error_diag_len
);

---

💜 DESCRIPTION 💜

so drmaa_job_ps() is the vibe-check function. it takes your Grid Engine job job_id and drops its status into the integer that remote_ps points at. the possible return values are right here, no cap:

• DRMAA_PS_UNDETERMINED — job status cannot be determined (mystery era 🙈)
• 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 (main character energy 🔥)
• DRMAA_PS_SYSTEM_SUSPENDED — job is system suspended
• DRMAA_PS_USER_SUSPENDED — job is user suspended
• DRMAA_PS_DONE — job finished normally (ate, no crumbs ✨)
• DRMAA_PS_FAILED — job finished, but failed (it's giving tragedy 😭)

want the receipts on how those line up with actual Grid Engine statuses? check sge_status(5). iykyk.

jobs' user hold and user suspend states can be controlled via drmaa_control(3). but for touching system hold and system suspend states? nope, not here — you gotta use the appropriate Grid Engine interfaces for that. 💅

🎀 drmaa_control() 🎀

drmaa_control() applies control operations on Grid Engine jobs. the jobid can be either a Grid Engine jobid, or DRMAA_JOB_IDS_SESSION_ALL to refer to all jobs submitted during the DRMAA session opened using drmaa_init(3). the way that's a whole-session vibe. 👑

legal values for action and their meanings:

• 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 using the -sj jobid and -usj jobid options with Grid Engine qmod(1). the DRMAA hold/release operations are equivalent to using Grid Engine qhold(1) and qrls(1). the DRMAA terminate operation is equivalent to using Grid Engine qdel(1). and only user hold and user suspend can be controlled via drmaa_control(3) — for affecting system hold and system suspend states, the appropriate Grid Engine interfaces must be used. that part is not a suggestion, bestie, it's a boundary. 🫶

---

🌈 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 precedence):
  1. the name of the cell specified in the environment variable SGE_CELL, if it is set.
  2. 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 communication requests. most installations will use a services map entry instead to define that port.

---

⭐ RETURN VALUES ⭐

upon successful completion, drmaa_job_ps() and drmaa_control() return DRMAA_ERRNO_SUCCESS. any other value means an error happened, bestie. in that case, up to error_diag_len characters of error-related diagnosis information get dropped into the buffer error_diagnosis. 🩹

---

💀 ERRORS 💀

drmaa_job_ps() and drmaa_control() may fail with:

• DRMAA_ERRNO_INTERNAL_ERROR — unexpected or internal DRMAA error, like system call failure, etc. (the classic "idk what happened either" moment 😭)
• DRMAA_ERRNO_DRM_COMMUNICATION_FAILURE — could not contact DRM system for this request.
• DRMAA_ERRNO_AUTH_FAILURE — the specified request was not processed successfully due to authorization failure. (you're not on the list, bestie 🙈)
• 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.
• DRMAA_ERRNO_INVALID_JOB — the specified job does not exist. (ghosted by your own job 💀)

and drmaa_control() may fail with these extra ones:

• DRMAA_ERRNO_RESUME_INCONSISTENT_STATE — the job is not suspended. the resume request will not be processed.
• DRMAA_ERRNO_SUSPEND_INCONSISTENT_STATE — the job is not running and thus cannot be suspended.
• DRMAA_ERRNO_HOLD_INCONSISTENT_STATE — the job cannot be moved to a hold state.
• DRMAA_ERRNO_RELEASE_INCONSISTENT_STATE — the job is not in a hold state.

ngl, "inconsistent state" errors are just the DRM system saying "bestie, that's not where the job is at rn." read the state, then act. periodt. 💅

---

👑 SEE ALSO 👑

drmaa_submit(3), drmaa_wait(3), sge_status(5).

---

and that's the page, bestie!! 🎀 this one came from SGE 8.1.3pre, dated $Date: 2009-06-17 09:50:13 $ — yes it's old, yes it still slays, go monitor those jobs. 💖✨🦋