Installation

Installation

Top  Previous  Next

 

If you are going to try things out as you read this manual, the first thing we need to discuss is how to install your own version of QM. This section relates only to the commercial QM product. If you are planning to use the open source version of QM and build your own system, none of what follows in this section applies to you. Instead, you must download and build the system from its source code.

 

In this section, you will find details on how to install QM on

Windows

A USB memory stick under Windows

Linux, FreeBSD, AIX, Solaris 10, Raspberry Pi

Mac OS X

 

See Multi-Tenanting for details of how to install multiple separate versions of QM on the same server.

 

Although QM can be supplied on CD, users normally download the software from the OpenQM website, www.openqm.com, which ensures that you have the latest version of this rapidly developing product.

 

On most platforms, you can also use QM in its single user "Personal Version" mode. This is exactly the same as the commercial product but is restricted for use in non-commercial activities, typically as a learning environment, and has a low limit on the size of database file that it will support. The Personal Version comes with no support beyond any help necessary to get it installed.

 

You will probably not want to install every revision that is released. The product web site includes a "What's new in recent releases" page that can be used to help decide when an upgrade is desirable.

 

To download the software, follow the link to the download page and select the appropriate version for your platform. Right click on the Download link and select Save Target As to copy the install file to your system. If you need to move the file from the system on which it is downloaded to a different system for installation, be sure to use a binary mode copy tool.

 

If you have a commercial licence or are using an evaluation copy of QM, you can also download the AccuTerm terminal emulator by following the link from the QM download page. The activation code is included with your QM licence.

 

The installation process for QM is exactly the same for a new installation and for an upgrade. The following sections describe the process for each platform.

 

 

 

Installation on Windows

 

You must have administrator rights on the PC to install QM as it updates restricted system files. The self-extracting install file has a name of the form qm_3-4-13.exe (32-bit) or qm64_3-4-13.exe (64-bit), where the numeric components identify the release. Execute this file. The first screen confirms that you are about to install QM. Click on the Next button to continue.

 

The install process now displays the software licence. Tick the box to say that you accept the terms of this licence and click on the Next button.

 

QM can be installed in any convenient location. The default is C:\QMSYS but this can be changed. An upgrade installation will offer the directory used for the previous installation as the default.

 

Having selected the installation directory, you will be asked to specify the program group folder name in the Start menu. This defaults to QM and is probably best left unchanged.

 

You will be asked to choose between the 8-bit (ASCII) and Extended Character Set (Unicode) versions. This will depend on what languages you need to support.

 

The final step before installation commences is to select the components to be installed. The components offered are:

QM DatabaseThe QM database itself.
QM HelpThis document as a Windows help (.chm) file.
QMTermA simple terminal emulator.
QM Online DocumentationAdobe Acrobat style pdf documentation.
QMClientThe client API.

 

After the main installation has been performed, the install process displays a screen in which the authorisation data can be entered as discussed below.

 

If this is an upgrade installation, you will be asked if the VOC file should be updated in all accounts. Although this is probably a good idea, users who have access to the QM command prompt will be asked about upgrading when they enter QM if it is left until later.

 

Finally, the installer offers to show the readme file.

 

If not already present, the installation will add the bin subdirectory of the QMSYS account location to the Windows PATH environment variable.

 

After installation is complete, you may need to make changes to configuration parameters. Although the default values work well for most systems, installations with many users or a large number of database tables may require changes. You can always make further changes later.

 

The self-extracting archive file of the standard install includes the user documentation as a set of pdf files and a compiled HTML help file for use on the QM server or on other Windows clients. Individual pdf manuals and a zip file containing a browser based help package are also available on the download page.

 

The performance of disk i/o intensive applications on Windows systems is massively affected by the settings of the Windows memory usage performance options. See the QM KnowledgeBase on the openqm.com web site for more details.

 

 

 

Installation on a USB memory stick under Windows

 

This mode of installation allows you to carry a complete Windows based QM system on a USB memory stick and use it on any compatible PC without installing any software on the PC itself. The stick must comply with the USB 2 standards or later. Older USB 1 sticks cannot be used.

 

The installer will attempt to create or update a file named memstick in the top level directory of the USB device. This file contains the unique id codes for that stick and is only used during licence application, however, you should not amend this file as this may cause QM to fail at a later upgrade. If the installer is unable to create this file for any reason, the process can be done manually by running the USBCONFIG tool that can be downloaded from the OpenQM website.

 

To install QM, run the standard Windows installation program as described above, ensuring that the "USB memory device" check box is ticked and the pathname of the target device is correctly entered on the destination directory screen. The remainder of the installation process is as above. The drive letter assigned to the USB device may change each time it is inserted. This will not affect use of QM.

 

To use QM from a USB memory device:

1.Open a Command Prompt window.

2.Use CD to make the account directory on the USB device the current directory.

3.Type "\qmsys\bin\qm" to enter QM where the actual pathname will depend on where you installed the software.

 

