2 Installation and licensing

2.1 Installing IQML

IQML requires the following in order to work:

An active account at DTN IQFeed

An installation of the IQFeed client (IQConnect)

An installation of Matlab R2008a or a newer release

On older Matlab releases, some IQML functionality may still be available. Contact info@IQML.net or info@UndocumentedMatlab.com for details.

Installing IQML is simple:

Read IQML’s license agreement.2 This is required even for the trial version of IQML. If you do not accept the agreement you cannot use IQML.

Download IQML.zip3 to a local folder (e.g.: C:\IQML\).

Unzip the downloaded IQML.zip file in this local folder.

Add the local folder to your Matlab path using the path tool (run the Matlab pathtool command, or in the Matlab Desktop’s toolstrip, click HOME / ENVIRONMENT / Set path… and save). The folder needs to be in your Matlab path whenever you run IQML.

If you are running the Production (non-trial) version of IQML, you will need to activate your license at this point. When you purchase your license you will be given specific instructions for this. See §2.2 below for licensing details.

Ensure that the IQFeed client is working and can be used to log-in to IQFeed.4

You can now run IQML within Matlab. To verify that IQML is properly installed, retrieve the latest IQFeed server time, as follows (see §9.2 below):5

>> t = IQML('time');

You can query the installed version using IQML’s 'version' action, as follows:

>> disp(IQML('version'))
Version: 1.0
Release: '23-Feb-2018'
License: 'Professional'
Expiry: '16-Jun-2018'

Once the IQML product is installed, you will be notified in the Matlab console (Command Window) whenever there is a new version available. You can always update your installation to the latest version, as follows:

>> IQML('update')
Downloading
the latest IQML version from http://IQML.net/files/IQML.zip
into C:\IQML\...
Download complete - installing...
Installation of the latest IQML version is now complete.

2.2 Licensing and activation

IQML’s license uses an activation that is specific to the installed computer. This uses a unique fingerprint hash-code that is reported by the Operating System, which includes the Windows ID (on Windows systems), computer name, and the list of hardware MAC addresses used by the computer.

Once the computer’s license is activated, the activation key is stored on the IQML webserver. This activation key automatically validates online whenever IQML connects to IQFeed (i.e., at the beginning of an IQFeed session), and once every few hours while it is connected. Validating the license online only takes a second or two. Since it is only done at the initial connection to the IQFeed client and once every few hours, it does not affect IQML’s run-time performance. If you have a special concern regarding the online activation, please contact us for clarifications.

A corollary of the computer fingerprint is that whenever you modify components that affect the fingerprint, IQML will stop working. This could happen if you reinstall the operating system (OS), modify the computer name, change network adapters (e.g., switch between wifi/cellular/wired connection, or use a new USB networking device), modify MAC addresses, or use software that creates dynamic MACs. In such cases, you might see an error message such as the following when you try to use IQML:

Error using IQML
IQML is not activated on this computer.

Some additional information may be presented to help you diagnose the problem.

To fix such cases, simply revert back to the original hardware/networking configuration, and then IQML will resume working. If you wish to make the configuration change permanent, you can contact us for an activation switch to the new configuration (see the following section (§2.3) for details).

Computer fingerprints are typically stable, and are not supposed to change dynamically. However, some software programs (especially on MacOS, but also sometimes on Windows) create dynamic MAC addresses and/or dynamically modify the computer name (hostname). This may then be reflected in the OS-reported fingerprint, possibly causing IQML to stop working. The solution is to find a way to keep the fingerprint components static, with the same values as the activated fingerprint.6 You can determine the nature of the OS-reported fingerprint as follows:

>> IQML('license', 'debug',1)

Using this command, you can determine which fingerprint component has changed and take the appropriate action to fix it so that the reported fingerprint will match the activated fingerprint. If you decide that the fingerprint changes are permanent, contact us to change the activated fingerprint (see §2.3 below).

A short time before you license term is over, you will start to see a notification message in your Matlab console (Command Window) alerting you about this:

*** Your IQML license will expire in 3 days (10-Mar-2018).
*** To extend your license please email info@IQML.net

This informational message will only appear during the initial connection to IQFeed, so it will not affect your regular trading session.

When the license term is over, IQML will stop working and display an error message:

*** Your IQML license has expired on 10-Mar-2018.
*** To extend your license please email info@IQML.net

You can always renew or extend your license using the payment links on http://IQML.net or https://UndocumentedMatlab.com/IQML. If you wish to be independent of such renewals, you can select a discounted long-term license.

You can query the installed version using IQML’s 'version' action, as follows:

>> data = IQML('version')
data =
Version: 1.0
Release: '23-Feb-2018'
License: 'Professional'
Expiry: '16-Jun-2018'

Multiple IQML license options are available for purchase. Longer license terms are naturally more cost-effective than shorter ones. At the end of any license term you can decide to renew the same term, or purchase any other term:

