Choosing the Mode

A command mode is required for normal operation. If you leave it off the command line, you'll get the mode message of Figure 3.13 to explain your available choices. I'll consider the real modes in this section, and the help mode in the next one, leaving aside the test modes as of use only to developers.

Figure 3.13: The mode message
\begin{figure}\footnotesize
\begin{verbatim}Usage: shim <mode> [optional featu...
... for internal use; unstable though otherwise harmless\end{verbatim}
\end{figure}

For all productive use of the shim you'll use either -data or -risk mode.

Data mode protects you from unintentional orders, since the commands used for orders are not accepted by a shim running in that mode; it literally can not understand them, and will treat such as a syntax error. Data mode has the virtues of its defect, since denial-of-service issues that might be critically important as orders are transmitted become much less troublesome when all that is at stake are market data subscriptions and outstanding history queries. E.g., the bulk subscription command, load, which is convenient for rapidly changing from one set of subcriptions to another, is best suited to data mode; even if you run up against your market data subscription limit by mistake, you can compensate for lost access to a particular symbol by an ad hoc history query.

As mentioned previously, you can submit orders to the IB tws in risk mode, and this is the only mode that accepts the commands to submit and cancel orders. All other commands are also supported in this mode, including the bulk subscription load command, since you might need to monitor market conditions over some large, rapidly changing set of symbols. You should be careful, however, to control the number of market data subscriptions that you have in place at any one time, since IB limits you to at most 100 per account. This and other IB tws resource limitations are listed in Figure 3.14, and each of these limits is enforced as well by the shim, to avoid disconnect-reconnect delays.

Figure 3.14: Resource limits to the IB tws
\begin{figure}\centering
\begin{tabular}{\vert r\vert l\vert} \hline
Limit & Res...
...& history queries in flight at any one time  \hline
\end{tabular}
\end{figure}

The shim feeds requests to the IB tws at most once every 20 milliseconds, to avoid breaking the api request rate limitation. It counts market data and market depth subscriptions already submitted, and queues new ones up until the number of active subscriptions has declined to allow the requests to be sent. Only one history query is sent out at a time, and at most six of those will be submitted per minute. In each case over-eager downstream commands that would surpass some rate or counted limit are simply queued up until conditions allow later submission.

For market data, and in the absence of subscription cancellations, the resulting delay is unbounded, so that careless use of the load command might easily block data subscriptions for critical, position-related contracts. It is up to the user or programs that control the shim -- i.e., you -- to make the resource allocation decisions for history queries and market data subscriptions that are necessary to stay within the limitations that IB has placed on their system. Otherwise, early requests will starve later ones.

Bill Pippin 2010-01-14