logo
Powered by QM on a Rpi server
Home
About OpenQM
Sales and Downloads
Help and Support
About
Login

Developer Information

If you an open source user and have a new source component or a modification that you would like to contribute to the standard source, email details to support@openqm.com. Please be aware of the following...

We make no guarantee that modifications submitted to us will be incorporated into a future OpenQM build. We reserve the right to reject or further modify the submitted components entirely at our discretion.

We ask you to indemnify us from any cost or actions arising from claims that your submission is partly or wholly someone else's intellectual property.

Where appropriate, unless otherwise requested, we will include the contributor's name in the history data for the relevant modules and in the readme file.

Modifications are more likely to be accepted if they follow the same general style as existing code.

All submitted modifications become the property of Ladybridge Systems Limited and may be included by us in a future release of the commercial QM product.

You need to send a completed version of the submittal document with your source submittal.


Making Changes

To make it easier for you to reintegrate your changes into a new version and to maintain compatibility between applications, it is helpful to adopt a few basic rules about how you make changes. No one will enforce these. They are here simply to make your life easy (and ours, if you submit your changes for inclusion in the standard product).


QMBasic coding style

Software developers all have their own personal style. We accept this but some consistency is desirable. In particular, the following rules should help, especially if you might submit your changes for integration into the master source.

  • Write source code in lowercase for improved readability. We have partially adopted a convention that equate token names should be in uppercase.
  • Use the standard command parser (!PARSER) rather than writing your own.
  • Use token names from include records rather than literal values where appropriate.
  • Use CRT or DISPLAY rather than PRINT unless you want the output to go to a printer.
  • QM is reasonably case independent. Try to preserve this by looking up VOC or dictionary items as typed and, if not found, by trying again in uppercase.
  • Whatever the programming purists may say, limited careful use of GOTO is fine.
  • Use meaningful label names. Numeric label names are not allowed in the master source.
  • The standard message handler should be used for all output text. Use message numbers in the range 10000 - 19999. We will change these to the final message number on integration where appropriate. Pick style messages from the ERRMSG file (and hence the Pick syntax variant of STOP and ABORT) may not be used.
  • Programs must conform to the locking rules such that all writes and deletes, including adding a new record, are covered by a suitable lock. Programs must operate correctly with the MUSTLOCK configuration parameter set to 1.
  • Programs must not rely on settings in the $BASIC.OPTIONS record for correct compilation.
  • Programs must be adequately commented that their operation can be clearly understood for maintenance purposes.

C Coding Style

  • All code returned to Ladybridge Systems for integration must be written in standard C with no compiler or platform specific extensions.
  • Where possible, use the general layout style adopted by other modules. It may be different from your personal style but a single style eases maintenance.
  • The standard message handler should be used for all output text. Use message numbers in the range 10000 - 19999. We will change these to the final message number on integration where appropriate.

File System Changes

Changes in file formats are likely to cause serious problems with cross-version compatibility. It is strongly recommended that developers intending to make such changes discuss these with Ladybridge Systems beforehand if the change might be submitted for inclusion in the standard source.


QMClient Packet Types

The QMClient interface uses packet type numbers to identify the action to be performed. There could be serious data corruptions or other effects if mismatched versions of QM and the client application are used. The chances of this can be reduced significantly if developers use packet type numbers in a separate range from standard components of QM.

Note that regardless of the machine on which the software is run, QMClient packets always use low byte first representation of numeric data.


Internal Mode

Some QMBasic operations are restricted for use in internal mode programs. An internal mode program can only be compiled on an internal mode version of QM.

The concept of internal mode was invented to protect features that should not be widely available, either because they potentially allow a user to perform undesirable actions or because the interface to the protected operation is likely to change.

Developers should respect the concept of internal mode and not just open up these features of the system to everyone.


Adding New VOC Entries

Most developments are likely to require new VOC entries. Try not to make assumptions about the VOC item name in case it clashes with a standard entry in a future release.

New keywords should be assigned numbers over 10000 as these will never be used by Ladybridge Systems. Alternatively, register your keyword with us and we will reserve a value even if we do not implement it in the standard source.


Extending The QMBasic Opcode Set

If your development requires a new opcode, there are a set of 16 opcodes (0xCFF0 to 0xCFFF) reserved for GPL developer use that will never be used in the standard source. Alternatively, create a new extended opcode set in a similar manner to the existing PREFIX opcode (0xCF).


Byte Ordering

The QM object code stream is byte order independent so that it is possible to execute code on machines with the reverse ordering. This is essential for use of compiled dictionary entries in mixed byte ordering networks. The object code header is not byte order independent but is automatically converted, if necessary, when a program is read into memory.

The file system is byte order specific and is not dynamically converted because access to any file on a remote QM server should always be via QMNet which will hide all aspects of byte ordering.

QM includes a tool, qmconv, to convert the byte ordering of a program or data file. In its normal mode of operation it takes a list of file pathnames, including wildcards, and converts these files to the byte ordering of the host machine. The -b or -l options force conversion to big or little-endian respectively, regardless of the byte ordering of the host system.