lb_lookup_range(3ncs)													     lb_lookup_range(3ncs)

Name
       lb_lookup_range - look up information in a Global Location Broker or Local Location Broker database

Syntax
       #include <idl/c/lb.h>

       void lb_$lookup_range(object, obj_type, obj_interface, location,
					    location_length, lookup_handle, max_num_results,
					    num_results, results, status)
       uuid_$t *object;
       uuid_$t *obj_type;
       uuid_$t *obj_interface;
       socket_$addr_t *location;
       unsigned long location_length;
       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.

       obj_type 	   The UUID of the type being looked up.

       obj_interface	   The UUID of the interface being looked up.

       location 	   The location of the database to be searched.  If the value of location_length is 0, the GLB database is searched.  Oth-
			   erwise, the LLB database at the host specified by location is searched; in this case, the port  number  in  the  socket
			   address is ignored, and the lookup request is sent to the LLB port.

       location_length	   The length, in bytes, of the socket address specified by the location field.  A value of 0 indicates that the GLB data-
			   base is to be searched.

       lookup_handle	   A location in the database.	On input, the lookup_handle indicates the  location  in  the  database	where  the  search
			   begins.  An input value of lb_$default_lookup_handle specifies that the search will start at the beginning of the data-
			   base.  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 routine that supplied it
			   was successful.

Description
       The routine returns database entries whose object, obj_type, and obj_interface fields match the specified values.  A value of uuid_$nil	in
       any  of	these input parameters acts as a wildcard and will match any value in the corresponding entry field.  You can specify wildcards in
       any combination of these parameters.

       The routine cannot return more than max_num_results matching entries at a time.	The lookup_handle parameter enables you to find all match-
       ing entries by doing sequential lookups.

       If  you	use a sequence of lookup routines to find entries in the database, it is possible that the returned results will skip or duplicate
       entries.  This is because the Location Broker does not prevent modification 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 information in the GLB database about servers that export the matrix interface for  any  objects  of  type
       array.  The variable glb is defined elsewhere as a null pointer.
       lb_$lookup_range(&uuid_$nil, &array_id, &matrix_id, glb, 0,
			    &lookup_handle, max_results,
			    &num_results, results, &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 current
			   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 LLB.  A communications failure occurred or the  broker  was
			   not running.

Files
See Also
       intro(3ncs), lb_lookup_interface(3ncs), lb_lookup_object(3ncs), lb_lookup_object_local(3ncs), lb_lookup_type(3ncs)

															     lb_lookup_range(3ncs)