SECTION 6 Job Status and Control Functions

Functions
int	drmaa_control (const char *jobid, int action, char *error_diagnosis, size_t error_diag_len)
int	drmaa_job_ps (const char *job_id, int *remote_ps, char *error_diagnosis, size_t error_diag_len)

---

Function Documentation

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

This function allows the job specified by jobid to be controlled according to a given action. Possible action to be performed over a given job are:

• DRMAA_CONTROL_SUSPEND A job will be stopped, and restart files tranferred back to the client. These files if provided by the running job will be used on RESUME to re-start execution.

• DRMAA_CONTROL_RESUME A previously stopped job will be resumed. If re-start files are provided the job will used them to re-start execution, from the last checkpointing context.

• DRMAA_CONTROL_TERMINATE The job will be killed, it execution can be synchronized through the drmaa_wait and drmaa_synchronize function calls. However, job rusage information will not be available.

• DRMAA_CONTROL_HOLD The job will be held, it execution will not start until it is released. Only jobs in the QUEUED_ACTIVE state can be held.

• DRMAA_CONTROL_RELEASE The job will be released and scheduled, only jobs in the USER_ON_HOLD state can be released.

Parameters:

	jobid	String with the job unique identification as provided by the GridWay system. The jobid SHOULD be obtained from a drmaa_run_job() or drmaa_run_bulk_jobs() function calls.
	action	The action to be performed over the job whose value may be one of the following: DRMAA_CONTROL_SUSPEND, DRMAA_CONTROL_RESUME, DRMAA_CONTROL_TERMINATE, DRMAA_CONTROL_HOLD or DRMAA_CONTROL_RELEASE.
	error_diagnosis	string of characters with error related diagnosis information. The error diagnosis buffer will be filled in case of error. If the size of error_diagnosis buffer passed is smaller than the error message the resultant string will be truncated.
	error_diag_len	size of the error_diagnosis buffer. DRMAA_ERROR_STRING_BUFFER can be used for error_diag_len when appropiate.

Returns:

• DRMAA_ERRNO_SUCCESS on success.
• DRMAA_ERRNO_INTERNAL_ERROR if action is not defined or supported.
• DRMAA_ERRNO_DRM_COMMUNICATION_FAILURE could not contact GridWay
• DRMAA_ERRNO_NO_ACTIVE_SESSION if drmaa_init() function has not been previously called.
• DRMAA_ERRNO_INVALID_ARGUMENT undefined control operation
• DRMAA_ERRNO_INVALID_JOB the job does not exist or has already been reaped
• DRMAA_ERRNO_HOLD_INCONSISTENT_STATE the HOLD action could not be performed
• DRMAA_ERRNO_RELEASE_INCONSISTENT_STATE the RELEASE action could not be performed
• DRMAA_ERRNO_RESUME_INCONSISTENT_STATE the RESUME action could not be performed
• DRMAA_ERRNO_SUSPEND_INCONSISTENT_STATE the SUSPEND action could not be performed

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

Obtains the status of a given job.

Parameters:

	*job_id	String with the job unique identification as provided by the GridWay system. The jobid SHOULD be obtained from a drmaa_run_job() or drmaa_run_bulk_jobs() function calls.
	*remote_ps	The actual state of the job. remote_ps can be one of the following: DRMAA_PS_UNDETERMINED: An UNDETERMINED state can either obtained due to a communication error with the GridWay daemon, or because the job has not been initialized yet.

• DRMAA_PS_QUEUED_ACTIVE The job has been successfully submitted and it is pending to be scheduled.

• DRMAA_PS_RUNNING The job has been successfully submitted to a remote host. Please note that once submitted, the job can be in any of the execution stages, namely: prolog (file stage-in), wrapper (execution), epilog (file stage-out) or migrating (to another host).

• DRMAA_PS_USER_ON_HOLD The job has been held by the user

• DRMAA_PS_DONE Job has been completely executed and output files are available at the client. drmaa_wait() and drmaa_synchronize() calls on the job will return immediately. Also rusage information is available.

• DRMAA_PS_DONE Job has been completely executed and output files are available at the client. drmaa_wait() and drmaa_synchronize() calls on the job will return immediately. Also rusage information is available.

• DRMAA_PS_FAILED Job execution has failed, and the "on_failure" policy is to hold it on FAILED state.

The GridWay DRMAA implementation does not define the following actions: DRMAA_PS_SYSTEM_ON_HOLD, DRMAA_PS_USER_SYSTEM_ON_HOLD, DRMAA_PS_SYSTEM_SUSPENDED and DRMAA_PS_USER_SYSTEM_SUSPENDED.

Parameters:

	error_diagnosis	string of characters with error related diagnosis information. The error diagnosis buffer will be filled in case of error. If the size of error_diagnosis buffer passed is smaller than the error message the resultant string will be truncated.
	error_diag_len	size of the error_diagnosis buffer. DRMAA_ERROR_STRING_BUFFER can be used for error_diag_len when appropiate.

Returns:

• DRMAA_ERRNO_SUCCESS on success.
• DRMAA_ERRNO_INTERNAL_ERROR if action is not defined or supported.
• DRMAA_ERRNO_DRM_COMMUNICATION_FAILURE could not contact GridWay (remote_ps will be DRMAA_PS_UNDETERMINED)
• DRMAA_ERRNO_INVALID_JOB the job does not exist or has already been reaped
• DRMAA_ERRNO_NO_ACTIVE_SESSION if drmaa_init() function has not been previously called.