drmaa_jobcontrol (3) - Linux Manuals

drmaa_jobcontrol: 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 xxQS_NAMExx job job_id into the integer pointed to by remote_ps. Possible return values are listed below. See for the correspondence between them and the xxQS_NAMExx 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 For affecting system hold and system suspend states the appropriate xxQS_NAMExx interfaces must be used.

drmaa_control()

The drmaa_control() function applies control operations on xxQS_NAMExx jobs. jobid may contain either an xxQS_NAMExx jobid or `DRMAA_JOB_IDS_SESSION_ALL' to refer to all jobs submitted during the DRMAA session opened using 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 xxQS_NAMExx The DRMAA hold/release operations are equivalent to the use of xxQS_NAMExx and The DRMAA terminate operation is equivalent to the use of xxQS_NAMExx Only user hold and user suspend can be controlled via For affecting system hold and system suspend states the appropriate xxQS_NAMExx interfaces must be used.

ENVIRONMENTAL VARIABLES

xxQS_NAME_Sxx_ROOT

Specifies the location of the xxQS_NAMExx standard configuration files.

xxQS_NAME_Sxx_CELL

If set, specifies the default xxQS_NAMExx cell to be used. To address a xxQS_NAMExx cell xxQS_NAMExx uses (in the order of precedence):

The name of the cell specified in the environment variable xxQS_NAME_Sxx_CELL, if it is set.

The name of the default cell, i.e. default.

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

xxQS_NAME_Sxx_QMASTER_PORT

If set, specifies the tcp port on which 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.