QM The Multi-Value Database for PC Based Applications

QMClient API Guide

QMClient API Guide

QMClient API Guide Historically, multi-value databases have used a character based user interface. QM includes a set of Windows OLE compatible functions that enable development of applications in, for example, Visual Basic. This manual describes these functions and includes examples of how to use them to develop a Windows style front end to your application. The same functions are also available in the qmclilib library for use in C programs and as a QMBasic class module for use in QMBasic programs. This manual discusses all of these API sets. In addition, the QMClient.pb record in the SYSCOM file contains an interface layer for use with the PureBasic product from Fantaisie Software.

Overview The API functions enable a Visual Basic or C application to access data stored in the QM database or allow connection to remote QM systems from within QMBasic application programs. There are API equivalents to the major file handling statements of QMBasic as well as a range of string functions for dynamic array data manipulations, functions to execute commands and catalogued subroutines on the server, etc. The secret of writing efficient client server applications is to perform the bulk data processing on the server and only handle user interface issues on the client. This minimises the data transferred between the systems and hence optimises performance.

Using the Visual Basic API The QMClient Windows API consists of two components; a Visual Basic module (QMClient.bas) containing the API function definitions, and a dynamic link library (QMClient.dll) containing the actual interface functions. To use the API functions in a Visual Basic application, include the QMClient.bas module in your project. This module is placed in the SYSCOM file of the QMSYS account when QM is installed. The QMClient.dll library must be installed on the client system. This library is placed in the Windows directory (not necessarily c:\windows) when QMClient is installed. These components may be freely copied and distributed as necessary. From QM release 2.2-8, QMClient allows up to four connections from a single client process. This allows development of applications that transfer data between accounts or servers. Functions that return boolean values, return 0 for False, -1 for True in the Visual Basic API.

Using the C API Use of the C programmers' API is different depending on the compiler in use. On Linux and FreeBSD, programs need to include the qmclilib.o object file when linking the application. The Linux version of QM also includes a shared object version of the QMClient API named qmclilib.so. On Windows, the qmclilib.dll dynamic link library is used and two import libraries are provided to include when linking the application; qmcllbbl.lib for Borland C users and qmcllbms.lib for Microsoft

QMClient API Guide

2.4-9

2

QMClient API Guide

C users. All of these components can be found in the bin subdirectory of the QMSYS account. The function definitions can be found in the qmclilib.h include record in the SYSCOM file. From QM release 2.2-8, QMClient allows up to four connections from a single client process. This allows development of applications that transfer data between accounts or servers. Functions that return boolean values, return 0 for False, 1 for True in the C API library. API calls that return strings dynamically allocate memory to hold the returned data. It is the calling program's responsibility to release this memory using the QMFree() function when it is no longer required. This function must be used in place of the standard free() C runtime library routine to ensure compatibility with the memory allocator used by the QMClient library.

Using the QMBasic Class Module API The QMClient class module is supplied as a globally catalogued item named !QMCLIENT. To create a QMClient session, the object is instantiated with a statement of the form session = object("qmclient") The session is then connected to a server using the CONNECT method ok = session->connect(hostname, port, user, password, account) The four connection limit that applies to other QMClient API styles does not apply to the QMBasic interface. The limit here is imposed by how many socket connections the underlying system permits. Functions that return boolean values, return 0 for False, 1 for True in the QMBasic class module API.

QMClient API Guide

2.4-9

3

QMClient API Guide

API Function Summary This section lists the API functions by type.

Session Management QMConnect() QMConnected() QMConnectLocal() QMDisconnect QMDisconnectAll QMGetSession() QMLogto() QMSetSession()

Establishes a QMClient session via a network Verifies whether a QMClient session is open Establishes a QMClient session on the local system Terminates a QMClient session Terminates all QMClient sessions from this client Retrieves currently selected session number Moves to an alternative account Selects the session to which subsequent function calls relate

File Handling QMClearSelect QMClose QMDelete QMDeleteu QMMarkMapping() QMOpen() QMRead() QMReadl() QMReadList() QMReadNext() QMReadu() QMRecordlock() QMRelease QMSelect() QMSelectIndex() QMSelectLeft() QMSelectRight() QMSettLeft() QMSettRight() QMWrite QMWriteu

Clears a select list Closes a file Deletes a record Deletes a record, retaining the lock Enables/disables mark mapping for a directory file Opens a file Reads a record without locking Reads a record with a shareable read lock Reads a select list Retrieves a record id from a select list Reads a record with an exclusive update lock Locks a record Releases a record lock Generates a select list Generates a select list from an alternate key index Scan left in an alternate key index Scan right in an alternate key index Position at the left in an alternate key index Position at the right in an alternate key index Writes a record Writes a record, retaining the lock

Dynamic Array Manipulation QMDel() QMExtract() QMIns() QMLocate() QMReplace()

Deletes a field, value or subvalue Extracts a field, value or subvalue Inserts a field, value or subvalue Searches for a field, value or subvalue Replaces a field, value or subvalue

String Manipulation QMChange()

QMClient API Guide

Change substrings

2.4-9

4

QMClient API Guide

QMDcount() QMField() QMFree() QMMatch() QMMatchfield()

Count delimited items in a string Extract substring from delimited string Free dynamically allocated memory (C API only) Test pattern match Extract data based on pattern match

Command Execution QMEndCommand QMExecute() QMRespond()

Abort an executed command Execute a command on the server Respond to a request for input from an executed command

Subroutine Execution QMCall

Call a catalogued subroutine on the server

Error Handling QMError() QMStatus()

Returns extended error message text Returns STATUS() value

Security Issues of the QMClient API In most systems, a normal terminal user is taken directly into the application on logging in and the application itself controls what the user can do. The ON.ABORT paragraph provides a mechanism to ensure that, even if the application fails, the user cannot fall back to a command prompt. With QMClient, the client session is effectively at a command prompt from which it can open, read and write files, execute commands, or call subroutines. It becomes the responsibility of the client software to control what the user can do. A knowledgeable user with a valid user name and password could, however, develop a client session that connects in the same way as the application and then goes on to do almost anything. Setting appropriate access rights on files may help but is unlikely to be a perfect solution to this potential security threat. The QMCLIENT configuration parameter can be used to control the level of access that a QMClient session has. It takes one of three values: 0

