---
name: "drmaa_control"
section: "3"
platform: "linux"
package: "gridengine-drmaa-dev"
version: "6.2u5-7.1"
release: "Debian 7 (Wheezy)"
platforms: ["linux"]
url: "https://new.carta.tech/drmaa_jobcontrol"
---

# drmaa\_control(3)

Monitor and control jobs

Part of [drmaa\_jobcontrol(3)](/drmaa_jobcontrol/3.md).

## 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 Sun Grid Engine job** *job\_id*  **into the integer pointed to by** *remote\_ps***. 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**  [*drmaa\_control*(3)](/drmaa_control/3.md). For affecting system hold and system suspend states the appropriate Sun Grid Engine interfaces must be used.

### drmaa\_control()

The drmaa\_control() function applies control operations on Sun Grid Engine jobs. *jobid* may contain either an Sun 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   Sun Grid Engine [*qmod*(1)](/qmod/1.md). The DRMAA hold/release operations are equivalent to the use of  Sun Grid Engine [*qhold*(1)](/qhold/1.md) and  [*qrls*(1)](/qrls/1.md). The DRMAA terminate operation is equivalent to the use of  Sun 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 Sun Grid Engine interfaces must be used.

## 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)](/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() 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 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() will fail if:

### 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)and [*drmaa\_wait*(3)](/drmaa_wait/3.md).