/// <summary>
/// An iterator to get the next command for executing a request.
/// </summary>
/// <param name="current">
/// Returns the next command. On the initial call the value should
/// be <c>null</c>.
/// </param>
/// <returns>
/// The result of <see cref="ZIMapCommand.IsPending"/>.
/// </returns>
/// <remarks>
/// If the return value is <c>true</c> the caller must fetch and read the result
/// and call <see cref="ZIMapCommand.Reset"/> before the command can be reused.
/// <para/>
/// If the value of <paramref name="current"/> references a command whose state
/// is <see cref="ZIMapCommand.CommandState.Queued"/> the queued command will
/// be sent automatically.
/// </remarks>
/// <para />
/// Here a simple usage expample:
/// <para /><example><code lang="C#">
/// uint ucnt = NNN; // number of messages
/// uint usnd = 0; // send counter
/// uint urcv = 0; // receive counter
/// ZIMapCommand.Generic current = null;
/// ZIMapFactory.Bulk bulk = app.Factory.CreateBulk("XXXX", 4, false);
///
/// while(urcv < ucnt)
/// { // step 1: queue request and check for response ...
/// bool done = bulk.NextCommand(ref current);
///
/// // step 2: check server reply for error ...
/// if(done)
/// { urcv++;
/// if(!current.CheckSuccess("Command failed")) done = false;
/// }
///
/// // step 3: process data sent by server ...
/// if(done)
/// {
/// }
///
/// // step 4: create a new request
/// if(usnd < ucnt)
/// { current.Reset();
/// current.Queue();
/// usnd++;
/// }
/// }
/// bulk.Dispose();
/// </code></example>
public bool NextCommand(ref ZIMapCommand.Generic current)
{
if(current != null && current.State == ZIMapCommand.CommandState.Queued)
current.Execute(false);
uint uidx = FindIndex(current);
if(uidx == uint.MaxValue)
parent.RaiseError(ZIMapException.Error.InvalidArgument);
if(current != null) uidx++;
if(uidx >= commands.Length) uidx = 0;
current = commands[uidx];
return current.State != ZIMapCommand.CommandState.Created;
}