All functions are available.

1

QMOpen() and QMExecute() and not available. The client session can call subroutines and, if these generate select lists, can continue to use QMReadnext(), etc but cannot access file directly or run commands.

2

The level 1 restrictions are extended to restrict QMCall to allow access only to subroutines that have been compiled with the $QMCALL compiler directive. The actions of those subroutines are not restricted. Thus, the $QMCALL directive should appear in all subroutines to be executed directly by the client.

The QMCLIENT configuration parameter starts with the value defined in the QM configuration parameters and can be modified to a higher level using the CONFIG command but cannot be taken

QMClient API Guide

2.4-9

5

QMClient API Guide

to a lower level in this way. Because QMClient sessions execute the LOGIN paragraph on connection, the CONFIG command is easily executed from this paragraph. It may also be useful to validate the client network address (see @IP.ADDR) in the LOGIN paragraph.

QMClient API Guide

2.4-9

6

QMClient API Guide

API Function Descriptions This section contains an alphabetical list of function descriptions.

Many functions have an Errno argument passed by reference as an Integer variable. This will be set to one of the following values broadly corresponding to the various clauses applicable to the equivalent QMBasic statements. 0

SV_OK

Action successful

1

SV_ON_ERROR Action took the ON ERROR clause to recover from a situation that would otherwise cause the server process to abort.

2

SV_ELSE

Action took the ELSE clause. In most cases the QMStatus() function can be used to determine the error number.

3

SV_ERROR

An error occurred for which extended error text can be retrieved using the QMError() function.

4

SV_LOCKED

The action was blocked by a lock held by another user. The QMStatus() function can be used to determine the blocking user.

5

SV_PROMPT

A command executed on the server is waiting for input. The only valid client functions when this status is returned are QMRespond(), QMEndCommand and QMDisconnect.

The tokens shown above are defined in the QMClient.bas Visual Basic module and the qmclilib.h C include file.

QMClient API Guide

2.4-9

7

QMClient API Guide

QMCall The QMCall function calls a catalogued subroutine on the server.

Format VB

QMCall(ByVal SubrName as String, ByVal ArgCount as Integer, Optional ByRef Arg1 as String, ...)

C

QMCall(char * SubrName, short int ArgCount as Integer, ArgList...)

Obj

Session->Call(SubrName, ArgList...)

where SubrName

is the name of the subroutine to be called.

ArgCount

is the count of arguments following (not present in QMBasic class module API).

ArgList

is a list of arguments to be passed to the subroutine.

The QMCall function calls the named catalogued subroutine on the server system. In the Visual Basic and C APIs, there may be at most 20 variables named as arguments and these must be declared as strings. In the C API, the size of any argument variable that may be overwritten by the subroutine must be large enough to receive the updated value. Failure to observe this rule will result in memory corruption. If the subroutine modifies the values of any of its arguments, this will be reflected in the variables specified in ArgList. It is a good idea to ensure that arguments that are only used for values returned from the subroutine are set to empty strings before the call to minimise data unnecessarily sent across the network. The called subroutine may make use of any of the standard QMBasic programming statements and functions, however, it may not perform terminal input or output as there is no terminal associated with a server process.

QMClient API Guide

2.4-9

8

QMClient API Guide

QMChange() The QMChange() function replaces occurrences of one substring with another in a string.

Format VB

QMChange(ByVal Src as String, ByVal OldStr as String, ByVal NewStr as String, Optional ByRef Occurrences as Long, Optional ByRef Start as Long) as String

C

char * QMChange(char * Src, char * OldStr, char * NewStr, int Occurrences, int Start)

where Src

is the string to be processed.

OldStr

is the substring to be replaced.

NewStr

is the replacement substring.

Occurrences is the number of occurrences of OldStr to be replaced. If omitted (VB only) or specified as less than one, all occurrences are replaced. Start

is the occurrence number from one of the first occurrence of OldStr to be replaced. If omitted (VB only) or less than one, replacement commences at the first occurrence of OldStr.

The QMChange() function returns a new string with the specified substrings replaced. One use of QMChange() is to replace mark characters with carriage return / line feed pairs when transferring data from a dynamic array to a multi-line text box.

Note that in the C API library, a statement of the form rec = QMChange(rec, old, new, 0, 0) 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.

QMClient API Guide

2.4-9

9

QMClient API Guide

QMClearSelect The QMClearSelect function clears a select list.

Format VB

QMClearSelect(ByVal ListNo as Integer)

C

void QMClearSelect(int ListNo)

Obj

Session->ClearSelect(ListNo)

where ListNo

is a valid select list number (0 to 10)

The QMClearSelect function clears the specified select list. No error occurs if the list was not active. Applications that use select list 0 (the default select list) and could leave unprocessed items in the list should always clear it to avoid unwanted effects on later server processing.

QMClient API Guide

2.4-9

10

QMClient API Guide

QMClose The QMClose function closes a file.

Format VB

QMClose(ByVal FileNo as Integer)

C

void QMClose(int FileNo)

Obj

Session->Close(FileNo)

where FileNo

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

The server maintains a list of files open for processing by the client application. The QMClose function causes the server to close the specified file. It is not normally necessary to close files as there is no practical limit to the number of files that the server can hold open at once, however, for best performance applications should close files if they are unlikely to be referenced for a considerable time.

QMClient API Guide

2.4-9

11

QMClient API Guide

QMConnect() The QMConnect() function establishes a QMClient session.

Format VB QMConnect(ByVal Host as String, ByVal Port as Integer, ByVal UserName as String, ByVal Password as String, ByVal Account as String) as Boolean C

int QMConnect(char * Host, int Port, char * UserName, char * Password, char * Account)

Obj

Bool = Session->Connect(Host, Port, UserName, Password, Account)

where Host

is the IP address or name of the server system.

Port

is the port number to which connection is to be made. Set this to -1 to use the QM default port.

UserName

is the username under which the server process is to run.

Password

is the password for the given UserName.

Account

is the name of the QM account to be accessed.

