Control the Return of Information

Edit online

Use iterators to enumerate through multiple returned objects.

Commands and methods store multiple items in an iterator. The iterator provides methods to enumerate through each returned object.

Iterators

Commands that retrieve a single record from the server block the calling thread in the Execute() method until the data arrives. The data is then put into a record object and returned. Other commands, like select statistics, can potentially return hundreds of records. If the Execute() method blocks until all records are returned, it can take longer to receive any feedback. If the records are all returned in one large block instead of being consumed one at a time, the computer slows down.

To solve these problems, commands that potentially retrieve multiple records return an iterator object as soon as the first record arrives. As data is returned, a background thread automatically appends to the iterator. The iterator has a connection to the server and the command object is not involved. This method allows you to process records as they arrive. The following example demonstrates the select process command returning a process iterator:
 CDSelectProcCmd cmd; 
 CDProcIterator it = cmd.Execute(node):

Accessing Iterator Records

The iterator keeps an internal list of all records returned from the server. Use the following commands to control iterator records:

  • HasMore()—Call this method to determine if any records are available in the list.
    Note: You must always call HasMore() before calling GetNext(). It is not legal to call GetNext() if there are no records.
  • GetNext()—If HasMore() returns TRUE, obtain the next record in the list using this command. It removes the next record from the list and returns it.

When all records are received from the server, the server notifies the iterator that the command is complete. After all records are removed using GetNext(), HasMore() returns FALSE.

If the iterator's list is empty, but the server has not notified the iterator that the command is complete, the iterator cannot determine whether there are more records. In this case, HasMore() blocks until more records are received from the server or a completion notification is received. Only then can the iterator return TRUE or FALSE.

The following is an example of accessing statistics records using an iterator:

 CDSelectStatCmd cmd; 
 CDStatIterator it = node.Execute (cmd); 
 while (it.HasMore()) { 
     CDStatistic stat = it.GetNext(); 
 // use the statistics object }