Control the Return of Information
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.
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.
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: