QMClient.NET README for v2.0.2

History

QMClient.NET v1.0 was created by Manuel J. Goyenechea in 2004 as a simple set of managed declarations for the qmclilib.dll. After the initial creation it was not modified. Sometime after v2006 Manuel's website went offline and it was difficult to find a version of QMClient.NET. The software was effectively dead.

In early 2011, Tony Gravagno enhanced the wrapper with extended support for QMCall, ensuring proper handling of ByRef and ByVal arguments, and adding overloads for more convenient development.

With a class named QMClient, and all operations performed in static methods beginning with QM, it seemed that the QM moniker was over-used.  After the change to QMCall, all method names had the QM prefix removed, resulting in QMClient.Call, QMClient.Status, etc.

The new version was repackaged into a .NET 3.5 project. The namespace was changed from stec.openqm to NebulaRnD.QM to avoid confusion with the prior release. The version was updated to 2.0.1. After minor updates including a new sample project, the software was released as v2.0.2

Obviously with this new version, QMClient.NET cannot readily be used to replace existing code that relies on v1.0. With verification, a global change in existing code from "QMClient.QM" to "QMClient." should be adequate.

A new project, QMClient.Tests was created which at this time only tests a subset of available functionality. The test project is Windows Form app which allows a code walkthrough, runtime changes, etc. To use the tests, modify the code with your own server, account, user, and password. BASIC code provided in the test source is required on the server. Testing the code requires a one-step walk through of the code - it is not a series of tests that returns success/failure. The tests are as much for developers to learn how to use the software as to test functionality - the project itself is not intended to display output confirming correct functionality. One of the tests executes through the same functionality as the original lists.cs provided with v1.0.

As of v2.0.2, updates to this project may be obtained from the Nebula R&D freeware web page:
http://Nebula-RnD.com/freeware/QMClient.NET.zip
The software is being maintained by Tony until this README indicates otherwise. A public project at Codeplex may be created if there is any demand.

Using QMClient.NET

The only thing required to use QMClient.NET is that qmclilib.dll must be in your system path. The latest version available, dated may-21-2010, is in the Source\QMClient.NET\bin directory. This can be dropped into your Windows\System32 directory (or another directory in the system path). The file does not need to be registered.

Differences from qmclilib.dll

As of v2.0  the API is exactly the same as documented in the QM reference manual, except that method names do not begin with "QM". For example, in the manual see "QMWriteu" where the QMClient.NET method is "Writeu".

A string "Version" property was added in case your client code needs to identify the assembly version.

In addition to Int values QM_FM, QM_VM, and QM_SVM which were in v1.0, v2.0 includes Char values AM, FM, VM, and SVM to easily embed system delimiters into strings.

The Call method has many overloads to support string[] arrays, ByRef strings passed as "ref p1, ref p2...." and ByVal strings passed as simply "p1, p2".

Call overloads have also been added which eliminate the need for argCount, which seems redundant with a fixed number of arguments. The Call method supports the argCount parameter to be compatible with qmclilib but that value is ignored and replaced with the actual number of parameters used. When passing a string[] array the argCount element is optional, but when used only a subset of the array is passed to the server. For example if array.Length=10 and argCount=3, then only array elements 0, 1, and 2 will be sent to the BASIC subroutine. 

To Do

The best thing to do at this point is simply to use the assembly as-is until a bug is found. If you would like to contribute to this library, here are some suggestions:

License

QMClient.NET is licensed under the terms of the GPL

Copyright (c) 2004 Manuel J. Goyenechea. All rights reserved.
Copyright (c) 2011 Tony Gravagno, Nebula R&D. All rights reserved.


This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to
the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.


A copy of the GPL license is included in this distribution, in the file license.txt.