Data Access API

Synopsis

use IBM::LoadLeveler;
 
$version = ll_version();
 
# Data Access API functions
 
$query = ll_query( JOBS|MACHINES|CLUSTER|WLMSTAT|MATRIX|CLASSES|RESERVATIONS|MCLUSTERS|BLUE_GENE|FAIRSHARE );
 
$return = ll_set_request( $query,QUERY_ALL|QUERY_JOBID|QUERY_STEPID|\
        QUERY_GROUP|QUERY_CLASS|QUERY_HOST|QUERY_STARTDATE|QUERY_ENDDATE|\
        QUERY_PROCID|QUERY_RESERVATION_ID|\
        QUERY_BG_JOB|QUERY_BG_PARTITION|QUERY_BG_BASE_PARTITION,\
        QUERY_TOP_DOG,\@filter,ALL_DATA|Q_LINE|STATUS_LINE );
 
$object = ll_get_objs( $query, LL_STARTD|LL_SCHEDD|LL_CM|LL_MASTER|\
        LL_STARTER|LL_HISTORY_FILE, $hostname, $number_of_objs, $error_code);
 
$return = ll_reset_request( $object );
 
$next_object = ll_next_obj ( $object );
 
$return = ll_free_objs ( $object );
 
$return = ll_deallocate ( $object );
 
$result = ll_get_data( $object, $LLAPI_Specification );

Description

A minimal example of using the Data Access API is:

use IBM::LoadLeveler;
 
# Query Job information
$query = ll_query(JOBS);
 
# Ask for all data on all jobs
$return=ll_set_request($query,QUERY_ALL,undef,ALL_DATA);
if ($return != 0 )
{
    print STDERR "ll_set_request failed Return = $return\n";
}
 
# Query the scheduler for information
# $number will contain the number of objects returned
 
$job=ll_get_objs($query,LL_CM,NULL,$number,$err);
 
while ( $job)
{
    # Get the Job submit time
    $SubmitTime=ll_get_data($job,LL_JobSubmitTime);
    $job=ll_next_obj($query);
}
# Free up space allocated by LoadLeveler to hold the job object
ll_free_objs($job);
 
# Free up space used by the Query Object
ll_deallocate($query);

The Data Access API has the following functions:

ll_query

$query = ll_query( JOBS | MACHINES | CLUSTER  | WLMSTAT   | MATRIX | CLASSES |
                       RESERVATIONS| MCLUSTERS| BLUE_GENE | FAIRSHARE);

ll_query is the first call you make to access the API it establishes the type of information you receive.

Note:

  1. CLASSES query requires version LoadLeveler 3.2+
  2. RESERVATIONS query requires LoadLeveler 3.3+
  3. BLUE_GENE query requires LoadLeveler 3.3.1+ and a Blue Gene system
  4. MCLUSTERS query requires LoadLeveler 3.3.1+ and a Multi-Cluster environment
  5. FAIRSHARE query requires LoadLeveler 3.3.2+

ll_set_request

$return=ll_set_request($query,$QueryFlags,$ObjectFilter, $DataFilter);

ll_set_request is used to determine the range of data returned by ll_get_objs.

Parameters:

Parameter Description
$query The return from ll_query
$QueryFlags The permissible Query Flags depends on the type of query being made.
$ObjectFilter Specifies the search criteria:
$DataFilter Filters the amount of data you get back from the query.
Query Flags
Flag Description
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.
QUERY_STARTDATE Query by job start dates
QUERY_ENDDATE Query by job end dates.
QUERY_PROCID Query by process id.
QUERY_RESERVATION_ID Query by reservation id.
QUERY_BG_JOB Query by Blue Gene type jobs only.
QUERY_BG_PARTITION Query defined Blue Gene partitions.
QUERY_BG_BASE_PARTITION Query Blue Gene base partitions.
QUERY_TOP_DOG Query by job steps that are top dogs.

These query flags can be used with the following query types:

Query Type Permitted Flags
BLUE_GENE QUERY_ALL QUERY_BG_BASE_PARTITION QUERY_BG_PARTITION
CLASSES QUERY_ALL QUERY_CLASS
CLUSTER QUERY_ALL
FAIRSHARE QUERY_ALL QUERY_USER QUERY_GROUP
JOBS QUERY_ALL QUERY_BG_JOB QUERY_CLASS QUERY_ENDDATE QUERY_GROUP QUERY_HOST QUERY_JOBID QUERY_RESERVATION_ID QUERY_STARTDATE QUERY_STEPID QUERY_USER QUERY_TOP_DOG
MACHINES QUERY_ALL QUERY_HOST
MATRIX QUERY_ALL QUERY_HOST
MCLUSTERS QUERY_ALL
RESERVATIONS QUERY_ALL QUERY_BG_BASE_PARTITION QUERY_GROUP QUERY_HOST QUERY_RESERVATION_ID QUERY_USER
WLMSTAT QUERY_STEPID

The search criteria are:

Query Flag Filter
QUERY_ALL undef
QUERY_JOBID Array reference of job IDs eg [“host.jobid1”, “host.jobid2”]
QUERY_STEPID Array reference of step IDs eg [“host.jobid.stepid”]
QUERY_USER Array reference of user IDs eg [“mike”, “mark”, “mary”]
QUERY_CLASS Array reference of LoadLeveler class names.
QUERY_GROUP Array reference of LoadLeveler group names.
QUERY_HOST Array reference of LoadLeveler host names.
QUERY_STARTDATE two start dates having the format MM/DD/YYYY eg [“01/14/2003”, “02/23/2003”].
QUERY_ENDDATE two end dates having the format MM/DD/YYYY eg [“01/14/2003”, “02/23/2003”].
QUERY_PROCID Array reference containing a single process id terminated by a NULL string eg [“procid”,NULL].
QUERY_RESERVATION_ID Array reference containing a list of reervation IDs.
QUERY_BG_BASE_PARTITION Array reference of base partition IDs. For all base partitions, the first entry in the list must contain the string “all”.
QUERY_BG_PARTITION Array reference of partition IDs. For all partitions, the first entry in the list must contain the string “all”.
QUERY_TOP_DOG Array reference of step IDs

