QMIns()

The QMIns() function inserts a field, value or subvalue in a dynamic array. It is analogous to the QMBasic INSERT() function.

Format

VB	QMIns(ByVal Src as String, ByVal Fno as Integer, ByVal Vno as Integer, ByVal Svno as Integer, ByVal NewData as String) as String

C	char * QMIns(char * Src, int Fno, int Vno, int Svno, char * NewData)

where

Src	is the dynamic array to be processed

Fno	is the number of the field to be inserted. If less than 1, 1 is assumed.

Vno	is the number of the value to be inserted. If less than 1, an entire field is inserted.

Svno	is the number of the subvalue to be inserted. If less than 1, an entire value is inserted.

NewData

is the new data to form the new dynamic array element.

The QMIns() function returns a new dynamic array with the specified field, value or subvalue inserted.

Note that in the C API library, a statement of the form

rec = QMIns(rec, 2, 1, 0, new_data)

will return a pointer to a newly allocated memory area, overwriting the rec pointer. The old memory is not freed by this call and it is therefore necessary to retain a pointer to the original rec string so that it can be freed later.

This function is evaluated on the client system and does not require a server connection to be open.

Examples

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

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

QMWrite fClients, ClientNo, Rec

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

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

QMWrite(fClients, ClientNo, Rec2);

QMFree(Rec);

QMFree(Rec2);

The above program fragment reads a record with an update lock, uses QMIns() to modify 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.