HP-UX SNAplus2 R7 NOF Programmer's Guide

Writing NOF Applications

List Options For QUERY_* Verbs

2.7 List Options For QUERY_* Verbs

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 conﬁguration of an LS by issuing

QUERY_LS. These verbs can either return information about a speciﬁc resource (for example, the conﬁguration

of a particular LS) or about many resources of the same type (for example, a summary of all con

ﬁgured LSs),

depending on the options used. In addition, some QUERY_* verbs have the option of returning either summary or

detailed information about the speciﬁed resources. This section explains how to use these options.

2.7.1 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 ﬁrst)

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

NOF API Verbs.

This means that an application can obtain information about multiple resources by requesting the complete list or

a speciﬁed 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 speciﬁc 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 ﬁrst entry required:

• First entry in the list

• Entries starting from a speciﬁc named entry

• Entries starting from the next entry after a speciﬁc named entry. (The name speciﬁed 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 ﬁrst entry after

NODEC, the ﬁrst entry returned is NODED.)

In addition, if the list_options parameter does not request starting from the ﬁrst entry, the name of a speciﬁc 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 speciﬁed 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.