lb_lookup_object(3ncs)lb_lookup_object(3ncs)Namelb_lookup_object - look up information about an object in the Global
Location Broker database
Syntax
#include <idl/c/lb.h>
void lb_$lookup_object(object, lookup_handle, max_num_results,
num_results, results, status)
uuid_$t *object;
lb_$lookup_handle_t *lookup_handle;
unsigned long max_num_results;
unsigned long * num_results;
lb_$entry_t results[ ];
status_$t *status;
Arguments
object The UUID of the object being looked up.
lookup_handle A location in the database. On input, the
lookup_handle indicates the location in the data‐
base where the search begins. An input value of
lb_$default_lookup_handle specifies that the search
will start at the beginning of the database. On
return, the lookup_handle indicates the next
unsearched part of the database (that is, the point
at which the next search should begin). A return
value of lb_$default_lookup_handle indicates that
the search reached the end of the database; any
other return value indicates that the search found
at most max_num_results matching entries before it
reached the end of the database.
max_num_results The maximum number of entries that can be returned
by a single routine. This should be the number of
elements in the results array.
num_results The number of entries that were returned in the
results array.
results An array that contains the matching GLB database
entries, up to the number specified by the
max_num_results parameter. If the array contains
any entries for servers on the local network, those
entries appear first.
status The completion status. If the completion status
returned in is equal to status_$ok , then the rou‐
tine that supplied it was successful.
Description
The routine returns GLB database entries whose object field matches the
specified object UUID.
The routine cannot return more than max_num_results matching entries at
a time. The lookup_handle parameter enables you to find all matching
entries by doing sequential lookups.
If you use a sequence of lookup routines to find entries in the data‐
base, it is possible that the returned results will skip or duplicate
entries. This is because the Location Broker does not prevent modifi‐
cation of the database between lookups, and such modification can
change the locations of entries relative to a lookup_handle value.
It is also possible that the results of a single lookup routine will
skip or duplicate entries. This can occur if the size of the results
exceeds the size of an RPC packet (64K bytes).
Examples
The following statement, looks up GLB database entries for the object
identified by :
lb_$lookup_object(&bank_id, &lookup_handle,
MAX_LOCS, &n_locs, bank_loc, &status);
Diagnostics
This section lists status codes for errors returned by this routine in
lb_$database_invalid
The format of the Location Broker database is out
of date. The database may have been created by an
old version of the Location Broker; in this case,
delete the out-of-date database and reregister any
entries that it contained. The LLB or GLB that was
accessed may be running out-of-date software; in
this case, update all Location Brokers to the cur‐
rent software version.
lb_$database_busy The Location Broker database is currently in use in
an incompatible manner.
lb_$not_registered The Location Broker does not have any entries that
match the criteria specified in the lookup or
unregister routine. The requested object, type,
interface, or combination thereof is not registered
in the specified database. If you are using an or
routine specifying an LLB, check that you have
specified the correct LLB.
lb_$cant_access The Location Broker cannot access the database.
Among the possible reasons:
1. The database does not exist.
2. The database exists, but the Location Broker
cannot access it.
lb_$server_unavailable
The Location Broker Client Agent cannot reach the
requested GLB or LLB. A communications failure
occurred or the broker was not running.
FilesSee Alsointro(3ncs), lb_lookup_interface(3ncs), lb_lookup_object_local(3ncs),
lb_lookup_range(3ncs), lb_lookup_type(3ncs)lb_lookup_object(3ncs)
