Using and Administering

ll_terminate_job Subroutine

Purpose

This subroutine tells the negotiator to cancel the specified job step.

Library

LoadLeveler API library libllapi.a

Syntax

  #include "llapi.h"
 
  int ll_terminate_job(LL_terminate_job_info *ptr);

Parameters

ptr

Specifies the pointer to the LL_terminate_info structure that was allocated by the caller. The LL_terminate_job_info members are:

int version_num

Represents the version number of the LL_terminate_job_info structure. Should be set to LL_PROC_VERSION

LL_STEP_ID StepId

Represents the step ID of the job step to be terminated.

char *msg

A pointer to a null terminated array of characters. If this pointer is null or points to a null string, a default message is used. This message will be available through ll_get_data to tell the process why a program was terminated.

Description

You do not need to disable the default LoadLeveler scheduler in order to use this subroutine.

Only processes having the LoadLeveler administrator user ID can invoke this subroutine.

An external scheduler uses this subroutine in conjunction with the ll_get_job subroutine (of the job control API) and ll_start_jobs subroutine (of the query API). The external scheduler must use this subroutine to return errors from ll_start_job to interactive parallel jobs.

Return Values

This subroutine returns a value of zero when successful, to indicate the terminate job request was accepted by the negotiator. However, a return code of zero does not necessarily imply the negotiator cancelled the job. Use the llq command to verify the job was cancelled. Otherwise, this subroutine returns an integer value defined in the llapi.h file.

Error Values

-1

There is an error in the input parameter.

-4

An error occurred reading parameters from the administration or the configuration file.

-6

A data transmission failure occurred.

-7

The subroutine cannot authorize the action because you are not a LoadLeveler administrator or you are not the user who submitted the job.

-8

The job object version number is incorrect.

Examples

Makefiles and examples which use this subroutine are located in the samples/llsch subdirectory of the release directory. The examples include the executable sch_api, which invokes the query API and the job control API to terminate the first job reported by the ll_get_jobs subroutine. You should submit at least two jobs prior to running the sample. To compile sch_api, copy the sample to a writeable directory and update the RELEASE_DIR field to represent the current LoadLeveler release directory.

Related Information

Subroutines: ll_get_jobs, ll_start_job, ll_get_nodes.