---
name: "drmaa_jobcontrol"
section: "3"
platform: "linux"
package: "gridengine-drmaa-dev"
version: "8.1.9+dfsg-13.1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/drmaa_jobcontrol"
---

# drmaa\_jobcontrol(3)

Monitor and control jobs

## NAME

drmaa\_job\_ps, drmaa\_control, - Monitor and control jobs

## 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

**The drmaa\_job\_ps() function returns the status of the Grid Engine job** *job\_id*  **into the integer pointed to by** *remote\_ps***. Possible return values are** **listed below.  See** [*sge\_status*(5)](/sge_status/5.md) for the correspondence between them and the Grid Engine status.

| | |
| --- | --- |
| 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  [*drmaa\_control*(3)](/drmaa_control/3.md). For affecting system hold and system suspend states the appropriate Grid Engine interfaces must be used.

### drmaa\_control()

The drmaa\_control() function applies control operations on Grid Engine jobs. *jobid* 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 [*drmaa\_init*(3)](/drmaa_init/3.md). Legal values for *action* 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  **-sj** *jobid* and **-usj** *jobid* options with Grid Engine [*qmod*(1)](/qmod/1.md). The DRMAA hold/release operations are equivalent to the use of  Grid Engine [*qhold*(1)](/qhold/1.md) and  [*qrls*(1)](/qrls/1.md). The DRMAA terminate operation is equivalent to the use of  Grid Engine [*qdel*(1)](/qdel/1.md). Only user hold and user suspend can be controlled via  [*drmaa\_control*(3)](/drmaa_control/3.md). For affecting system hold and system suspend states the appropriate Grid Engine interfaces must be used.

## 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):

  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)](/sge_qmaster/8.md) 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. 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\_job\_ps() and drmaa\_control() functions may fail with:

- **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 was 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.

- **DRMAA\_ERRNO\_INVALID\_JOB**

  The specified job does not exist.

The drmaa\_control() function may fail with:

- **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.

## SEE ALSO

[*drmaa\_submit*(3)](/drmaa_submit/3.md), [*drmaa\_wait*(3)](/drmaa_wait/3.md), [*sge\_status*(5)](/sge_status/5.md).