The QMConnect() function attempts to establish a QMClient process on the system identified by the Host argument. If successful, the function returns True. If unsuccessful, the function returns False and the QMError() function can be used to retrieve a text error message identifying the cause of the failure. Host can reference the local machine. For an alternative method of starting a local QM session, see the QMConnectLocal() function. A single client may open up to four connections simultaneously. The internal session number associated with the session opened by QMConnect() can be retrieved using QMGetSession(). All subsequent QMClient function calls relate to the most recently opened session unless QMSetSession() is used to select an alternative session. QMClient sessions run the LOGIN paragraph (if present) but not the MASTER.LOGIN paragraph. A QMClient session can be recognised within this paragraph by testing the value of @TTY which will be "vbsrvr" for QMClient.

QMClient API Guide

2.4-9

12

QMClient API Guide

QMConnected() The QMConnected() function confirms whether a QMClient session is open.

Format VB

QMConnected() as Boolean

C

int QMConnected()

Obj

Bool = Session->Connected

The QMConnected() function can be used by an application to determine whether a client session is open.

QMClient API Guide

2.4-9

13

QMClient API Guide

QMConnectLocal() The QMConnectLocal() function establishes a QMClient session on the local system.

Format VB

QMConnectLocal(ByVal Account as String) as Boolean

C

int QMConnectLocal(char * Account)

where Account

is the name of the QM account to be accessed.

The QMConnectLocal() function attempts to establish a QMClient process on the local system. This process runs as the user executing the function. If successful, the function returns True. If unsuccessful, the function returns False and the QMError() function can be used to retrieve a text error message identifying the cause of the failure. A single client may open up to four connections simultaneously. The internal session number associated with the session opened by QMConnectLocal() can be retrieved using QMGetSession(). All subsequent QMClient function calls relate to the most recently opened session unless QMSetSession() is used to select an alternative session. QMClient sessions run the LOGIN paragraph (if present) but not the MASTER.LOGIN paragraph. A QMClient session can be recognised within this paragraph by testing the value of @TTY which will be "vbsrvr" for QMClient. NOTE: The underlying operating system call needed by QMConnectLocal() is not implemented on Windows 95, 98 or ME. It will be necessary to use QMConnect() for these systems. QMConnectLocal() is not supported by the QMBasic class module API.

QMClient API Guide

2.4-9

14

QMClient API Guide

QMDcount() The QMDcount() function counts delimited items in a string.

Format VB

QMDcount(ByVal Src as String, ByVal Delim as String) as Long

C

int QMDcount(char * Src, char * Delim)

where Src

is the string to be processed

Delim

is the delimiter character. If Delim is more than one character long, only the first character is used.

The QMDcount() function is usually used to count fields, values or subvalues in a dynamic array but can be used to count elements in any string that is separated by some single character delimiter.

QMClient API Guide

2.4-9

15

QMClient API Guide

QMDel() The QMDel() function deletes a field, value or subvalue from a dynamic array.

Format VB

QMDel(ByVal Src as String, ByVal Fno as Integer, ByVal Vno as Integer, ByVal Svno as Integer) as String

C

char * QMDel(char * Src, int Fno, int Vno, int Svno)

where Src

is the dynamic array to be processed

Fno

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

Vno

is the number of the value to be deleted. If less than 1, the entire field is deleted.

Svno

is the number of the subvalue to be deleted. If less than 1, the entire value is deleted.

The QMDel() function returns a new dynamic array with the given field, value or subvalue deleted. If the required item is not found, the original string is returned unchanged.

Note that in the C API library, a statement of the form rec = QMDel(rec, 2, 1, 0) 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.

QMClient API Guide

2.4-9

16

QMClient API Guide

QMDelete The QMDelete function deletes a record from a file.

Format VB

QMDelete(ByVal FileNo as Integer, ByVal Id as String)

C

void QMDelete(int FileNo, char * Id)

Obj

Session->Delete(FileNo, Id)

where FileNo

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

Id

is the id of the record to be deleted.

The QMDelete function deletes the named record from the file open as FileNo. No error occurs if the record does not exist. Applications should always obtain an update lock for a record before deleting it. The lock is released by this function.

QMClient API Guide

2.4-9

17

QMClient API Guide

QMDeleteu The QMDeleteu function deletes a record from a file, retaining the record lock.

Format VB

QMDeleteu(ByVal FileNo as Integer, ByVal Id as String)

C

void QMDeleteu(int FileNo, char * Id)

Obj

Session->Deleteu(FileNo, Id)

where FileNo

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

Id

is the id of the record to be deleted.

The QMDeleteu function deletes the named record from the file open as FileNo. No error occurs if the record does not exist. Applications should always obtain an update lock for a record before deleting it. The lock is retained on return from this function.

QMClient API Guide

2.4-9

18

QMClient API Guide

QMDisconnect The QMDisconnect function terminates a QMClient session.

Format VB

QMDisconnect()

C

void QMDisconnect(void)

Obj

Session->Disconnect

The QMDisconnect function terminates a QMClient session previously established using QMConnect().

QMClient API Guide

2.4-9

19

QMClient API Guide

QMDisconnectAll The QMDisconnectAll function terminates all QMClient sessions from a client process.

Format VB

QMDisconnectAll()

C

void QMDisconnectAll(void)

A single client may establish multiple QMClient connections. The QMDisconnectAll() function terminates all such connections. The QMDisconnectAll() function has no equivalent in the QMBasic class module API as each session is a separate instantiation of the object.

QMClient API Guide

2.4-9

20

QMClient API Guide

QMEndCommand The QMEndCommand function aborts a command executed on the server that is requesting input.

Format VB

QMEndCommand()

C

void QMEndCommand(void)

Obj

void QMEndCommand(void)

This function may only be used when an immediately preceding QMExecute() or QMRespond() function has returned a status of SV_PROMPT. The QMEndCommand() function causes the server command to be aborted.

QMClient API Guide

2.4-9

21

QMClient API Guide

QMError() The QMError() function returns extended error message text.

Format VB

QMError() as String

C

char * QMError(void)

Obj

Str = Session->Error