Although the USB installation of QM is intended for single user use via the QMConsole interface activated by the process described above, it is possible to run network sessions with a USB version of QM. Because the USB installation is all about not needing to install anything on the host PC, this cannot use the QMSvc network service. Instead, a USB installation of QM includes the QMUSBSrvr network management program to allow telnet and QMClient connections. To start this, open a Command Prompt window and execute the \qmsys\bin\qmusbsrvr program from the USB device. Network connections run as the user currently logged in on the Windows system but, if QM's security features are enabled, the @LOGNAME variable will contain the user name supplied when entering QM.

 

When installing on a USB device, the QMClient.dll file is installed in the bin subdirectory of the QMSYS account instead of in the SYSTEM32 subdirectory of Windows on the hard drive. To use QMClient on a USB installation, it will be necessary either to use full pathnames for QM executable items of to ensure that the PATH environment variable includes the QMSYS\bin directory. Typically, this can be achieved by a line such as

PATH=\qmsys\bin;%PATH%

in the .bat file that is used to start QM on the USB device.

 

 

 

Installation on Linux, FreeBSD, AIX and Solaris

 

The installation is controlled by a shell script that has an embedded tar archive.

 

You must have superuser access rights to install QM as it updates restricted system files. The self-extracting install file has a name of the form:

Linuxqm_3-4-13
FreeBSDqmf_3-4-13
AIXqmr_3-4-13
Solarisqms_3-4-13
Raspberry Piqmp_3-4-13

where the numeric components identify the release. Where a 64-bit version is available, the leading part of the 64-bit installation file includes "64". Ensure that you have execute permission for this file and then execute it.

 

The installer confirms that you are about to install QM. Note that any existing installation of QM must have been shut down before installation of a new version.

 

The compressed install file is unpacked and the software licence is displayed. You must confirm that you agree with this licence to continue.

 

QM can be installed in any convenient location. The default is /usr/qmsys but this can be changed in response to a prompt from the installer. An alternative default location can be set using the optional QMSYS environment variable.

 

After the main installation has been performed, the install process displays a screen in which the authorisation data can be entered as discussed below. If this screen appears incorrectly formatted, check that the operating system TERM variable references the correct terminal type and repeat the install.

 

If this is an upgrade installation, you will be asked if the VOC file  should be updated in all accounts. Although this is probably a good idea, users will be asked about upgrading when they enter QM if it is left until later.

 

The installation process does not add QM to the operating system PATH environment variable. Depending on how you plan to operate your system it may be worth adding the bin subdirectory of the QMSYS account to the PATH variable.

 

 

The self-extracting archive file of the standard install does not include the user documentation. This can be downloaded separately from the openqm.com web site as individual pdf manuals, a zip file of all the manuals, a compiled HTML help file for use on Windows clients, or a zip file containing a browser based help package for use on all platforms.

 

The default password encryption mode of Solaris is weak and not accepted by network connections to QM. The encryption mode can be changed by editing the /etc/security/policy.conf file to uncomment the line that reads

CRYPT_ALGORITHMS_DEPRICATE=__unix__

and change the CRYPT_DEFAULT line to be

CRYPT_DEFAULT=2a

After making this change, any user who will directly access QM over a network must reset their password.

 

 

Some Unix systems (e.g. AIX) have a kernel configuration parameter that sets the limit on the number of files that may be opened simultaneously by one process. The name of this parameter differs across operating systems but is often NOFILES. QM will automatically handle reaching this limit but there will be a performance degradation caused by needing to close and reopen files to stay within the limit. There may also be a system wide file limit kernel parameter, often called NFILE which also needs to be set carefully.

 

 

 

Installation on an Intel Mac

 

The Mac install is performed using a variant of the Linux install process described above.

 

The self-extracting install file has a name of the form qmmi_3-4-13, where the numeric components identify the release.

 

Open a terminal window and set the terminal type to vt102.

 

Execute the downloaded file using sudo:

sudo bash qmmi_3-4-13

 

The installer confirms that you are about to install QM. Note that any existing installation of QM must have been shut down before installation of a new version.

 

The compressed install file is unpacked and the software licence is displayed. You must confirm that you agree with this licence to continue.

 

QM can be installed in any convenient location. The default is /usr/qmsys but Mac users may prefer to use /var/qmsys. The installer will prompt for the pathname to be used. An alternative default can be set using the QMSYS environment variable.

 

After the main installation has been performed, the install process displays a screen in which the authorisation data can be entered as discussed below.

 

If this is an upgrade installation, you will be asked if the VOC file  should be updated in all accounts. Although this is probably a good idea, users will be asked about upgrading when they enter QM if it is left until later.

 

From OS X 10.6, the installation process adds the pathname of the QM binaries to the /etc/paths.d directory which is used to construct the PATH environment variable on login. This will take effect from the next login. On older versions of the operating system, the installer does not add QM to the operating system PATH environment variable. Depending on how you plan to operate your system it may be worth adding the bin subdirectory of the QMSYS account to the PATH variable in a profile script.

 

