drmaa_jobcontrol (3) Linux Manual Page
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.