QMClient API |
![]() ![]() ![]() |
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
File Handling
Dynamic Array Manipulation
String Manipulation
Command Execution
Subroutine Execution
Error Handling
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.
The tokens shown above are defined in the QMClient.bas module and the qmclilib.h C include file.
|