9 Connection, administration and other special commands

9.1 Connecting & disconnecting from IQFeed

When using IQML, there is no need to worry about connecting or disconnecting from IQFeed – IQML handles these activities automatically, without requiring user intervention. The user only needs to ensure that IQFeed is active and logged-in when the IQML command is invoked in Matlab.

IQML does not require any special configuration when connecting to IQFeed. It uses whatever setting was previously set in the DTN IQConnect client application. You might be prompted to enter a username/password, if IQConnect was not set up to automatically connect using saved login/password information:

???

In addition to entering the login credentials in the client window, you can also specify them programmatically. This could be useful when you have several IQFeed accounts and wish to switch between them programmatically, or if you use IQFeed’s non-Windows client installer on MacOs (which prevents user-entry in the login window):

>> IQML('time', 'Username','123456-1', 'Password','OpenSesame')

Note that the Username and Password parameters must be specified together, and that they are only meaningful in the first IQML command that starts the connection. If the Username and Password parameters are specified after a connection to IQFeed has been established, they will be ignored for the current connection, but stored in IQFeed’s registry for subsequent connections (see §9.5 below).

If you enter an invalid set of Username/Password, an error message will be thrown. A different error will be thrown if IQML fails to connect to IQFeed within 10 seconds.

IQML can connect to a running IQFeed client, that was already started by another process on the current computer (e.g. charting app or another Matlab process that runs IQML), even without Username and Password in the initial IQML connection. IQML will bypass login, connecting directly to the client process.

IQML typically uses the latest API features supported by your installed IQFeed client (IQConnect). For example, if you use client version 6.0.1.1, IQML will use IQFeed communication protocol 6.0, and you will not have access to features of protocol 6.1.135 Once you install a newer IQFeed client, IQML will automatically detect this and use a newer protocol number, as determined by the new client version. For debugging purposes, you can override Protocol to a version older than your installed client. For example, with a 6.0.1.1 client, you can set Protocol to 5.2, but not to 6.1 or newer:

>> IQML(..., 'Protocol',6.2)

Warning: Your IQFeed client (version 6.0.1.1) does not support Protocol 6.1 - using Protocol 6.0 instead
(Type "warning off IQML:UnsupportedProtocol" to suppress this warning.)

You will be able to retrieve information in Matlab as soon as IQML connects to the IQFeed client and [if necessary] the client finishes the login process and synchronizes with the IQFeed servers. This process typically takes a few short seconds.

The following parameters affect the initial connection to IQFeed:

Parameter

Data type

Default

Description

Username

string

(none)

Used to launch and login into IQConnect

Password

string

(none)

Used to launch and login into IQConnect

Protocol

number

installed client’s version

IQFeed API protocol that should be used. You can set any protocol value supported by your IQConnect client version. For example, client 6.0.1.1 supports protocols 5.2 and 6.0 (this client’s default), but not 6.1.

By default, IQML uses the following TCP ports to connect to IQFeed’s client:

5009 – Level1Port – used for Level 1 queries/msgs (quotes, fundamentals)

9100 LookupPort used for historical, news and lookup queries/messages

9200 – Level2Port – used for Level II (market-depth) queries/messages

9300 – AdminPort – used for administrative queries/messages (stats etc.)

9400 – DerivativePort – used for interval-bars queries/messages

60020 – LoginPort – used for login authentication

If any of these ports are already used by any other process at the time that IQFeed’s client application (IQConnect) starts, it will not be able to communicate with IQML via these ports. IQML automatically tries to detect and report such cases, for example:

>> data = IQML('history', 'Symbol','IBM')

Error using IQML
Port #9100 is already used by process #12345 (SomeProcess.exe) and cannot be used by IQFeed. Run IQML('registry') to set a different value for LookupPort.

You can solve such port conflicts using any of the following methods:

Stop/uninstall the other process (SomeProcess.exe in the example above)

Modify the other process’s settings to use different ports, so that they will not conflict with IQFeed (this is rarely possible)

Modify IQFeed’s registry settings to use a different port, which is not used by any other process (see §9.5 below). If you choose this option, you will need to fix the port again whenever you re-install the IQFeed client (for example, whenever you update the client to a newer version), because the client’s installation process resets the port values back to their default values.