2- or 4-months license: these short-term licenses can be repeatedly renewed, for product evaluation or program development beyond the free trial.

1-year license: this is the standard, most popular license term.

Multi-year license: 2-year, 3-year or 5-year license terms will work for a longer duration than the standard license year without requiring a renewal, as long as IQFeed continues to provide its API service and your environment remains stable.

Volume (multi-computer) license: the same license as for a single computer, but when you purchase multiple licenses at once, you get a volume discount.

Site license: enables to run IQML on an unlimited number of computers within the same Windows Domain. This license does not require end-user activation, only a single centralized activation. It supports cloud deployment, where computer hardware fingerprints (but not the domain) often change.

Deployment (compiled or OEM) license: enables to use IQML within a compiled program that runs on an unlimited number of computers, in any site or domain. This license does not require any end-user activation, only a single centralized activation of the parent executable to which the license is tied.

Source-code license: unlimited in duration, can be installed on an unlimited number of computers within the organization, and requires no activation. This license requires signing a dedicated NDA (non-disclosure agreement).

Bundle license: a discounted bundle of licenses for IQML and IB-Matlab (the InteractiveBrokers-Matlab connector). The combination of IB+IQFeed+Matlab is quite common in trading systems.

Each of these licenses can be selected in one of two variants: Standard and Pro. The Standard license contains most IQFeed functionality; the Pro license provides access to the full set of IQFeed data. A detailed comparison is provided in §3.1, §3.4 below.

2.3 Switching activated computers

You can switch the IQML license activation between computers or computer hardware configurations (i.e., fingerprint hash-code) whenever you purchase a license renewal. For license terms of 1 year or longer, up to 2 activation switches per year are also included, at no extra cost. A handling fee will be incurred for other re-activations.

In order to change the activation fingerprint, simply email us the new configuration’s fingerprint and we will make the switch on IQML’s activation server.

warningActivation switches can take up to two business days to process, but typically complete within a few hours during European business hours. You will receive a confirmation email when the activation switch is complete.

2.4 Updating the installed version

Once IQML is installed, you will be notified in the Matlab console (Command Window) whenever a new version is available. An example of such a notification is:

>> IQML(...) % some IQML command

A newer version of IQML (2.08) is available. Updates include:

2.08 (2018-10-28)
- Enabled parallelized historic data queries having date/time range

To display the latest online User Guide, click here.

To install the new version, click here, or run IQML('update'), or download IQML.zip from http://IQML.net/files/IQML.zip and then unzip it in C:\IQML.

You can decide to ignore this notification and keep using your existing IQML version, or to follow the notification’s advice and update your version – the choice is yours.

You can update IQML to the latest version any time during the license term, as follows:

>> IQML('update')
Downloading the latest IQML version from
http://IQML.net/files/IQML.zip
into C:\IQML\...
Download complete - installing...
Installation of the latest IQML version is now complete.

This update process preserves the current version as backup, so you could revert to it later (see below). Following the update, you can verify the new release’s version:

>> data = IQML('version')
data =
Version: 1.9
Release: '16-Apr-2018'
License: 'Professional'
Expiry: '16-Jun-2018'

After installing the latest version, if you discover that this version does not work well, you can always revert back to a previous version:

run IQML('revert'), which replaces the current version with a previous version that was preserved in the last IQML('update'), or:

download http://IQML.net/files/IQML_previous.zip, unzip this file in your IQML folder, then restart Matlab. The current version is not preserved as backup, so you will not be able to revert to it later by running IQML('revert').

After the version update (by either methods), restart Matlab, and run data=IQML('version') to verify the new version. Then email us to let us know why you reverted, so that we could correct the problem in upcoming versions.


2 http://IQML.net/files/IQML_License_Agreement.pdf or https://UndocumentedMatlab.com/IQML/files/IQML_License_Agreement.pdf

3 http://IQML.net/files/IQML.zip or https://UndocumentedMatlab.com/IQML/files/IQML.zip

4 IQConnect.exe on Windows, IQFeed application on MacOS. or ran as a Windows app on Mac/Linux using Parallels/Wine. Note: some MacOS users have reported problems with the “native” app (which is basically just a bottled Wine installation) compared to a standard Wine install. This is a pure IQFeed/Mac issue, and not an IQML one; using Wine seems to solve it. In any case, only the IQFeed client needs to run under Wine - Matlab itself can run natively, but note that certain Windows-only functionality (such as discussed in §9.5 and §12.2) will not work in native mode, only under Parallels/Wine.

5 In some cases, you may need (or want) to specify the IQFeed Username,Password for the initial connection – see §9.1 below

6 For example, the computer’s name can be set using the OS hostname command, or the following method on Mac OS: https://knowledge.autodesk.com/support/smoke/learn-explore/caas/sfdcarticles/sfdcarticles/Setting-the-Mac-hostname-or-computer-name-from-the-terminal.html