IBM::LoadLeveler - Data Access API
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 );
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
ll_set_request
ll_reset_request
ll_get_objs
ll_get_data
ll_next_obj
ll_free_objs
ll_deallocate
$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:
CLASSES query is only available in version LoadLeveler 3.2 and above.
RESERVATIONS requires LoadLeveler 3.3+
MCLUSTERS & BLUE_GENE require LoadLeveler 3.3.1+
FAIRSHARE requires LoadLeveler 3.3.2+
$return=ll_set_request($query,$QueryFlags,$ObjectFilter, $DataFilter);
ll_set_request is used to determine the range of data returned by ll_get_objs.
The return from ll_query
The permissable Query Flags depends on the type of query being made. The flags are:
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 bluegene type jobs only
QUERY_BG_PARTITION : Query defined Blue Gene partitions
QUERY_BG_BASE_PARTITIONS : Query Blue Gene base partitions
QUERY_TOP_DOG : Query by Job steps that are top dogs
They 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
Specifies the search criteria:
Query Flag Filter Description --------------------------------------- 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 or QUERY_ENDDATE two start dates or 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 base partitions, the first entry in the list must contain the string "all" QUERY_TOP_DOG Array reference of job step
QUERY_PROCID is currently broken, some of the return fields don't return a value and it does not work at all with GANG scheduling. APAR is IY48329
Filters the amount of data you get back from the query. Permitted values are:
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
$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 ll_set_request using different parameters.
$data=ll_get_objs($query,$query_daemon,$host,$number,$err);
Sends a query request to LoadLeveler
Data from ll_query
The LoadLeveler Daemon you want to query, permitted values are:
LL_STARTD
LL_SCHEDD
LL_CM (negotiator)
LL_MASTER
LL_STARTER
LL_HISTORY_FILE
Should 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.
The number of query objects returned.
If there is an error this is it. Possible values are:
$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.
-head3 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:
SHARED, NOT_SHARED, SLICE_NOT_SHARED
NO_HOLD, HOLDTYPE_USER, HOLDTYPE_SYSTEM, HOLDTYPE_USERSYS
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
$job=ll_next_obj($query);
This returns the next object from the query object.
$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.
$return=ll_deallocate($query);
Frees the query object itself, this is the last LoadLeveler action.
These two requests are supposed to return integer arrays. In this module they will return lists.
LL_MachinePoolList
This will return a list with LL_MachinePoolListSize elements in it.
LL_AdapterWindowList
This will return a list with LL_AdapterTotalWindowCount elements in it.
Blue Gene
The Blue Gene arrays are all 3 elements in size.
Mike Hawkins <mike@pink-pit.com>
LoadLeveler perl. IBM LoadLeveler for AIX 5L: Using and Administering
To install IBM::LoadLeveler, copy and paste the appropriate command in to your terminal.
cpanm
cpanm IBM::LoadLeveler
CPAN shell
perl -MCPAN -e shell install IBM::LoadLeveler
For more information on module installation, please visit the detailed CPAN module installation guide.