Some API functions documented in this guide set extended error text and return an error code of SV_ERROR when an error condition occurs. The QMError() function can be used to retrieve this text. Note that in the C API, this function returns a pointer to a statically allocated error message buffer. The calling program must not attempt to free this memory.

QMClient API Guide

2.4-9

22

QMClient API Guide

QMExecute() The QMExecute() function executes a command on the server.

Format VB

QMExecute(ByVal Cmnd as String, ByRef Errno as Integer) as String

C

char * QMExecute(char * Cmnd, int * Errno)

Obj

Str = Session->Execute(Cmnd, Errno)

Cmnd

is the command to be executed.

Errno

is an integer variable to receive status information.

where

The QMExecute() function executes the specified command on the server. The output from this command is returned as a text string. If the command completes without requesting input, the Errno variable is set to SV_OK. If the command requests input, any output up to that point is returned and the Errno variable is set to SV_PROMPT. The client may respond to this using the QMRespond() function or abort the command using the QMEndCommand() function. On completion of the command, QMStatus() will return the value of @SYSTEM.RETURN.CODE. The executed command may perform most functions of the QM database. Specific restrictions are: Input may be requested from the client using the QMBasic INPUT and INPUT@ statements. Use of the KEYIN() function is not allowed. Testing for input using the QMBasic KEYREADY() function or the INPUT -1 syntax will not show input waiting. The length parameter of an INPUT statement will be ignored if present. Execution of a further command from within the executed command may not behave correctly.

QMClient API Guide

2.4-9

23

QMClient API Guide

QMExtract() The QMExtract() function extracts a field, value or subvalue from a dynamic array.

Format VB

QMExtract(ByVal Src as String, ByVal Fno as Integer, ByVal Vno as Integer, ByVal Svno as Integer) as String

C

char * QMExtract(char * Src, int Fno, int Vno, int Svno)

where Src

is the dynamic array to be processed

Fno

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

Vno

is the number of the value to be extracted. If less than 1, the entire field is extracted.

Svno

is the number of the subvalue to be extracted. If less than 1, the entire value is extracted.

The QMExtract() function returns the given field, value or subvalue from the source string. If the required item is not found, a null string is returned.

QMClient API Guide

2.4-9

24

QMClient API Guide

QMField() The QMField() function extracts one or more components of a delimited string.

Format VB

QMField(ByVal Src as String, ByVal Delimiter as String, ByVal Start as Long, Optional ByRef Occurrences as Long) as String

C

char * QMField(char * Src, int Delimiter, int Start, int Occurrences)

where Src

is the string to be processed.

Delimiter

is the single character delimiter separating components of the string.

Start

is the number from one of the first component of Src to be returned.

Occurrences is the number of delimited of components of Src to be returned. If omitted (VB only) or less than one, one component is returned.

The QMField() function returns the specified substring components of Src.

QMClient API Guide

2.4-9

25

QMClient API Guide

QMFree() The QMFree() function releases memory returned by other functions. It is only used with the C API library.

Format void QMFree(void * addr)

where addr

is the pointer to a dynamic memory area returned by another API function.

The QMFree() function is needed because the memory allocator used within the API functions may not be compatible with that of the calling program.

QMClient API Guide

2.4-9

26

QMClient API Guide

QMGetSession() The QMGetSession() function returns the internal session number associated with the currently selected QMClient session.

Format VB

QMGetSession() as Integer

C

int QMGetSession(void)

A single client may open multiple QMClient sessions, each identified by a session number. The QMConnect() and QMConnectLocal() functions select an available session number to use for the newly created session which may be retrieved using QMGetSession(). All subsequent QMClient function calls relate to this session until an alternative session is selected using QMSetSession(). The QMGetSession() function has no equivalent in the QMBasic class module API as each session is managed as a separate instantiation of the object.

QMClient API Guide

2.4-9

27

QMClient API Guide

QMIns() The QMIns() function inserts a field, value or subvalue in a dynamic array.

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.

QMClient API Guide

2.4-9

28

QMClient API Guide

QMLocate() The QMLocate() function searches a dynamic array for a field, value or subvalue matching a given string.

Format VB

QMLocate(ByVal Item as String, ByVal DynArray as String, ByVal Fno as Integer, ByVal Vno as Integer, ByVal Svno as Integer, ByRef Pos as Integer, ByVal Order as String) as Boolean

C

int QMLocate(char * Item, char * DynArray, int Fno, int Vno, int Svno, int * Pos, char * Order)

Usage Found = QMLocate(Item, DynArray, Fno, Vno, Svno, Pos, Order) where Item

is the item to find.

DynArray

is the dynamic array to be processed.

Fno

is the number of the field at which the search is to begin. If less than 1, 1 is assumed.

Vno

is the number of the value at which the search is to begin. If less than 1, the function searches for a field containing Item.

Svno

is the number of the subvalue at which the search is to begin. If less than 1, the function searches for a value containing Item.

Pos

is an integer variable to receive the position information.

Order

identifies the sort method to the applied. This may be: AL Ascending, left aligned AR Ascending, right aligned DL Descending, left aligned DR Descending, right aligned If omitted, no sort order is applied.

The QMLocate() function searches a dynamic array at one of three levels: If Vno is less than 1, the function searches the dynamic array for a field matching Item, starting at the field position given by Fno. If Vno is given but Svno is less than 1, the function searches field Fno of the dynamic array for a value matching Item, starting at the value position given by Vno.

QMClient API Guide

2.4-9

29

QMClient API Guide

If Vno and Svno are given, the function searches field Fno, value Vno of the dynamic array for a subvalue matching Item, starting at the value position given by Svno. The Order argument determines the sorting system to be applied during the search: If Order is a null string, no sort rules are applied. The function scans all applicable dynamic array elements for a match against Item. The Pos variable will be returned as the position at which the item was found. If the item is not found, Pos will be returned as the position at which a new element could be appended. If the first character of Order is A, an ascending sort is applied. If the first character of Order is D, a descending sort is applied. In either case, the search terminates if an entry is found that would be beyond the correct position for Item. In this case, if the item is not found, Pos will be returned as the position at which to insert Item to maintain the correct sort order. If the second character of Order is L, a left aligned comparison is performed. Each entry of the dynamic array is compared with Item character by character from the left until a difference is found. If the second character of Order is R, a right aligned comparison is performed. If the two items being compared are of different lengths, spaces are added to the front of the shorter item before comparison. The QMLocate() function returns True if the item is found, False if it is not found.