warningAfter you resolve the problem using one of these alternatives, restart IQFeed’s IQConnect client and then retry the IQML command. An IQConnect restart is necessary since IQConnect reads the registry values and sets the ports only when it starts.

In some cases, users may wish to disrupt a live connection. You can disconnect from IQFeed using IQML’s 'disconnect' action, which has no settable parameters:

>> IQML('disconnect')

This command disconnects IQML from the IQFeed client. If IQML was the only application that was connected to the client, then the client will silently exit after several seconds, unless a new IQFeed connection is established during this time.

There is no need for a corresponding connect action, because connection is automatically (re-)established whenever this is required by a new IQML command.

IQML and IQConnect automatically try to recover from connection losses during normal operation. You may see in the Matlab console one or more IQConnect error messages such as the following, which indicate such a connection loss:

20180410 20:03:06.371 Level1 server disconnected!

or:

20180410 20:03:57.934 Unable to connect to L2IP server. Error Code: 10051 Error Msg: A socket operation was attempted to an unreachable network.

or:

20180410 20:03:57.934 Unable to connect to L2IP server. Error Code: 10065 Error Msg: A socket operation was attempted to an unreachable host.

or:

20180410 20:03:57.934 Unable to connect to L2IP server. Error Code: 10053 Error Msg: An established connection was aborted by the software in your host machine.

or:

20180410 20:03:57.934 Unable to connect to L2IP server. Error Code: 10060 Error Msg: A connection attempt failed because the connected party did not properly respond after a period of time

You can safely ignore such messages in most cases, since IQConnect will automatically re-establish connection with IQFeed’s servers as soon as they become accessible again, and show an appropriate informational message in Matlab’s console:

20180410 20:04:16.497 Level1 server is connected

In some cases, users may wish to actively re-connect (disconnect and then connect) to IQFeed. This can be done with the 'reconnect' action (no settable parameters):

>> IQML('reconnect')

warningNote that after reconnecting to IQFeed, you will need to request any and all streaming data again (see §6), since IQFeed resets data streaming after a client disconnect.

9.2 Server time

You can request the latest IQFeed server time using the 'time' action:

>> data = IQML('time')
data =
latestEventDatenum: 737114.660205451
latestEventTimeStamp: '20180223 15:50:41'
latestServerDatenum: 737114.368518519
latestServerTimestamp: '20180223 08:50:40'

The returned data struct includes the following data fields:

latestEventDatenum – a Matlab numeric datenum value that corresponds to the local time in which the very latest message has arrived from IQFeed.

latestEventTimeStamp – a human-readable format of latestEventDatenum

latestServerDatenum – a Matlab numeric datenum value that corresponds to the latest server time that was received from IQFeed.

latestServerTimeStamp – a human-readable format of latestServerDatenum

Note that the server time may be off by up to a full second from the current time, depending on when the last timestamp message was received from IQFeed. IQFeed sends server time messages once every second, so latestServerDatenum lags by 0.5 secs behind the current time on average.

Similarly, latestEventDatenum reports the time at which the last message was received from IQFeed. This message could be a timestamp message, or any other data message. For this reason, the lag here is typically much lower than the lag of latestServerDatenum.

The 'time' action has no settable properties.

9.3 Client stats

You can retrieve the updated IQFeed connection traffic stats using the 'stats' action:

>> data = IQML('stats')
data =
ServerIP: '66.112.148.226'
ServerPort: 60002
MaxSymbols: 1300
NumOfStreamingSymbols: 0
NumOfClientsConnected: 3
SecondsSinceLastUpdate: 1
NumOfReconnections: 0
NumOfAttemptedReconnections: 0
StartTime: 'Mar 07 11:03AM'
MarketTime: 'Mar 07 04:34AM'
ConnectionStatus: 'Connected'
IQFeedVersion: '5.2.7.0'
LoginID: '123456-1'
TotalKBsRecv: 42.98
KBsRecvLastSecond: 0.02
AvgKBsPerSecRecv: 0.02
TotalKBsSent: 361.62
KBsSentLastSecond: 0.22
AvgKBsPerSecSent: 0.19
Exchanges: {1×16 cell}
ServerVersion: '6.0.0.5'
ServiceType: 'real_time'

The returned data struct includes the following data fields:136

ServerIP – IP address of the least loaded IQFeed Quote Server

ServerPort – Port number for least loaded IQFeed Quote Server

