After the request and response buffers are prepared, they are passed to NDS in the NWDSSearch call

A prototype for NWDSSearch is shown below:

 (NWDSCCODE) NWDSSearch (	 NWDSContextHandle 	 context,
 	 	 	 pnstr8 	 	 	 baseObjectName,  
 	 	 	 nint 	 	 	 scope, 
 	 	 	 nbool8 	 	 	 searchAliases, 
 	 	 	 Buf_T 	 	 	 *reqBuf, 
 	 	 	 nuint32 	 	 	 infoType, 
 	 	 	 nbool8 	 	 	 allAttrs, 
 	 	 	 pBuf_T 	 	 	 attrNames, 
 	 	 	 pnint32 	 	 	 itHandle, 
 	 	 	 nint32	 	 	 countObjsToSearch, 
 	 	 	 pnint32 	 	 	 countObjsSearched, 
 	 	 	 Buf_T 	 	 	 *respBuf );

context Specifies the NDS context for the request.

baseObjectName The name of the container object in which to start search.

scope Specifies the depth of the search (see Table 1).

searchAliases TRUE-Dereference aliases, FALSE-Don't dereference aliases.

reqBuf Points to the request buffer in containing the search filter.

infoType Specifies the type of info to return (see Table 2).

allAttrs TRUE-Return Info about all attrs, FALSE-only attrs in attrNames.

attrNames Points to a buffer containing attr names of interest.

itHandle Used by NW client to reference call iteration info.

countObjsToSearch RESERVED.

countObjsSearched Obtains the number of objects searched by server.

respBuf The buffer to be filled with search result info by NDS.

Note: Non-zero return values from NWDSSearch indicate an error. To understand handling client side NDS errors, refer to handling_errors.

Table 1: Scope Flags

Table 2: Information Types for Search and Read

The itHandle parameter is what is called an iteration handle. Applications must sometimes repeat an NDS request multiple times in order to have it completed because, at a lower level, multiple NDS network transactions may be required to send or obtain the desired information. In these NDS calls, an iteration handle is used by the NetWare client to manage the process state of the request. Before the operation loop, the iteration handle is initialized to NO_MORE_ITERATIONS. The operation is complete when NDS sets the iteration handle to NO_MORE_ITERATIONS, which is a negative one. NWDSSearch is just such an iterative NDS request.

If an iterative request, such as NWDSSearch, must be terminated by the application, it should use NWDSCloseIteration to notify the client to close the iteration so that the iteration's resources can be freed.

Notes:

1. WDSSearch succeeds if the search base object is located, regardless of whether there are any subordinates to the base object.

2. Aliases are dereferenced while locating the base object unless the context flag associated with DCV_DEREF_ALIASES is not set.

3. Aliases among the subordinates of the base object are dereferenced during the search unless the searchAliases parameter is FALSE. If the searchAliases parameter is TRUE, the search continues in the subtree of the aliased object.

4. Currently, because of aliasing, searching a subtree can result (1) in duplicate entries or (2) in an infinite loop.

This example specifies DS_ATTRIBUTE_NAMES as the infoType parameter because it really isn't interested in the values of the objects. What it really wants to know is the distinguished names of all of the User objects that have approximately the same surname as theSurname value passed in the search filter (see explanation 2). Using DS_ATTRIBUTE_NAMES gives the smallest return buffer or fewest iterations.

There may be several iterations of the NWDSSearch call depending on the number of API_Info objects in the tree. After each iteration of NWDSSearch, foundObjectsBuffer is passed to selectOptimalObj to determine which of the found objects contains a reference to the closest service.