QMClient API Guide

2.4-9

30

QMClient API Guide

QMLogto() The QMLogto() function moves to an alternative account.

Format VB

QMLogto(ByVal Account as String) as Boolean

C

int QMLogto(char * Account)

Obj

Bool = Session->Logto(Account)

where Account

is the name of the QM account to be accessed.

The QMLogto() function attempts to move to the named account. If successful, the function returns True. If unsuccessful, the function returns False and the QMError() function can be used to retrieve a text error message identifying the cause of the failure. The LOGIN paragraph will be executed (if present). A QMClient session can be recognised within this paragraph by testing the value of @TTY which will be "vbsrvr" for QMClient.

QMClient API Guide

2.4-9

31

QMClient API Guide

QMMarkMapping The QMMarkMapping function enables or disables mark mapping for a directory file.

Format VB

QMMarkMapping(ByVal FileNo as Integer, ByVal State as Integer)

C

void QMMarkMapping(int FileNo, int State)

Obj

Session->MarkMapping(FileNo, State)

where FileNo

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

State

is non-zero to enable mark mapping, zero to disable.

The QMMarkMapping function enables or disables mark character mapping on the file open as FileNo. See the QMBasic MARK.MAPPING statement for more details.

QMClient API Guide

2.4-9

32

QMClient API Guide

QMMatch() The QMMatch() function matches a character string against a pattern template.

Format VB

QMMatch(ByVal Src as String, ByVal Pattern as String) as Boolean

C

int QMMatch(char * Src, char * Pattern)

where Src

is the string to be processed.

Pattern

is the pattern template to be used

The QMMatch() function tests whether Src matches the Pattern template consisting of one or more concatenated items from the following list. ... 0X nX n-mX 0A nA n-mA 0N nN n-mN "string"

Zero or more characters of any type Zero or more characters of any type Exactly n characters of any type Between n and m characters of any type Zero or more alphabetic characters Exactly n alphabetic characters Between n and m alphabetic characters Zero or more numeric characters Exactly n numeric characters Between n and m numeric characters A literal string which must match exactly. Either single or double quotation marks may be used.

The values n and m are integers with any number of digits. m must be greater than or equal to n. The 0A, nA, 0N, nN and "string" patterns may be preceded by a tilde (~) to invert the match condition. For example, ~4N matches four non-numeric characters such as ABCD (not a string which is not four numeric characters such as 12C4). A null string matches patterns ..., 0A, 0X, 0N, their inverses (~0A, etc) and "". The 0X and n-mX patterns match against as few characters as necessary before control passes to the next pattern. For example, the string ABC123DEF matched against the pattern 0X2N0X matches the pattern components as ABC, 12 and 3DEF. The 0N, n-mN, 0A, and n-mA patterns match against as many characters as possible. For example, the string ABC123DEF matched against the pattern 0X2-3N0X matches the pattern components as ABC, 123 and DEF. The pattern string may contain alternative templates separated by value marks. The QMMatch() function tries each template in turn until one is a successful match against the string.

QMClient API Guide

2.4-9

33

QMClient API Guide

QMMatchfield() The QMMatchfield() function matches a character string against a pattern template and extracts the part corresponding to a specified pattern component.

Format VB

QMMatchfield(ByVal Src as String, ByVal Pattern as String, ByVal Component as Integer) as String

C

char * QMMatchfield(char * Src, char * Pattern, int Component)

where Src

is the string to be processed.

Pattern

is the pattern template to be used

Component

is the pattern template component number for which the corresponding part of Src is to be returned.

The QMMatchfield() function matches Src against the Pattern template as described for the QMMatch() function. If the string matches, the portion corresponding to the specified Component is returned. If the string does not match the pattern, a null string is returned.

QMClient API Guide

2.4-9

34

QMClient API Guide

QMOpen() The QMOpen() function opens a file.

Format VB

QMOpen(ByVal FileName as String) as Integer

C

int QMOpen(char * FileName)

Obj

FileNo = Session->Open(FileName)

where FileName

is the name of the file to be opened. This must correspond to an F or Q-type entry in the VOC of the QM account in which the server is running.

The QMOpen() function opens a QM database file. The returned integer value is the file number which must be used in all subsequent operations against this file. If the file cannot be opened, the function returns zero. The QMStatus() function can be used to retrieve the error cause. To open a dictionary, the FileName argument should commence with "DICT" and a single space separating this prefix from the file name, for example: DictNo = QMOpen("DICT READERS")

There is no practical limit to the number of files that can be open at one time.

QMClient API Guide

2.4-9

35

QMClient API Guide

QMRead() The QMRead() function reads a record without locking.

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.

QMClient API Guide

2.4-9

36

QMClient API Guide

QMReadl() The QMReadl() function reads a record with a shareable read lock.

Format VB

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

C

char * QMReadl(int FileNo, char * Id, int Wait, int * Errno)

Obj

Str = Session->Readl(FileNo, Id, Wait, Errno)

where FileNo

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

Id

is the id of the record to be read.

Wait

is a boolean value indicating the action to be taken if the record is currently locked by another user: True wait for the record to become available False return an error code of SV_LOCKED

Errno

is an integer variable to receive status information.

The QMReadl() function requests the server to return the record with key Id from the file opened as FileNo. A shareable read lock is applied to the record. Any number of users may hold a shareable read lock on the same record at one time but, while any user has a shareable read lock, no other user can establish an update lock or a file lock. 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. 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.

QMClient API Guide

2.4-9

37

QMClient API Guide

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

Format VB

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

C

char * QMReadList(int ListNo)

Obj

Str = Session->ReadList(ListNo)

where ListNo

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

Errno

receives 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.

QMClient API Guide

2.4-9

38

QMClient API Guide

QMReadNext() The QMReadNext() function retrieves the next entry from a select list

Format VB

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

C

char * QMReadNext(int ListNo)

Obj

Str = Session->ReadNext(ListNo)

where ListNo

is the number of the select list to be processed in the range 0 to 10.