MaxSymbols – The maximum # of symbols that can be streamed simultaneously

NumOfStreamingSymbols – The # of symbols that are currently being streamed

NumOfClientsConnected – The # of clients that are currently connected

SecondsSinceLastUpdate – The # of seconds since the last update from the Quote Server

NumOfReconnections – The # of times that IQFeed successfully reconnected

NumOfAttemptedReconnections – The # of times that IQFeed has attempted to reconnect, but failed

StartTime – Time of latest connection/reconnection to IQFeed (local timezone)

MarketTime – Current time of the market (market’s time-zone)

ConnectionStatus – Represents whether IQFeed is connected or not

IQFeedVersion – Represents the version of IQFeed that is running

LoginID – The Login ID that is currently logged into IQFeed

TotalKBsRecv – Total # of Kilobytes received by IQFeed from IQML (i.e., IQML commands/requests to IQFeed). Found in the “Internet Bandwidth” section of the IQConnection Manager. Formula: total bytes received / 1024

KBsRecvLastSecond – Found in the “Internet Bandwidth” section of the IQConnection Manager. Formula: bytes received in the past second / 1024

AvgKBsPerSecRecv – Found in the “Internet Bandwidth” section of the IQConnection Manager. Formula: total KB's received / total seconds

TotalKBsSent – Total # of Kilobytes sent from IQFeed to IQML (i.e., IQFeed messages to IQML). Found in the “Local Bandwidth” section of the IQConnection Manager. Formula: total bytes sent / 1024

KBsSentLastSecond – Found in the “Local Bandwidth” section of the IQConnection Manager. Formula: bytes sent in the past second / 1024

AvgKBsPerSecSent – Found in the “Local Bandwidth” section of the IQConnection Manager. Formula: total KB's sent / total seconds.

Exchanges – The list of exchanges for which this IQFeed account is subscribed

ServerVersion – The current version of IQFeed that the server supports. This is always the same or higher than your locally-installed IQFeedVersion.

ServiceType – Type of data provided for this account (delayed or real-time)

The 'stats' action has a single settable property: AddPortStats (default=0). If you set this property to 1 or true, then additional stats will be returned, with extra information on the connected data channels/ports (see the highlighted fields below):

>> data = IQML('stats', 'AddPortStats',1)
data =
ServerIP: '66.112.148.224'
ServerPort: 60005
MaxSymbols: 1300
NumOfStreamingSymbols: 0
NumOfClientsConnected: 4
SecondsSinceLastUpdate: 0
NumOfReconnections: 0
NumOfAttemptedReconnections: 0
StartTime: 'Apr 01 8:21PM'
MarketTime: 'Apr 01 02:12PM'
ConnectionStatus: 'Connected'
IQFeedVersion: '5.2.7.0'
LoginID: '464720-1'
TotalKBsRecv: 69.44
KBsRecvLastSecond: 0.04
AvgKBsPerSecRecv: 0.02
TotalKBsSent: 1470.32
KBsSentLastSecond: 0.47
AvgKBsPerSecSent: 0.48
Exchanges: {1×16 cell}
ServerVersion: '6.0.0.5'
ServiceType: 'real_time'
Level2: [1×1 struct]
Level2SymbolsWatched: 2
Lookup: [1×1 struct]
RegionalSymbolsWatched: 2
Admin: [1×1 struct]
Level1: [1×1 struct]
Level1SymbolsWatched: 0

>> data.Level1
ans =
ConnectTime: '20180401 202111'
KBsReceived: 0.74
KBsSent: 70.58
KBsQueued: 0

>> data.Admin
ans =
ConnectTime: '20180401 202108'
KBsReceived: 0.43
KBsSent: 1516.74
KBsQueued: 0

Note that it might take a few seconds for the additional port stats to arrive after the initial command. If you don’t see the expected results immediately, simply re-query them after 1-2 secs.

The returned data structs include the following data fields, separately for each data channel (port):137

ConnectTime – Timestamp when this channel to IQFeed was first opened

KBsReceived – Total # of Kilobytes sent from IQML to IQFeed via this channel (requests for data queries etc.).

KBsSent – Total # of Kilobytes sent from IQFeed to IQML via this channel. This data transfer is typically much larger than KBsReceived – this is normal and does not indicate a problem.

