A NOF application can obtain information about a particular
SNAplus2 resource by issuing a QUERY_* verb for the appropriate
resource type. For example, it can obtain information about the
configuration of an LS by issuing QUERY_LS. These verbs can either
return information about a specific resource (for example, the configuration
of a particular LS) or about many resources of the same type (for
example, a summary of all configured LSs), depending on the options
used. In addition, some QUERY_* verbs have the option of returning
either summary or detailed information about the specified resources.
This section explains how to use these options.
Obtaining
Information about a Single Resource or Multiple Resources |
 |
You can think of the information returned by QUERY_* verbs
as being stored in the form of a list, ordered according to the
name of the resource. For example, the information returned by QUERY_LS
is in order of LS name. The normal order of the list (for compatibility
with SNMP list ordering) is as follows:
By name length (shortest name first)
By ASCII lexicographical ordering for names of the
same length
Where the list ordering differs from this (for example, where
the list is ordered by a numeric value), this difference is indicated
in the individual verb descriptions in Chapter 4 “NOF
API Verbs (QUERY Verbs)”
This means that an application can obtain information about
multiple resources by requesting the complete list or a specified
part of it. The following parameters on a QUERY_* verb determine
which entries from the list are returned:
- buf_size
Size of the data buffer that the application supplies
to receive the returned information.
- num_entries
Maximum number of resources for which information should
be returned. The application can specify 1 to request
a specific entry rather than a range, a number greater than 1 to
request a range, or 0 (zero) to request as many entries as possible.
- list_options
The position in the list of the first entry required:
Entries starting from a specific named entry
Entries starting from the next entry after a specific named
entry. (The name specified gives the starting position according
to the list ordering and need not exist in the list; for example,
if the list contains entries NODEA, NODEB, NODED, NODEF,
and the application requests entries starting from the first entry
after NODEC, the first entry returned is NODED.)
In addition, if the list_options parameter does not request starting from the first
entry, the name of a specific entry in the list is used to indicate
the starting position for the required entries.
The number of entries returned is the smallest of the following
values:
The num_entries parameter, if this is nonzero
The maximum number of entries that the supplied
data buffer can hold
The number of entries between the specified starting
position and the end of the list
In addition, the verb returns information about the total
number of entries available and the size of the buffer that would
be required to return all the entries at once. If the application
has not yet received all the information it requires, it can then
issue further verbs to obtain the remaining information.
These options enable the application to manage the information
it receives, as follows:
To obtain a specific entry, it sets
the index value to the name of that entry, list_options to indicate “start from the named entry”, buf_size to at least the size of a single entry, and num_entries to 1.
To obtain a complete list a few entries at a time,
it first sets list_options to indicate “start from beginning of list”,
and uses either buf_size or num_entries to limit the amount of information returned. If the
returned values indicate that there is more information available,
it then issues another verb with list_options indicating “start from the following entry” and
sets the index value to the name of the last entry received; this
second verb then returns the next section of the list. The application
repeats this process until it has received all the required entries.
Obtaining
Summary or Detailed Information |
|
Some QUERY_* verbs provide the option of returning either
summary or detailed information about the specified resources. For
example, QUERY_LOCAL_LU can return just the LU name and LU alias (summary
information) or can also return additional information such as the
LU address and session limit (detailed information). The description of
each QUERY_* verb in Chapter 4 “NOF
API Verbs (QUERY Verbs)” indicates
whether the verb includes the option of returning summary or detailed
information.
For the verbs that provide this option, the list_options parameter is used to indicate whether summary or detailed
information is required, as well as the starting position within
the list. To specify these options, you combine two values using
a logical OR operation (one value to specify the
starting position in the list and one value to specify whether summary
or detailed information is required) and set the list_options parameter to the combination of these two values. For
verbs that do not provide this option, you simply set list_options to a single value to indicate the starting position
in the list.
Printable version
