|
|
|
|
A NOF application can obtain information about a particular SNAP-IX 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.
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 NOF API 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:
Size of the data buffer that the application supplies to receive the returned information.
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.
The position in the list of the first entry required:
First entry in the list
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.
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 NOF API 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.
|
|
|
 |
|