QMClient API

Historically, multivalue 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 section 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 (qmclilib.dll on Windows, libqmclient.a on other platforms) for use in C programs and as a QMBasic class module for use in QMBasic programs. All of these API sets are discussed here.

In addition, the QMClient.pb record in the SYSCOM file contains an interface layer for use with the PureBasic product from Fantaisie Software.

A QMClient session is an interactive use of the system and hence is counted in determining the licensed user limit.

Overview

The API functions enable applications written in languages such as Visual Basic or C to access data stored in a 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. Where both ends of the connection support it, the network traffic is encrypted.

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.

QMClient has some security issues that need special consideration.

Licensing

The QMClient DLL and corresponding libraries may be freely distributed with application software. The QM licence redistribution clauses apply to the server software, not the QMClient client-side components. Although every attempt is made to ensure compatibility with older versions of the client libraries, there may be times when changes require the distributed client components to be updated.

Using the Visual Basic API

The QMClient Windows API consists of two components; a Visual Basic module (QMClient.bas, QMClient.vb or QMClient 2005.vb) 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 appropriate module from the QMSYS file dependant on the version of Visual Basic in use. The distinction is based on the representation of numeric data:

	16 bit	32 bit	64 bit
QMClient.bas	Integer	Long
QMClient.vb	Integer	Long
QMCLient2005.vb	Short	Integer	Long

All function declaration prototypes shown in this section are based on the QMClient.bas definitions. Developers should see the relevant for the correct data types for the version of Visual Basic being used.

The QMClient.dll library must be installed on the client system. This library is placed in the Windows directory (not necessarily c:\windows) when QM is installed. These components may be freely copied and distributed as necessary.

QMClient allows multiple 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, FreeBSD, AIX and Mac, programs need to include the libqmclient.a library when linking the application. The Linux version of QM also includes a shared object version of 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 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.

QMClient allows multiple connections from a single client process, known as sessions. 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. On Windows systems, 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. On other platforms, use of QMFree() is strongly recommended but this should be compatible with the C run time library free() function.

The Windows version of the C API supports multi-threading so long as two threads do not attempt an operation on the same session simultaneously. If a session could never be accessed by more than one thread simultaneously, no special coding is needed. A thread may access multiple sessions using QMSetSession() in which case QMClient will correctly track the currently active session in each thread. If a single session could be accessed by multiple threads simultaneously, it will be necessary to use semaphores or similar synchronisation techniques to ensure that actions on a single session do not overlap.

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)

Functions that return boolean values, return 0 for False, 1 for True in the QMBasic class module API. Status codes referenced with a prefix of SV_ in the function descriptions are defined in the SYSCOM KEYS.H include record with a prefix of SV$. For example, SV_OK becomes SV$OK for the QMBasic interface to QMClient.

Error Handling in QMClient Applications

QMClient was originally developed for use in applications that had a directly associated user screen on which error messages could be displayed. It has subsequently found use in applications that do not have a directly associated screen such as the server side of a web application. In such situations, it will be necessary to use the QMConnectionType function to disable display of error messages. To ensure that older applications continue to run unchanged, the default behaviour of QMClient is to display errors either using a pop-up message box (Windows) or by sending the message to the stderr error channel (Linux).

From release 2.11-3, nearly all QMClient functions start by setting the QMError() error string to null. Applications can test if QMError() is a null string in order to determine whether an error has occurred. Errors are returned in this way even if the older style displayed messages are still enabled.

The functions that do not change the QMError value are QMFree, QMStatus and QMError itself.

API Function Summary

Session Management

QMConnect()

Establishes a QMClient session via a network

QMConnected()

Verifies whether a QMClient session is open

QMConnectionType

Sets parameters that affect the behaviour of QMClient

QMConnectLocal()

Establishes a QMClient session on the local system

QMDisconnect

Terminates a QMClient session

QMDisconnectAll

Terminates all QMClient sessions from this client

QMGetSession

Retrieves currently select session number

QMLogto()

Moves to an alternative account

QMRevision()

Returns the revision level of the client and server components.

QMSetSession

Selects the session to which subsequent function calls relate

QMTrapCallAbort

Enables client trapping of aborts in QMCall

File Handling

Clear a file

Clears a select list

Closes a file

Deletes a record

Deletes a record, retaining the lock

QMEvaluate()

Evaluate a dictionary I-type

QMMarkMapping()

Enables/disables mark mapping for a directory file

QMNextPartial()

Return next part of a select list

QMOpen()

Opens a file

QMRead()

Reads a record without locking

QMReadl()

Reads a record with a shareable read lock

QMReadList()

Reads a select list

QMReadNext()

Retrieves a record id from a select list

QMReadu()

Reads a record with an exclusive update lock

QMRecordlock()

Locks a record

QMRecordlocked()

Query the lock state of a record.

QMRelease

Releases a record lock

QMSelect()

Generates a select list

QMSelectIndex()

Generates a select list from an alternate key index

QMSelectLeft()

Scan left in an alternate key index

QMSelectPartial()

Optimised select operation that returns multiple ids

QMSelectRight()

Scan right in an alternate key index

QMSetLeft()

Position at the left in an alternate key index

QMSetRight()

Position at the right in an alternate key index

QMWrite

Writes a record

QMWriteu

Writes a record, retaining the lock

Dynamic Array Manipulation

QMDel()

Deletes a field, value or subvalue

QMExtract()

Extracts a field, value or subvalue

QMIns()

Inserts a field, value or subvalue

QMLocate()

Searches for a field, value or subvalue

QMReplace()

Replaces a field, value or subvalue

String Manipulation

QMChange()

Change substrings

QMChecksum()

Calculate checksum value

QMDcount()

Count delimited items in a string

QMDecrypt()

Decrypt data

QMEncrypt()

Encrypt data

QMField()

Extract substring from a delimited string

QMFree()

Free dynamically allocated memory (C API only)

QMIConv()

Convert data to internal form

QMMatch()

Test pattern match

QMMatchfield()

Extract data based on pattern match

QMOConv()

Convert data to external form

Command Execution

QMEndCommand

Abort an executed command

QMExecute()

Execute a command on the server

QMRespond()

Respond to a request for input from an executed command

Subroutine Execution

QMCall

Call a catalogued subroutine on the server

QMCallx

Call a catalogued subroutine on the server, returning updated arguments with QMGetArg(). (C API only)

QMGetArg()

Retrieve an argument value after user of QMCallx. (C API only)

Error Handling

QMError()

Returns extended error message text

QMStatus()

Returns STATUS() value

Miscellaneous

QMGetVar()

Return value of @-variable on server

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 SYSCOM include record or Visual Basic module relevant to the language in use.