Errno

receives an error value indicating the outcome of the request. The C API does not have this argument and returns NULL if an error occurs.

The QMReadNext() function retrieves the next entry from the select list identified by the ListNo argument. If successful, the function returns the list entry and, in the Visual Basic API, Errno is set to SV_OK. If the list is empty, the Visual Basic API function returns a null string and Errno is set to SV_ELSE. In the C API implementation, the function returns NULL.

See also the QMReadList() function for a discussion of the relationship between QMReadNext() and QMReadList().

Note that in the C API library, the returned string is dynamically allocated. A loop containing a call to this function must free the memory from each call separately.

QMClient API Guide

2.4-9

39

QMClient API Guide

QMReadu() The QMReadu() function reads a record with an exclusive update lock.

Format VB

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

C

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

Obj

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

where FileNo

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

Id

is the id of the record to be read.

Wait

is a boolean value indicating the action to be taken if the record is currently locked by another user: True wait for the record to become available False return an error code of SV_LOCKED

Errno

is 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.

QMClient API Guide

2.4-9

40

QMClient API Guide

QMRecordlock The QMRecordlock function locks a record.

Format VB

QMRecordlock(ByVal FileNo as Integer, ByVal Id as String, ByVal Update as Integer, ByVal Wait as Integer)

C

void QMRecordlock(int FileNo, char * Id, int update, int wait)

Obj

Session->Recordlock(FileNo, Id, update, wait)

where FileNo

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

Id

is the id of the record to be locked.

Update

is a boolean value specifying the type of lock to be obtained: True Update lock False Shareable read lock

Wait

is a boolean value indicating the action to be taken if the record is currently locked by another user: True wait for the record to become available False return an error code of SV_LOCKED

The QMRecordlock function can be used to obtain a lock on a record without reading the record.

QMClient API Guide

2.4-9

41

QMClient API Guide

QMRelease The QMRelease function releases a record lock.

Format VB

QMRelease(ByVal FileNo as Integer, ByVal Id as String)

C

void QMRelease(int FileNo, char * Id)

Obj

Session->Release(FileNo, Id)

where FileNo

is the file number returned by a previous QMOpen() call. If zero, all locks are released.

Id

is the id of the record to be unlocked. If given as a null string, all locks in the file identified by FileNo are released.

The QMRelease function can be used to release a lock without writing or deleting the record. One common use of this function is to release the lock obtained by a call to QMReadl() or QMReadu() where the record was not found and the function returned the SV_ELSE status.

QMClient API Guide

2.4-9

42

QMClient API Guide

QMReplace() The QMReplace() function replaces the content of a field, value or subvalue in a dynamic array.

Format VB

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

C

char * QMReplace(char * Src, int Fno, char * Vno, int Svno, char * NewData)

where Src

is the dynamic array to be processed

Fno

is the number of the field to be replaced. If zero, 1 is assumed. If negative, a new field is appended to the dynamic array.

Vno

is the number of the value to be replaced. If zero, the entire field is inserted. If negative, a new value is appended to the specified field.

Svno

is the number of the subvalue to be replaced. If zero, the entire value is inserted. If negative, a new subvalue is appended to the specified value.

NewData

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

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