KBsQueued – Total # of Kilobytes waiting in IQConnect to be sent to IQML via this channel for processing. This value should typically be 0 (zero) – a consistent non-zero value indicates that the Matlab program is unable to keep up with the inflow of data from IQFeed, perhaps due to a high load on the computer, or some heavy processing of the incoming data. If the value increases over time, Matlab and your computer will eventually freeze and become non-responsive, requiring a hard reset. See §3.6 for ways to speed-up the processing time, in order to get KBsQueued back to 0.

9.4 Sending a custom command to IQFeed

You can send any custom command to IQFeed’s API, using the 'command' action. For example, to send the 'S,TIMESTAMPSOFF' command,138 which stops IQFeed from sending server timestamp messages every second:

>> IQML('command', 'String','S,TIMESTAMPSOFF')

IQFeed expects that users send commands to its API via specific channels (“ports”). Each command is typically accepted only by the port for which it is defined. For example, the 'S,TIMESTAMPSOFF' command is defined for the Level1 port,139 whereas the 'S,CLIENTSTATS OFF' command (which stops the IQFeed server from streaming client stats messages) is defined for the Admin port.140 When you use IQML’s standard actions you do not need to worry about which port handles which command – this is automatically handled by IQML. But when you send a custom command to IQFeed, you need to specify the port, if it is different from the default ('Level1'). In this specific example:

>> IQML('command', 'String','S,CLIENTSTATS OFF', 'PortName','Admin')

IQFeed is very picky about the spelling of the commands, including spaces and casing. If the spelling is not exactly right, the command will be rejected by IQFeed, possibly even without an error message. Unfortunately, IQFeed are not entirely consistent in the format of the various commands. For example, the 'S,TIMESTAMPSOFF' command has no space, whereas the 'S,CLIENTSTATS OFF' command does have a space; also, both of these commands are all-uppercase, yet the 'S,SET AUTOCONNECT,On' Admin command spells On/Off with lowercase letters (and uses a comma instead of a second space).

In some cases, the command that is sent to IQFeed may result in data messages that will be sent back from IQFeed, which should be received and processed. To do this, you can set the ProcessFunc property to a custom callback function that will handle these messages (see §10).

The following properties can be specified in IQML with the 'command' action:

Parameter

Data type

Default

Description

String

string or cell-array of strings

(none)

The IQFeed command string(s).

PortName

string

'Level1'

The IQFeed port that will process the command(s). Must be one of the following:

'Level1' (default)

'Level2'

'Lookup'

'Admin'

ProcessFunc

function handle

[]

Custom user callback function to process incoming IQFeed data messages (see §10).

9.5 Modifying IQFeed’s registry settings

IQFeed stores its settings as keys in the HKEY_CURRENT_USER\Software\DTN\ path of the Windows registry. Most of the important setting keys that a user might want to modify are located within HKEY_CURRENT_USER\Software\DTN\IQFeed\Startup\. These registry keys can be reviewed and modified using Window’s built-in Registry Editor (regedit.exe) utility. As a convenient method to open the Registry Editor at the correct path, use the IQML 'registry' action, which has no settable parameters:141

>> IQML('registry')

???

IQFeed’s key names are generally self-explanatory. In most cases you should leave the settings unchanged. Some circumstances where you might want to modify certain keys are discussed in §9.1 and §12.2. Key values can be modified by right-clicking the key name and selecting “Modify…”:

???

???

warningBe EXTREMELY careful when editing the Windows registry: if you make a mistake it could disable not only a specific program, but possibly even Windows itself, rendering the computer useless. Never delete or rename keys, only modify their value. If you are unsure which registry key to modify and how, ask DTN’s technical support.


135 For example, historic market summary data and scanning (§5.6)

136 http://iqfeed.net/dev/api/docs/AdminSystemMessages.cfm

137 See §9.1 for a description of IQFeed’s data channels (ports)

138 http://iqfeed.net/dev/api/docs/Level1viaTCPIP.cfm

139 http://iqfeed.net/dev/api/docs/Level1viaTCPIP.cfm

140 http://iqfeed.net/dev/api/docs/AdminviaTCPIP.cfm

141 Note: running Windows Registry Editor requires local computer Administrator priviledges (or elevation).
In Mac/Linux, IQML('registry') will naturally work only when Matlab runs under Parallels/Wine, not in native mode.