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).
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.
Once IQML connects to IQFeed, it remains connected via IQFeed’s client (IQConnect) as long as the user does not exit the client application, or connects to IQFeed from another computer (this automatically closes the client on the previous computer, since exchange regulations do not allow using IQFeed on multiple computers concurrently).
IQML typically uses the latest API features supported by your installed IQFeed client. 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.159 If you install a newer IQFeed client, IQML will automatically detect this and use a newer protocol, 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 or 6.0, but not to 6.1 or newer:
>> IQML(..., 'Protocol',6.1)
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.160 IQML tries to automatically detect such port conflicts, 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 resolve such port conflicts using any of the following methods:
Stop/uninstall the other process (SomeProcess.exe in this example)
Modify the other process’s settings to use different ports, so that they will not conflict with IQFeed (this is rarely possible, but is preferable when possible)
Modify IQFeed’s registry settings to use a different port, which is not used by any other process (see §9.5). 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.
After 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.
You can close a live connection to IQFeed using the 'disconnect' action:
>> IQML('disconnect')
This command disconnects IQML from the IQFeed client (IQConnect). 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. If IQConnect is not active, the 'disconnect' action is silently ignored (no error).
There is no need for a corresponding 'connect' action, because IQFeed 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
You can actively disconnect and then connect to IQFeed using the 'reconnect' action:
>> IQML('reconnect')
The 'reconnect' action accepts an optional input parameter of Timeout (default value: 8 [secs]), which controls the pause duration between disconnecting IQML from IQFeed and sending a termination signal to the IQConnect process, and reconnecting to IQFeed again. The default pause of 8 secs allows IQConnect enough time (in most cases) to properly terminate before IQML reconnects – this ensures a clean “restart” of the IQFeed connection, with no leftovers from the previous connection session. If you are not concerned about this aspect, and wish to restart IQML’s connections without necessarily resarting IQConnect, use a lower Timeout.161 For example:
>> IQML('reconnect', 'timeout',0) % reconnect immediately after disconnecting
Note 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.
Also note that in the few seconds following an initial connection (or re-connection) to IQFeed, some queries may return empty data. In such cases, you should try to refetch the data after a short pause (see §3.4 for details).
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 =
Timestamp: '20210203 12:57:30.653'
Datenum: 738190.539938113
ServerIP: '66.112.148.226'
ServerPort: 60002
MaxSymbols: 1300
NumOfStreamingSymbols: 15
NumOfAvailableSymbols: 1285
NumOfClientsConnected: 3
SecondsSinceLastUpdate: 1
NumOfReconnections: 0
NumOfAttemptedReconnections: 0
StartTime: 'Mar 07 11:03AM'
MarketTime: 'Mar 07 04:34AM'
ConnectionStatus: 'Connected'
IQFeedVersion: '6.0.0.5'
LoginID: '123456-1'
TotalKBsRecv: 42.98
KBsRecvLastSecond: 0.02
AvgKBsPerSecRecv: 0.02
TotalKBsSent: 361.62
KBsSentLastSecond: 0.22
AvgKBsPerSecSent: 0.19
TotalMsgsRcv: 9530
Exchanges: {1×16 cell}
ServerVersion: '6.1.0.20'
ProtocolInUse: 6.1
ServiceType: 'real_time'
IQFeedAccountExpiryDate: ''
The returned data struct includes the following data fields:162
Timestamp – The timestamp of fetching the stats data
Datenum – The numeric Matlab datenum value of the Timestamp
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 – # of symbols that are currently being streamed
NumOfAvailableSymbols – # of symbols that are available for streaming
NumOfClientsConnected – # of clients that are currently connected
SecondsSinceLastUpdate – # of seconds since last update from the Quote Server
NumOfReconnections – # of times that IQFeed successfully reconnected
NumOfAttemptedReconnections – # of times IQFeed failed to reconnect
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.
TotalMsgsRcv – Total number of messages received from IQFeed
Exchanges – A cell-array list of exchanges and news subscriptions for which this IQFeed account is subscribed. Delayed data has 'DL-' prefix. For example: {'DL-FTSE', 'EUREXNDX', 'DL-NYMEX', 'CBOENDX', 'BLOOMBERG', 'FOREX_PREMIUM', 'RT_TRADER', 'DTNNEWS', 'BENZINGA', 'INDEX'}
ServerVersion – The server-recommended version of IQFeed. This version is typically the same or higher than your locally-installed IQFeedVersion, except in cases when you run a beta version of IQFeed.
ProtocolInUse – The protocol version that IQML uses to communicate with IQFeed (see §9.1 for details)
ServiceType – Type of data provided for this account (delayed or real-time)
IQFeedAccountExpiryDate – The IQFeed account expiry date: empty string for regular IQFeed users; YYYYMMDD format for DTN trial users.
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 =
Timestamp: '20210203 12:57:30.653'
Datenum: 738190.539938113
ServerIP: '66.112.148.224'
ServerPort: 60005
MaxSymbols: 1300
NumOfStreamingSymbols: 15
NumOfAvailableSymbols: 1285
NumOfClientsConnected: 4
SecondsSinceLastUpdate: 0
NumOfReconnections: 0
NumOfAttemptedReconnections: 0
StartTime: 'Apr 01 8:21PM'
MarketTime: 'Apr 01 02:12PM'
ConnectionStatus: 'Connected'
IQFeedVersion: '6.0.0.5'
LoginID: '464720-1'
TotalKBsRecv: 69.44
KBsRecvLastSecond: 0.04
AvgKBsPerSecRecv: 0.02
TotalKBsSent: 1470.32
KBsSentLastSecond: 0.47
AvgKBsPerSecSent: 0.48
TotalMsgsRcv: 9530
Exchanges: {1×16 cell}
ServerVersion: '6.1.0.20'
ProtocolInUse: 6.1
ServiceType: 'real_time'
IQFeedAccountExpiryDate: ''
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
EventsReceived: 17836
EventsNotified: 17836
EventsProcessed: 15267
EventsIgnored: 2569
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 (i.e., if the returned data-struct does not contain the channel/port sub-structs), simply resubmit the query after 1-2 secs.
The returned data structs include the following fields for each data channel (port):163
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.
EventsReceived – Total # of messages received from IQFeed via this data port.
EventsNotified – Total # of messages sent to IQML’s Matlab code to process. This value will typically be the same as EventsReceived, except in cases of high streaming data load, when OverflowMode=1 (see §6.1 for details).
EventsProcessed – Total # of IQFeed messages processed by IQML. This value will be less than EventsNotified in cases of high load, when OverflowMode=2.
EventsIgnored – Total # of messages thet were ignored due to overflow protection. This is the same as EventsReceived - EventsProcessed.
Corresponding information (except the fields on overflow handling) can also be seen in IQConnect’s Diagnostics Utility, which is included in IQFeed’s client installation:
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,164 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,165 whereas the 'S,CLIENTSTATS OFF' command (which stops the IQFeed server from streaming client stats messages) is defined for the Admin port.166 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 is not always consistent in the format of the various commands. For example, the 'S,TIMESTAMPSOFF' command has no space, whereas the 'S,CLIENTSTATS OFF' command does include a space; also, both of these commands are all-uppercase, whereas 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:167
>> 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…”:
➔ |
Be 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.
159 For example, historic market summary data and scanning (§5.6)
160 For example, Logitech GHub (via its LgHubUpdater.exe program) typically uses port 9100, IQFeed’s default Lookup port: https://forums.dtn.com/index.cfm?page=topic&topicID=7036, http://forums.dtn.com/index.cfm?page=topic&topicID=5843
161 IQConnect remains alive a few seconds after receiving a termination signal. If a reconnection request or any IQML query is received during these few seconds, IQConnect will not terminate and will service the incoming requests. The default pause of 8 seconds was chosen by experimentation that showed that in most cases this is sufficient time to ensure that IQConnect terminates. When Timeout is set to 0, no termination signal is sent to IQConnect and IQML reconnects immediately; When Timeout is set to any value between 0-8, the resulting pause will be smaller than the default (i.e., faster reconnection), but it is not assured that IQConnect has properly terminated by then, and this might potentially result in a bad reconnection. You can experiment with various Timeout value to see what works best for your specific computer setup.
163 See §9.1 for a description of IQFeed’s data channels (ports)
167 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.