Note that in the C API library, a statement of the form rec = QMReplace(rec, 2, 0, 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.

QMClient API Guide

2.4-9

43

QMClient API Guide

QMRespond() The QMRespond() function responds to a request for input from a command executed on the server.

Format VB

QMRespond(ByVal Response as String, ByRef Errno as Integer) as String

C

char * QMRespond(char * Response, int * Errno)

Obj

Session->Respond(Response, Errno)

where Response

is the response to be sent.

Errno

is an integer variable to receive status information.

This function may only be used when an immediately preceding QMExecute() or QMRespond() function has returned a status of SV_PROMPT. The QMRespond() function returns the given Response to the input request from the server command. Further output from this command is returned as a text string. If the command completes without requesting input, the Errno variable is set to SV_OK. If the command requests further input, any output up to that point is returned and the Errno variable is set to SV_PROMPT. The client may respond to this using the QMRespond() function or abort the command using the QMEndCommand() function.

QMClient API Guide

2.4-9

44

QMClient API Guide

QMSelect The QMSelect function generates a select list containing the ids of all records in a file.

Format VB

QMSelect(ByVal FileNo as Integer, ByVal ListNo as Integer)

C

void QMSelect(int FileNo, int ListNo)

Obj

Session->Select(FileNo, ListNo)

where FileNo

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

ListNo

is the select list number (0 to 10).

The QMSelect function constructs a list of record ids which can subsequently be processed using the QMReadNext() function. Select list 0, the default select list, is used automatically by many QM components to control their action and should, therefore, be used with caution. An unwanted or partially processed select list can be cleared using the QMClearSelect function. See the QMReadList() function for a discussion on different ways to process the select list. The QMSelect function does not provide any method to select only those records that meet specific conditions or to sort the list. These features can be accessed by executing query processor commands using the QMExecute() function.

QMClient API Guide

2.4-9

45

QMClient API Guide

QMSelectIndex The QMSelectIndex function generates a select list from an alternate key index.

Format VB

QMSelectIndex(ByVal FileNo as Integer, ByVal IndexName as String, ByVal IndexValue as String, ByVal ListNo as Integer)

C

void QMSelectIndex(int FileNo, char * IndexName, char * IndexValue, int ListNo)

Obj

Session->SelectIndex(FileNo, IndexName, IndexValue, ListNo)

where FileNo

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

IndexName

is the name of the alternate key index to be used.

IndexValue

is the value to be located in the alternate key index.

ListNo

is the select list number (0 to 10).

The QMSelect function constructs a list of record ids from an entry in an alternate key index. This list can subsequently be processed using the QMReadNext() function. Select list 0, the default select list, is used automatically by many QM components to control their action and should, therefore, be used with caution. An unwanted or partially processed select list can be cleared using the QMClearSelect function. See the QMReadList() function for a discussion on different ways to process the select list.

QMClient API Guide

2.4-9

46

QMClient API Guide

QMSelectLeft QMSelectRight The QMSelectLeft() and QMSelectRight() functions traverse an alternate key index, creating a select list from the entry to the left or right of the last entry processed.

Format VB

QMSelectLeft(ByVal FileNo as Integer, ByVal IndexName as String, ByVal ListNo as Integer) as String

C

char * QMSelectLeft(int FileNo, char * IndexName, int ListNo)

Obj

Str = Session->SelectLeft(FileNo, IndexName, ListNo)

where Var

is the variable to receive the index key value associated with the returned list.

FileNo

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

IndexName

is the name of the alternate key index to be used.

ListNo

is the select list number (0 to 10).

The QMSelectLeft() and QMSelectRight() functions construct a select list from the alternate key index entry to the left or right of the one most recently returned by QMSelectIndex(), QMSelectLeft or QMSelectRight(). The position of the scan can be set at the extreme left using QMSetLeft or at the extreme right using QMSetRight. These operations allow a program to find a specific value and then walk through successive values in the sorted data structure that makes up an alternate key index. If QMSelectIndex() is used to locate a value that does not exist in the index, QMSelectLeft() will return a list of records for the value immediately before the non-existant one and QMSelectRight() will return a list of records for the value immediately after the non-existant one. The QMStatus() function returns zero if the operation is successful, non-zero if it fails because the index does not exist.

QMClient API Guide

2.4-9

47

QMClient API Guide

QMSetLeft QMSetRight The QMSetLeft and QMSetRight functions set the scanning position of an alternate key index at the extreme left or right of the data.

Format VB

QMSetLeft ByVal FileNo as Integer, ByVal IndexName as String

C

void QMSetLeft(int FileNo, char * IndexName)

Obj

Session->SetLeft(FileNo, IndexName)

where FileNo

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

IndexName

is the name of the alternate key index to be used.

The QMSelectLeft and QMSelectRight functions are used with QMSelectLeft() and QMSelectRight() to set the scan position to the first or last entry in an alternate key index. The QMSatus() function returns zero if the operation is successful, non-zero if it fails because the index does not exist.

QMClient API Guide

2.4-9

48

QMClient API Guide

QMSetSession() The QMSetSession() selects an active QMClient session to be referenced by subsequent function calls.

Format VB

QMSetSession(ByVal Session as Integer) as Boolean

C

int QMSetSession(int session)

A single client may open multiple QMClient sessions, each identified by a session number. The QMSetSession() function determines to which session subsequent QMClient function calls relate. The QMSetSession() function has no equivalent in the QMBasic class module API as each session is managed by a separate instantiation of the object.

QMClient API Guide

2.4-9

49

QMClient API Guide

QMStatus() The QMStatus() function returns the value of the QMBasic STATUS() function for the last server function executed.

Format VB

QMStatus() as Long

C

int QMStatus(void)

Obj

Var = Session->ServerStatus

Many server actions set the QMBasic STATUS() value and return it to the client process. The QMStatus() function retrieves this value. This function does not require passing of a client server message pair as the value is held on the client system.

QMClient API Guide

2.4-9

50

QMClient API Guide

QMWrite The QMWrite function writes a record.

Format VB

QMWrite(ByVal FileNo as Integer, ByVal Id as String, ByVal Rec as String)

C

void QMWrite(int FileNo, char * Id, char * Rec)

Obj

Session->Write(FileNo, Id, Rec)

where FileNo

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

Id

is the id of the record to be written.

Rec

is the data to be written to this record.

The QMWrite function writes the given data to the file opened as FileNo. If a record with this Id already exists, it is replaced. If the record does not already exist, it is added. An application should always obtain an update lock on the record before writing it. This function releases the lock.

QMClient API Guide

2.4-9

51

QMClient API Guide

QMWriteu The QMWriteu function writes a record, retaining the lock.

Format VB

QMWriteu(ByVal FileNo as Integer, ByVal Id as String, ByVal Rec as String)

C

void QMWriteu(int FileNo, char * Id, char * Rec)

Obj

Session->Writeu(FileNo, Id, Rec)

where FileNo

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

Id

is the id of the record to be written.

Rec

is the data to be written to this record.

The QMWriteu function writes the given data to the file opened as FileNo. If a record with this Id already exists, it is replaced. If the record does not already exist, it is added. An application should always obtain an update lock on the record before writing it. The lock is retained on return from this function.

QMClient API Guide

2.4-9

52

QMClient API Guide

Example Application The application described here is a very simple single form Visual Basic program that handles return of books in the QM demonstration database. This database is described in the Tutorial Guide in the documentation set and can be created using the SETUP.DEMO command. The form displayed by this application is as shown below.

On entry, the form displays a list of reader numbers and their names in the left hand list box. Double clicking on a reader populates the reader details frame. Double clicking on a loan, returns that book to stock and repaints the loan details. The code components of the application are shown below.

Declarations Dim Readers As Integer Dim ReaderId As String Dim ReaderRec As String

' READERS file and... ' ...current reader's record id ... ' ...and record data

Dim Books As Integer

' BOOKS file

Dim CRNL As String Dim VM As String Dim FM As String ' Standard Windows definitions for tabbed text boxes Const LB_SETTABSTOPS = &H192 Private Declare Function SendMessage Lib "user32" Alias "SendMessageA" (ByVal hwnd As Long, ByVal wMsg As Long, ByVal wParam As Long, lParam As Long) As Long

Form Load Procedure Private Sub Form_Load() VM = Chr(253)

QMClient API Guide

2.4-9

FM = Chr(254)

53

QMClient API Guide

CRNL = Chr(13) & Chr(10) ' Connect to server If Not QMConnect("LBS2", -1, "GUEST", "GUESTPASS", "READERDEMO") Then MsgBox "Unable to connect to server", vbCritical, "Connection Failed" Unload Me Exit Sub End If ' Open READERS file Readers = QMOpen("READERS") If Readers = 0 Then MsgBox "Cannot open READERS file", vbCritical, "Initialisation Error" Unload Me Exit Sub End If ' Open BOOKS file Books = QMOpen("BOOKS") If Books = 0 Then MsgBox "Cannot open BOOKS file", vbCritical, "Initialisation Error" Unload Me Exit Sub End If Me.Show ' Build list of reader ids RefreshReaderList End Sub

Form Unload Procedure Private Sub Form_Unload(Cancel As Integer) QMDisconnect End Sub

Reader List Processing Private Sub ReaderList_DblClick() ' Select reader and display their loan details LoansList.Clear NameBox.Text = "" AddressBox.Text = "" ReaderId = QMField(ReaderList.List(ReaderList.ListIndex), Chr(9), 1, 1) ReaderRec = QMReadu(Readers, ReaderId, False, ErrNo) Select Case ErrNo Case SV_OK NameBox.Text = QMExtract(ReaderRec, 1, 0, 0) AddressBox.Text = QMChange(QMExtract(ReaderRec, 2, 0, 0), VM, CRNL) RefreshLoans Case SV_LOCKED MsgBox "Reader details are currently locked by another user", vbExclamation

QMClient API Guide

2.4-9

54

QMClient API Guide

Case Else MsgBox "Error " & QMStatus() & " reading reader details", vbExclamation End Select End Sub Private Sub RefreshReaderList() ' Update list of readers ' Show reader number and name using tabbed list Dim TabStops(1 To 1) As Long ReaderList.Clear TabStops(1) = 20 i = SendMessage(ReaderList.hwnd, LB_SETTABSTOPS, 1, TabStops(1)) QMSelect Readers, 1 Do Id = QMReadNext(1, ErrNo) If ErrNo SV_OK Then Exit Do ReaderRec = QMRead(Readers, Id, ErrNo) ReaderList.AddItem Id & Chr(9) & QMExtract(ReaderRec, 1, 0, 0) Loop End Sub

Loans List Processing Private Sub LoansList_DblClick() ' Return book Dim BookId As String Dim BookRec As String Dim ErrNo As Integer BookId = QMField(LoansList.List(LoansList.ListIndex), Chr(9), 1, 1) BookRec = QMReadu(Books, BookId, False, ErrNo) Select Case ErrNo Case SV_OK BookRec = QMReplace(BookRec, 1, 0, 0, "") ' Clear reader id BookRec = QMReplace(BookRec, 2, 0, 0, "") ' Clear date out QMWrite Books, BookId, BookRec ReaderRec = QMDel(ReaderRec, 3, LoansList.ListIndex + 1, 0) QMWrite Readers, ReaderId, ReaderRec RefreshLoans Case SV_LOCKED MsgBox "Book details are currently locked by another user", vbExclamation Case Else QMRelease Books, BookId MsgBox "Error " & QMStatus() & "accessing book details", vbExclamation End Select End Sub Private Sub RefreshLoans() 'Repaint updated loan details Dim Dim Dim Dim

Loans As String BookId As String TabStops(1 To 1) As Long BookRec As String

QMClient API Guide

2.4-9

55

QMClient API Guide

LoansList.Clear TabStops(1) = 20 i = SendMessage(LoansList.hwnd, LB_SETTABSTOPS, 1, TabStops(1)) Loans = QMExtract(ReaderRec, 3, 0, 0) NumLoans = QMDcount(Loans, VM) For i = 1 To NumLoans BookId = QMExtract(Loans, 1, i, 0) BookRec = QMRead(Books, BookId, ErrNo) LoansList.AddItem BookId & Chr(9) & FormattedDate(QMExtract(BookRec, 2, 0, 0)) Next i End Sub Private Function FormattedDate(QMDayNo As Long) As String ' Return QM date as day/month/year n = QMDayNo + 24837 FormattedDate = Day(n) & "/" & Month(n) & "/" & Year(n) End Function

Note the conversion of a QM style internal date to a Visual Basic style date by adding 24837 to the day number.

QMClient API Guide

2.4-9

56

QMClient API Guide

Index API Function Summary .......................................................................................................................................................4 Example Application .........................................................................................................................................................53 Introduction to QM..............................................................................................................................................................2 Overview .............................................................................................................................................................................2 QMCall ................................................................................................................................................................................8 QMChange() ........................................................................................................................................................................9 QMClearSelect ..................................................................................................................................................................10 QMClose............................................................................................................................................................................11 QMConnect().....................................................................................................................................................................12 QMConnected() .................................................................................................................................................................13 QMConnectLocal()............................................................................................................................................................14 QMDcount() ......................................................................................................................................................................15 QMDel() ............................................................................................................................................................................16 QMDelete ..........................................................................................................................................................................17 QMDeleteu ........................................................................................................................................................................18 QMDisconnect...................................................................................................................................................................19 QMDisconnectAll..............................................................................................................................................................20 QMEndCommand..............................................................................................................................................................21 QMError() .........................................................................................................................................................................22 QMExecute() .....................................................................................................................................................................23 QMExtract() ......................................................................................................................................................................24 QMField()..........................................................................................................................................................................25 QMFree..............................................................................................................................................................................26 QMGetSession() ................................................................................................................................................................27 QMIns() .............................................................................................................................................................................28 QMLocate() .......................................................................................................................................................................29 QMLogto() ........................................................................................................................................................................31 QMMarkMapping..............................................................................................................................................................32 QMMatch()........................................................................................................................................................................33 QMMatchfield().................................................................................................................................................................34 QMOpen() .........................................................................................................................................................................35 QMRead()..........................................................................................................................................................................36 QMReadl().........................................................................................................................................................................37 QMReadList()....................................................................................................................................................................38 QMReadNext() ..................................................................................................................................................................39 QMReadu()........................................................................................................................................................................40 QMRecordlock ..................................................................................................................................................................41 QMRelease ........................................................................................................................................................................42 QMReplace() .....................................................................................................................................................................43 QMRespond() ....................................................................................................................................................................44 QMSelect...........................................................................................................................................................................45 QMSelectIndex..................................................................................................................................................................46 QMSelectLeft ....................................................................................................................................................................47 QMSelectRight ..................................................................................................................................................................47 QMSetLeft .........................................................................................................................................................................48 QMSetRight.......................................................................................................................................................................48 QMSetSession().................................................................................................................................................................49 QMStatus() ........................................................................................................................................................................50 QMWrite............................................................................................................................................................................51 QMWriteu..........................................................................................................................................................................52

QMClient API Guide

2.4-9

57