Data Access API

IBM::LoadLeveler - 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

• ll_set_request

• ll_reset_request

• ll_get_objs

• ll_get_data

• ll_next_obj

• ll_free_objs

• ll_deallocate

• 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: 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+

• 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

  1 $query

  The return from ll_query

  2 $QueryFlags

  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

  3 $ObjectFilter

  Specifies the search criteria:

          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 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 steps
  =over 4

  NOTE:

  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

• 4 $DataFilter

  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

• 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 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

  1 $query

  Data from ll_query

  2 $query_daemon

  The LoadLeveler Daemon you want to query, permitted values are:

  • LL_STARTD

  • LL_SCHEDD

  • LL_CM (negotiator)

  • LL_MASTER

  • LL_STARTER

  • LL_HISTORY_FILE

  3 $host

  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.

  4 $number

  The number of query objects returned.

  5 $error

  If there is an error this is it. Possible values are:

  -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.

LL_MachinePoolList & LL_AdapterWindowList

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.

AUTHOR

Mike Hawkins <mike@pink-pit.com>

SEE ALSO

LoadLeveler perl. IBM LoadLeveler for AIX 5L: Using and Administering