HP Caliper Advisor Rule Writer Guide

the second matching dataset is returned, and so on. If there are not abs(nth) matching
datasets, then the None value is returned. Note that for all accessor functions, the base
version is identical in functionality to the nth version with a –1 final argument.
The primary argument list to an accessor function is the metric list (metric_list) to
be retrieved. The primary argument list represents one or more actual arguments in
any order.
The first argument to get_histogram() and get_histogram_nth() and the final
argument to the nth accessor functions have special meaning and are not part of the
primary argument list.
Every metric value returned has a specific type: integer, float, boolean, string, tuple,
and so forth.
There are two possible return values from an accessor function: a tuple containing all
of the metric values or the Python None value. The tuple is the same size as the primary
argument list, and the metric values are returned in the same order that they have in
the primary argument list.
Every accessor function searches through the analysis object’s ordered list of datasets
looking for a single dataset that contains all of the requested metrics. If it is successful,
then the matched set of metric values is retrieved from that dataset. If no single dataset
can fulfill the request, then None is returned. This is an all-or-nothing operation.
An accessor function always returns a value and never raises an exception. Any internal
processing problem results in the None value being returned.
The None value is also returned if a metric unknown to an accessor function is requested.
This processing is necessary for future compatibility. If a rule that requests a metric
that only a newer version of the Advisor provides is used with an older version of the
Advisor, it will work correctly. That is, the older Advisor’s accessor function will not
recognize the (new) metric and will return the None value. Rules must be written to
deal with None values because they can also occur for a known metric that has not
been measured.
Distinctions Between Datasets
For all of the accessor functions it is vital to understand the difference between:
get_xxx(metric1, metric2)
and:
get_xxx(metric1)
get_xxx(metric2)
The first example returns a matched set of metric1 and metric2 values from the
same dataset (measurement run). The second example returns values for metric1 and
metric2, but there is no guarantee that they are from the same dataset. It is possible
that the first example could fail while the second example succeeds if metric1 and
metric2 were only measured by different HP Caliper measurement runs.
34 How the HP Caliper Advisor Works