The self-extracting archive file of the standard install does not include the user documentation. This must be downloaded separately from the web site as individual pdf manuals, a zip file of all the manuals, a compiled HTML help file for use on Windows clients or a zip file containing a browser based help package for use on all platforms.

 

 

 

Licence Authorisation

 

QM will request licence authorisation data entry as part of the installation process described above. A new licence can also be applied at any time by use of the UPDATE.LICENCE command in the QMSYS account or from the operating system command prompt by executing QM with the -L option (case insensitive).

 

clip0002

 

You need to enter the details in the boxes surrounded by square brackets as given on your licence paperwork. If you have been supplied with a ten digit licence number, enter the following details:

Licence numberThe unique ten digit number identifying this licence.
Max usersThe maximum number of concurrent processes including Windows GUI processes such as QMClient.
Expiry dateThe last date on which this licence is valid. Leave blank for a permanent licence.
Authorisation codeA case insensitive sequence required to validate your licence details.
Security numberA number required to further validate your licence details.
Site textThis must be entered exactly as on your licence document.

 

Alternatively, if you have been supplied with a profile licence code (two groups of four letters), ensure that the system being licensed is connected to the internet and enter this code in the licence number field. Your system will connect to the OpenQM licensing server to fetch the licence details. You may be asked to enter the user limit or the site text.

 

 

The system id is used to tie a licence to a specific machine (or USB memory device for a Windows USB installation). The normal licensing procedure starts with a short term licence that will install on any system. During the life of this licence, you should supply the system id to your QM reselller who will then send you the final permanent licence.

 

If you subsequently move the QM software to a new system, you will need to arrange with your dealer to receive a new licence. There will normally be no charge for this so long as you undertake to remove the old installation. Your licence document will also show how to obtain a short term emergency licence if you need to move your QM installation to a new system at a time when your reseller is unavailable.

 

When installing a new release of QM over an existing version, the previous licence details are displayed as the defaults. To preserve these either press the return key in each field in turn or use ctrl-X to exit from the screen.

 

When updating the licence on a system that uses data encryption, the install process will ask for entry of the master key if the licence number or system id code has changed.

 

 

 

Post-Installation Questions

 

On completion of a new installation (not an upgrade), the installer will ask whether QM's internal security system is to be enabled. For more information on this topic, see Application Level Security. The setting of this option can be amended later using the SECURITY command if necessary.

 

 

 

Setting Configuration Parameters

 

After a new installation, you may need to set the value of some configuration parameters. In particular, the values of NUMFILES (the maximum number of files that can be open at the application level simultaneously) and NUMLOCKS (the maximum number of concurrent record locks) need to be appropriate to your use of the system.

 

Many operating systems have a limit on the number of files that can be open simultaneously either per-process or system wide. It may be necessary to increase this to match the setting of the NUMFILES parameter. Note that opening a dynamic hashed file in QM requires two operating system files to be opened. Each alternate key index adds a further operating system file.

 

 

 

Upgrades

 

A commercial QM licence has an "upgrade entitlement period" during which you are free to download and install new versions. Prior to 1 January 2015, this period was initially either one or ten years but could be extended. From 1 January 2015, the upgrade period is linked to the maintenance agreement expiry date. In either case, after the upgrade period has expired, versions of QM released before the expiry date may still be installed.

 

To install an upgrade:

1.Download the software from the OpenQM web site.

2.All QM users must log off.

3.On Windows, use the QM Network Control tool from the QM program group to shutdown the QMSvc service. On other platforms, use qm -stop to shutdown QM.

4.Follow the installation process described above.

 

Several files within the QMSYS account will be updated but all user accounts will remain unchanged except for optional updating of the VOC file for any new items. Note that the NEWVOC file which contains the items to go into the VOC of a new account is completely overwritten by an upgrade. Where there are site specific items that should be added to the VOC of all new accounts, it is recommended that a file named NEWVOC.MODS is created in the QMSYS account. The installer and the CREATE.ACCOUNT and UPDATE.ACCOUNT commands look for this file and, if found, copy its content into the account VOC.

 

 

Compatibility with Other Environments

 

The various multivalue database products implement some features differently. This results in syntactic or semantic differences in some commands or programming statements. If you are migrating an application to QM from another multivalue product, there are facilities to give closer compatibility without needing to make extensive modifications to the application.

 

The OPTION command can be used to enable features that are mostly concerned with the command environment. This command is typically embedded in the LOGIN paragraph that runs automatically when a user enters the system.

 

The QMBasic $MODE directive enables features that affect programming language syntax or semantics. Although developers could put this directive into every program, it is usually simpler to create a record named $BASIC.OPTIONS in the program file to apply mode settings (and other features) to every program in that file. Alternatively, this record can be put in the VOC file from where it will affect all programs in files that do not have their own $BASIC.OPTIONS record. For more details of this record, see the BASIC command.

 

It is recommended that after migration to QM, developers should spend some time reading the documentation to discover features of QM that were not in the previous environment so that they can take advantage of these.