QMRead()

The QMRead() function reads a record without locking. It is analogous to the QMBasic READ statement.

Format

VB	QMRead(ByVal FileNo as Integer, ByVal Id as String, ByRef Errno as Integer) as String

C	char * QMRead(int FileNo, char * Id, int * Errno)

Obj	Str = Session->Read(FileNo, Id, Errno)

where

FileNo

is the file number returned by a previous QMOpen() call.

Id	is the id of the record to be read.

Errno

is an integer variable to receive status information.

The QMRead() function requests the server to return the record with key Id from the file opened as FileNo.

If successful, the function returns the record as a dynamic array string and the Errno variable is set to SV_OK.

If the record cannot be found, the function returns a null string and the Errno variable is set to SV_ELSE. The QMStatus() function can be used to retrieve the error number.

Conditions that would normally cause a QMBasic program to abort or to take the ON ERROR clause of a READ statement return a null string and the Errno variable is set to SV_ON_ERROR. The QMStatus() function can be used to retrieve the error number.

In the C API library, the dynamic memory allocated for the returned string must subsequently be freed by the calling program. Note that attempting to read a non-existent record returns a pointer to a null string, not a NULL pointer.

Examples

fClients = QMOpen("CLIENTS")

Rec = QMRead(fClients, ClientNo, ErrNo)

QMClose(fClients)

fClients = QMOpen("CLIENTS");

Rec = QMRead(fClients, ClientNo, &ErrNo);

QMClose(fClients);

QMBasic

fClients = session->Open("CLIENTS")

Rec = session->Read(fClients, ClientNo, ErrNo)

session->Close(fClients)

The above program fragment opens the CLIENTS file, reads the record identified by ClientNo, and then closes the file. A real program should test the ErrNo status from the read to determine if the action was successful.

Note that the C example leaves variables Rec pointing to a dynamically allocated memory area that must be released using QMFree() when no longer needed.