Select lists in QMClient sessions
Because a QMClient session operates in two parts, one on the client and one on the server, it is important to understand how this affects use of select lists.
Using the QMSelect() function followed by repeated use of the QMReadNext() function builds the select list on the server and then returns items one by one. This will use the same group by group optimisation that is described with the QMBasic SELECT statement but, because the select list is maintained on the server, retrieval of each entry requires passing of a message pair between the client and the server which may be slow. However, because the select list actually exists at the server side of the QMClient session, it is available for use by commands and programs executed on the server within the session.
A QMClient application can read the entire select list in a single operation using the QMReadList() function and then extract entries using the QMExtract() function. This requires the list to be fully constructed before it can be returned to the client and hence loses the performance advantage gained from the group by group selection process.
Use of QMSelectPartial() provides a way to gain much of the performance advantage of the group by group select but without needing to retrieve each record id separately. This function performs an optimised select operation on the server and then returns a number of ids as a field mark delimited string. The QMNextPartial() function then retrieves a further set of record ids until the list is exhausted. Because QMSelectPartial() returns the first part of the list immediately, the full list is not available on the server for use by commands or programs executed within the QMClient session.
QMNextPartial() is effectively the same as a series of QMReadNext() operations that merge the results into a single string before returning it to the server. It can therefore also be used to retrieve data from a select list constructed by QMSelect(), a program or a command.
There is a further consideration for processes that use QMReadNext() or QMNextPartial() and also update the file by adding new records. Because the optimised selection process is finding records one by one as processing progresses, any records written during the processing may appear later in the returned list. Using QMReadList() to construct and retrieve the entire list before processing commences ensures that records added during processing will not be included in the list.
If a QMClient application uses QMSelectPartial() but the server pre-dates introduction of this function, the entire list is returned similar to use of QMSelect() followed by QMReadList(). Similarly, use of QMNextPartial() with a server that does not support it is equivalent to use of QMReadList().