NWDSItrCount

Returns the number of entries left in this iterator.

Local Servers:blocking
Remote Servers:blocking
NetWare Server:4.x, 5.x, 6.x
Platform:NLM, Windows NT, Windows 95, Windows 98
Library:Cross-Platform NDS (NET*.*)
Service:NDS Iterator

Syntax

  #include <nwnet.h> 
  or 
  #include <nwitr.h> 
   
  NWDSCCODE  NWDSItrCount ( 
     nuint_ptr  Iterator, 
     nuint32    timeout, 
     nuint32    maxCount, 
     nbool8     updatePosition, 
     pnuint32   pCount);

Parameters

Iterator

(IN) Specifies the iterator object.

timeout

(IN) Specifies the time (in milliseconds) allowed before returning an error. If 0 is passed, there is no time limit.

maxCount

(IN) Specifies how many entries to scan before stopping. If 0 is passed, there is no maximum limit.

updatePosition

(IN) Specifies whether the current position will be left pointing to the last entry counted.

  • N_TRUE The current position equals the last entry counted or EOF.
  • N_FALSE The current position is unchanged.
pCount

(OUT) Points to the number of entries counted.

Return Values

0x0000 0000

Indicates the function successfully counted all remaining entries in the list and reached the end of the list. The pCount parameter contains the actual number of objects counted.

ERR_ITR_MAX_COUNT

Indicates the function reached the maximum count.

ERR_QUERY_TIMEOUT

Indicates the function reached its timeout before counting all the entries. The pCount parameter contains the actual number of objects counted.

ERR_ITR_INVALID_HANDLE

Indicates the Iterator parameter was not a valid iterator object.

nonzero value

Nonzero values indicate errors. See NDS Return Values (-001 to -799).

Remarks

NWDSItrCount will scan the list until one of the following occurs:

  • The end of the list is reached (returns 0)

  • maxCount entries have been counted (returns ERR_ITR_MAX_COUNT)

  • The time limit expires (returns ERR_QUERY_TIMEOUT)

Entries are scanned starting from the current position. Make sure the current position is at the top of the list if you want a total count.

If both the timeout and maxCount parameters are zero, the function will scan the entire list and return an exact count. On NDS 8 servers, this process may be very slow on large lists. On eDirectory servers with previous versions of NDS, the timeout parameter is ignored since the count can be determined immediately.

If scanning stops due to reaching the values specified by timeout or maxCount, call NWDSItrGetPosition to estimate the real count. If more accuracy is needed, call NWDSItrCount again with a larger timeout or maxCount value.

If, on an NDS 8 server, you need only an approximate count of the number of entries in the list, use the following procedure.

  1. Position the iterator at the top of the list with NWDSItrSetPosition.

  2. Call NWDSItrCount to count for a specified number of entries and have the updatePosition parameter move to the last entry counted.

  3. Call the NWDSItrGetPosition function to discover the iterator's current position.

By comparing the logical position with the number of entries you requested to count, you can estimate the total length of the list. For example, if you requested to count 5,000 objects and the current logical position is 500 (or 50%), you can estimate that there are 10,000 objects in the list.

For sample code, see Section 4.2, Counting with eDirectory Iterators: Example.

NCP Calls

See Also

NWDSItrGetPosition