QMClient API

Top  Previous  Next

 

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 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 for use in C programs and as a QMBasic class module for use in QMBasic programs. This help section 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 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.

 

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.

 

 

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. The C programmers' API is a single library, qmclilib.

 

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

 

 

 

API Function Summary

 

Session Management

 

QMConnect()Establishes a QMClient session via a network
QMConnected()Verifies whether a QMClient session is open
QMConnectLocal()Establishes a QMClient session on the local system
QMDisconnectTerminates a QMClient session
QMDisconnectAllTerminates all QMClient sessions from this client
QMGetSessionRetrieves currently select session number
QMLogto()Moves to an alternative account
QMSetSessionSelects the session to which subsequent function calls relate

 

 

File Handling

 

QMClearSelectClears a select list
QMCloseCloses a file
QMDeleteDeletes a record
QMDeleteuDeletes a record, retaining the lock
QMMarkMapping()Enables/disables mark mapping for a directory file
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
QMReleaseReleases 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
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
QMWriteWrites a record
QMWriteuWrites 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
QMDcount()Count delimited items in a string
QMField()Extract substring from a delimited string
QMFree()Free dynamically allocated memory (C API only)
QMMatch()Test pattern match
QMMatchfield()Extract data based on pattern match

 

 

Command Execution

 

QMEndCommandAbort an executed command
QMExecute()Execute a command on the server
QMRespond()Respond to a request for input from an executed command

 

 

Subroutine Execution

 

QMCallCall a catalogued subroutine on the server

 

 

Error Handling

 

QMError()Returns extended error message text
QMStatus()Returns STATUS() value

 

 

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.

 

0SV_OK        Action successful

 

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

 

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

 

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

 

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

 

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

 

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