Using and Administering

ll_set_request Subroutine

Purpose

The ll_set_request subroutine determines the data requested during a subsequent ll_get_objs call to query specific objects. You can filter your queries based on the query_type, object_filter, and data_filter you select.

Library

LoadLeveler API library libllapi.a

Syntax

#include "llapi.h"
 
int ll_set_request(LL_element *query_element,QueryFlags query_flags,
char **object_filter,DataFilter data_filter);

Parameters

query_element

Is a pointer to the LL_element returned by the ll_query subroutine.

query_flags

When query_type (in ll_query) is JOBS, query_flags can be the following:

QUERY_ALL: Query all jobs.
QUERY_JOBID: Query by job ID.
QUERY_STEPID: Query by step ID.
QUERY_USER: Query by user ID.
QUERY_GROUP: Query by LoadLeveler group.
QUERY_CLASS: Query by LoadLeveler class.
QUERY_HOST: Query by machine name.

When query_type (in ll_query) is MACHINES, query_flags can be the following:

QUERY_ALL: Query all machines.
QUERY_HOST: Query by machine names.

object_filter

Specifies search criteria. The value you specify for object_filter is related to the value you specify for query_flags:

If you specify QUERY_ALL, you do not need an object_filter.
If you specify QUERY_JOBID, the object_filter must contain a list of job IDs (in the form schedd_host.cluster).
If you specify QUERY_STEPID, the object_filter must contain a list of step IDs (in the form schedd_host.cluster.step).
If you specify QUERY_USER, the object_filter must contain a list of user IDs.
If you specify QUERY_CLASS, the object_filter must contain a list of LoadLeveler class names.
If you specify QUERY_GROUP, the object_filter must contain a list of LoadLeveler group names.
If you specify QUERY_HOST, the object_filter must contain a list of LoadLeveler machine names. When the query type is JOBS, the machine names must be the names of machines to which the jobs are submitted.

The last entry in the object_filter array must be NULL.

data_filter

Filters the data returned from the object you query. The value you specify for data_filter is related to the value you specify for query_type:

If you specify JOBS, data_filter can be ALL_DATA (the default), which returns the entire object, or Q_LINE, which returns the same information returned by the llq -f flag. For more information, see llq - Query Job Status.
If you specify MACHINES, data_filter can be ALL_DATA (the default), which returns the entire object, or STATUS_LINE, which returns the same information returned by the llstatus -f flag. For more information, see llstatus - Query Machine Status.

Description

query_element, query_flags, object_filter, and data_filter are the input fields for this subroutine.

You can request a combination of object filters by calling ll_set_request more than once. When you do this, the query flags you specify are or-ed together. The following are valid combinations of object filters:

QUERY_JOBID and QUERY_STEPID. The result is the union of both queries.
QUERY_HOST and QUERY_USER. The result is the intersection of both queries.
QUERY_HOST and QUERY_CLASS. The result is the intersection of both queries.
QUERY_HOST and QUERY_GROUP. The result is the intersection of both queries.

That is, to query jobs owned by certain users and on a specific machines, issue ll_set_request first with QUERY_USER and the appropriate user IDs, and then issue it again with QUERY_HOST and the appropriate host names.

For example, suppose you issue ll_set_request with a user ID list of anton and meg, and then issue it again with a host list of k10n10 and k10n11. The objects returned are all of the jobs on k10n10 and k10n11 which belong to anton or meg.

Note that if you use two consecutive calls with the same flag, the second call will replace the previous call.

Also, you should not use the QUERY_ALL flag in combination with any other flag, since QUERY_ALL will replace any existing requests.

Return Values

This subroutine returns a zero to indicate success.

Error Values

-1: You specified an invalid query_element.
-2: You specified an invalid query_flag.
-3: You specified an invalid object_filter.
-4: You specified an invalid data_filter.
-5: A system error occurred.

Related Information

Subroutines: ll_get_data, ll_query, ll_reset_request, ll_get_objs, ll_free_objs, ll_next_obj, ll_deallocate.

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]