QMReadList()

Top  Previous  Next

 

The QMReadList() function reads a select list into a dynamic array in the client application

 

 

Format

 

VBQMReadList(ByVal ListNo as Integer, ByRef Errno as Integer) as String

 

Cchar * QMReadList(int ListNo)

 

ObjStr = Session->ReadList(ListNo)

 

where

 

ListNois the number of the select list to be read in the range 0 to 10.

 

Errnoreceives an error value indicating the outcome of the request.

 

 

If the action is successful, the returned value contains a field mark delimited set of unprocessed entries from the given list. The original list is destroyed by this action.

 

The Visual Basic API returns an empty string if there is no data to read. The C API returns NULL in this situation.

 

A server application can read entries from a select list one at a time using the QMReadNext() function. 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. For best performance, the QMReadList() function can be used to transfer the entire select list to the client where entries can then be extracted using the QMExtract() function.

 

There are times when use of QMReadNext() may give apparently better performance. When QM performs a select operation against a dynamic file, the file is actually processed as each entry is taken from the list. There is, therefore, no lengthy silence while QM constructs the list before entries can be retrieved. Use of QMReadList() requires the list to be fully constructed before it can be returned to the client.

 

There is a further consideration for processes that use QMReadNext() and also update the file by adding new records. Because QMReadNext() is finding records one by one as processing progresses, any records written during the processing may subsequently be found by QMReadNext(). 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.