NOTE:

QUERY_PROCID has been broken, some of the return fields don't return a value and it does not work at all with GANG scheduling. APAR is IY48329

The permitted values of $DataFilter are:

Value Notes
ALL_DATA All data
Q_LINE Valid only for a JOBS query, not using the history file, returns the same data as llq -f
STATUS_LINE Valid only for a MACHINES query, returns the same data as llstatus -f

ll_reset_request

$return=ll_reset_request($query);

This is used to reset the request (surprise!) associated with a query object, you use it if you want to do another L<ll_set_request> using different parameters.

ll_get_objs

$data=ll_get_objs($query,$query_daemon,$host,$number,$err);

Sends a query request to LoadLeveler

Parameters

ParameterNotes
$queryData from ll_query
$query_daemonThe LoadLeveler Daemon you want to query
$hostShould be NULL unless you are querying LL_STARTD or LL_SCHEDD and want to query a machine other than the localhost. If you are querying LL_HISTORY_FILE then this should be the name of the history file.
$numberThe number of query objects returned.
$errorIf there is an error this is it
Permitted Query Types
LL_STARTD
LL_SCHEDD
LL_CM (negotiator)
LL_MASTER
LL_STARTER
LL_HISTORY_FILE

Possible values of $error

-1 query_element not valid
-2 query_daemon not valid
-3 Cannot resolve hostname
-4 Request type for specified daemon not valid
-5 System error
-6 No valid objects meet the request
-7 Configuration error
-9 Connection to daemon failed
-10 Error processing history file (LL_HISTORY_FILE query only)
-11 History file must be specified in the hostname argument (LL_HISTORY_FILE query only)
-12 Unable to access the history file (LL_HISTORY_FILE query only)
-13 DCE identity of calling program can not be established
-14 No DCE credentials
-15 DCE credentials within 300 secs of expiration
-16 64-bit API is not supported when DCE is enabled

ll_get_data

$data=ll_get_data($element,$specification);

This call differs from the IBM documentation, the data you request is returned as the return value and not as a third parameter eg

$lav=ll_get_data($machine,LL_MachineLoadAverage);	# Returns a double
 
@msl=ll_get_data($machine,LL_MachineStepList);		# Returns an array of strings.

To know what you are getting you really need to know about the LoadLeveler Job Object Model. All of this is in the IBM LoadLeveler for AIX 5L: Using and Administering book and html. Sorry for not including it here, but there is an awful lot of it.

enum types

Returns from some query types may be, in C terms, enumerated types. In perl these all return as SCALAR Integers. Return values are shown below:

  • LL_AdapterReqUsage
  SHARED, NOT_SHARED, SLICE_NOT_SHARED
  • LL_StepHoldType
  NO_HOLD, HOLDTYPE_USER, HOLDTYPE_SYSTEM, HOLDTYPE_USERSYS
  • LL_StepNodeUsage
  SHARED, NOT_SHARED, SLICE_NOT_SHARED
  • LL_StepState
  STATE_IDLE, STATE_PENDING, STATE_STARTING, STATE_RUNNING,
  STATE_COMPLETE_PENDING, STATE_REJECT_PENDING, STATE_REMOVE_PENDING,
  STATE_VACATE_PENDING, STATE_COMPLETED, STATE_REJECTED, STATE_REMOVED,
  STATE_VACATED, STATE_CANCELED, STATE_NOTRUN, STATE_TERMINATED,
  STATE_UNEXPANDED, STATE_SUBMISSION_ERR, STATE_HOLD, STATE_DEFERRED,
  STATE_NOTQUEUED, STATE_PREEMPTED, STATE_PREEMPT_PENDING, 
  STATE_RESUME_PENDING

ll_next_obj

$job=ll_next_obj($query);

This returns the next object from the query object.

ll_free_objs

$return=ll_free_objs($query);

This frees up the the space taken by the ll_get_objs routine for the LoadLeveler Data. Since there is probably an awful lot of this this is a very important call.

ll_deallocate

$return=ll_deallocate($query);

Frees the query object itself, this is the last LoadLeveler action.

Integer Arrays

Some of the returns are integer arrays, In this module they will return lists so you do not need to worry about how many elements they contain. The parameters as I understand them are:

Query List size
LL_MachinePoolList LL_MachinePoolListSize
LL_AdapterWindowList LL_AdapterTotalWindowCount
LL_BgBPLocation 3
LL_BgMachineBPSize 3
LL_BgMachineSize 3
LL_StepBgShapeAllocated 3
LL_StepBgShapeRequested 3
LL_BgPartitionShape 3
LL_ReservationBgShape 3
LL_FairShareEntryTypes LL_FairShareNumberOfEntries
LL_FairShareAllocatedShares LL_FairShareNumberOfEntries
LL_FairShareUsedShares LL_FairShareNumberOfEntries
LL_FairShareUsedBgShares LL_FairShareNumberOfEntries
LL_MachineCPUList LL_MachineCPUs
LL_MCMCPUList LL_MCMCPUs
LL_MachineUsedCPUList LL_MachineUsedCPUs
 
data_access_api.txt · Last modified: 2008/07/21 17:41 by mike
 
Recent changes RSS feed Creative Commons License Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki