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@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 folder to Matlab’s path by running Matlab’s pathtool command, or via HOMEàENVIRONMENTàSet path… in Matlab Desktop’s toolstrip. The folder needs to be in Matlab’s 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 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):5

>> t = IQML('time')

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

>> disp(IQML('version'))
Version: 2.55
Release: '10-May-2021'
License: 'Professional'
Expiry: '31-Dec-2022'
Filepath: 'C:\IQML\IQML.p'

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')
the latest IQML version from http://undocumentedmatlab.com
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 reported by the Operating System, that includes the Windows ID (on Windows systems), computer name, disk ID, and list of hardware MAC addresses.

Once the computer’s license is activated, the activation key is stored on the IQML’s webserver and validated online when 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 only takes 1-2 secs, so it does not affect IQML’s run-time performance. If you have any concern regarding the online activation, please contact us for clarifications.

Since activation depends on the computer fingerprint, IQML will stop working if you modify any component that affects the fingerprint. This could happen if you reinstall the operating system (OS); change hard disk, computer name, or 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 use IQML:

Error using IQML
IQML is not activated on this computer.

Some additional information may be displayed 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 in order to switch the activation 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).

To check whether your license is activated, run the following command in Matlab:

>> isActivated = IQML('validate');

This will return true if the license is activated, and an error if not. Instead of an error event, you can request the error message as a string, using the following command:

>> [isActivated, errMsg] = IQML('validate');

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@undocumentedmatlab.com

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@undocumentedmatlab.com

You can always renew/extend a license on https://UndocumentedMatlab.com/IQML.

To query the installed version, use IQML’s 'version' action, as follows:

>> data = IQML('version')
data =
Version: 2.55
Release: '10-May-2021'
License: 'Professional'
Expiry: '31-Dec-2022'
Filepath: 'C:\IQML\IQML.p'

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-months or 6-months license: these short-term licenses can be repeatedly renewed beyond the free trial, for product evaluation or program development.

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

Multi-year license: these discounted long-term licenses 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 Matlab+IQFeed+IB 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 and §3.4.

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.32) is available. Updates include:

2.32 (2019-12-16)
- [2.4] Modified the hyperlinks in the new-version message
- [5.*] Improved processing speed of historic data queries

where [#.#] indicates the corresponding sections in the User Guide.

To install the new version, run IQML('update'), or download IQML.zip from http://undocumentedmatlab.com/files/IQML/IQML.zip and 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://undocumentedmatlab.com
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: 2.55
Release: '10-May-2021'
License: 'Professional'
Expiry: '31-Dec-2022'
Filepath: 'C:\IQML\IQML.p'

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://UndocumentedMatlab.com/files/IQML/IQML_previous.zip, unzip this file in your IQML folder, then restart Matlab. The current version is not preserved, so you will not be able to revert to it later by running IQML('revert').

After a version update by any method, 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 https://UndocumentedMatlab.com/files/IQML/IQML_License_Agreement.pdf

3 https://UndocumentedMatlab.com/files/IQML/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

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