QMReadu()

 Top  Previous  Next

 

The QMReadu() function reads a record with an exclusive update lock. It is analogous to the QMBasic READU statement.

 

 

Format

 

VBQMReadu(ByVal FileNo as Integer, ByVal Id as String, ByVal Wait as Boolean, ByRef Errno as Integer) as String

 

Cchar * QMReadu(int FileNo, char * Id, int Wait, int * Errno)

 

ObjStr = Session->Readu(FileNo, Id, Wait, Errno)

 

where

 

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

 

Idis the id of the record to be read.

 

Waitis a boolean value indicating the action to be taken if the record is currently locked by another user:
Truewait for the record to become available
Falsereturn an error code of SV_LOCKED

 

Errnois an integer variable to receive status information.

 

 

The QMReadu() function requests the server to return the record with key Id from the file opened as FileNo. An exclusive update lock is applied to the record. Only one user may hold an exclusive update lock on any one record at one time. An exclusive update lock also cannot be obtained if another user holds a shareable read lock on the record or a file lock on the entire file.

 

If the action is blocked by a lock held by another user, the function returns a null string and the Errno variable is set to SV_LOCKED. The QMStatus() function can be used to retrieve the user number of the process holding the lock.

 

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

 

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. The record is locked by the server process to allow creation of the record. If the lock is not required, it should be released using the QMRelease() function.

 

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

 

VB

Rec = QMReadu(fClients, ClientNo, True, ErrNo)

Rec = QMReplace(Rec, 1, Pos, 0, NewData)

QMWrite fClients, ClientNo, Rec

C

Rec = QMReadu(fClients, ClientNo, TRUE, &ErrNo);

Rec2 = QMReplace(Rec, 1, Pos, 0, NewData);

QMWrite(fClients, ClientNo, Rec2);

QMFree(Rec);

QMFree(Rec2);

QMBasic

Rec = session->Readu(fClients, ClientNo, @true, ErrNo)

Rec<1, Pos> = NewData

session->Write(fClients, Id, Rec)

 

The above program fragment reads a record with an update lock, modifies it and then writes it back to the file. A real program should test the ErrNo status from the read operations to determine if they were successful.

 

Note how the C example uses QMFree() to release the dynamic memory allocated to store Rec and Rec2.