Current time: 15:11   
Descriptive files from the source distribution
   copyright (c) 2005--2007, LLC  Columbus, OH
   GPL version 3 or later, see COPYING for details


Prerequisites:  You need, at a minimum, a C++ compiler; a Java; a
running Trader Workstation, available by download from ; MySQL; and Ruby.  You should also
consider installing the Graphviz package, if you want to recreate
the documentation, and distcc, if you want to compile the shim more
than once.  For Graphviz and distcc, we recommend the rpm packages
available from

Given a reasonable linux distribution, g++, Ruby, and MySQL are just a
package away.  What follows expects you to have this minimal foundation.

In the future we expect to provide a source rpm as an alternative
to the current tarball package, and we hope users consider switching
to that approach when we make it available.  We prefer the
administrative stability and consistency that follow from the
versioning and dependency resolution provided by a strong package

For more on installation beyond the text below, please see the manual;
it's the authoritative source for installation directions, and is available
both online at, and in your source tarball.

In brief:

    1.  Unpack and compile the sources
    2.  Setup and populate the database
    3.  Start the IB TWS and enable api connections.
    4.  Configure and run the shim, and see the example scripts
        in the exs directory, and in particular exs/test.rb, for
        examples of how the shim may be used.

1.  Compile the sources.  Either set up distcc, or use the Makefile
    as is to use g++ directly, and run make to compile the sources,
    e.g., from the directory originally containing this file, at the
    shell command prompt type:

        make shim

2.  Set up the MySQL database server, and use the instructions that
    follow these paragraphs to setup the two trading-shim databases,
    testing and trading.  The testing database is intended for use
    with an IB paper account and the regression test scripts that
    accompany the shim, while the trading database may be used with
    a real account, if you so choose to take this risk.

    Use the setup.sql script in subdirectory sql to create the
    initial set of user acccounts, the testing and trading databases,
    their tables, as well as load the tables with initial values;
    or else treat the setup script as a starting point to see how
    to set a database according to your own naming and security policy,
    and use the script create.sql to create and load the database tables.

    More precisely, and given that you accept the naming and security
    choices in the setup.sql script, do the following:
    2.1 Obtain the mysql [not Linux OS] root account password.

    2.2 Unpack the shim tar ball on the machine from which you
        intend to login to the mysql database, or else copy the
        subdirectory sql with all its contents and subdirectories
        to that machine.

    2.3 From the directory sql, and given read access to the sql
        directory, its subdirectories, and files, start the mysql
        interpreter as the (mysql) root user:

            mysql -u root -p

    2.4 Enter the following command in order to create user accounts,
        the testing and trading databases, create the tables for those
        databases, and populate them with initial values.  You should
        see *many* status messages fly by (on the order of a couple
        of hundred; in the dialogue below, the elipsis indicate many
        rows scrolling by), and ending with the mysql prompt:

            mysql> source setup.sql

            ... ... ... ... ... ... ... ... ... ... ... ... ... ... ...

            Query OK, 4 rows affected (0.00 sec)
            Records: 4  Duplicates: 0  Warnings: 0

            Query OK, 4 rows affected (0.00 sec)
            Records: 4  Duplicates: 0  Warnings: 0

            Query OK, 0 rows affected (0.00 sec)


    2.5 Type quit at the prompt to end the mysql session:
            mysql> quit

    If you ever need to recreate the tables and load their initial
    values, you may use the create.sql script to do this without using
    the mysql root account; see the manual for details.

    You should feel free to recreate the testing database tables as
    needed, and in any case, you will need to do this to upgrade
    your table design as new versions of the shim are released.
    The create.sql script, in particular, is provided to enable you
    to rebuild the tables without again obtaining mysql root access;
    you should only have to run the setup.sql script once, while the
    create.sql script may be executed many, many times during

    Note that the OrderJournal table contains accounting information
    about the orders, if any, that you have made, so that if you
    use a real IB account with the trading database, as opposed to
    the paper account that should be used with the testing database,
    you will need to first preserve the logical contents of that table.

3.  Start your IB TWS, and enable api connections.

    You must have the IP number of the machine on which the shim will be
    running included as a trusted address.  E.g., for the shim connecting
    as localhost, the IP number must have been entered as a
    trusted IP number, either by editing settings.xml while tws is not
    running, or using the configure menu option and saving the new
    configuration while it is, with the result that the file settings.xml
    includes information similar to the following:


    Interactive Brokers'Trader Workstation requires Java 1.5, so you will
    also need to have Java installed.

4.  Run the trading shim

    4.1 Provide the shim connection info, for both the database and 
        the IB tws, either via the config file .shimrc, of which
        there is an example file named shimrc in the tarball which may
        be edited and renamed with a leading dot; or via the "init"
        cmd line option, using the let command, about which see also
        the example shimrc file.

    4.2 Start the shim.  From the command prompt, to confirm the compile,
        and to read the usage message, you may run the shim without command
        line arguments, e.g., from the directory where the shim was compiled,
        the command "./shim" prints the following text:

Usage: shim  [optional feature list]

               # real modes, requiring access to an IB tws:
    --data     # process subscriptions and log resulting tick stream events
    --risk     # accept full command set, send requests, and log all events

        There may also be trace output to stderr, left in for debugging and
        development purposes.  That being said, when a message such as the
        following scrolls by, you'll know that the database and tws
        connnections were successful:

            The trading shim has connected to the database server and
            loaded  nnnnn products.  The IB tws offered api level 45,
            and connection negotiation resulted in an api level of 23
            and a client id of  1.  A query shows the account code to
            be  DUxxxx.  Program initialization has been completed.

    4.3 Provide commands and database inputs to the running shim.

        Commands consist of the command verb phrase, optional
        arguments, and a trailing semicolon.  The sample scripts in
        the exs directory explain the syntax for the various commands.
        To end a session, enter either the quit or exit command, e.g.:


        The quit command is immediate, while the exit command is queued
        to follow previously entered command requests, so that program
        termination waits until all upstream requests have been sent.

        Most of the time you'll be running the shim from shell scripts,
        in order to manipulate the database.  Look at the test scripts
        in exs, in particular test.rb and risk.rb, to see examples of
        how to use the shim.

        The mode names data and risk are chosen to suggest the
        real-world consequences of running in that mode, and the comments
        in risk.rb suggest the implications with respect to your account
        of running the order-related regression tests.  In short: run
        the order regression tests against the paper account only.  Do not
        run them against a real account with the shim in "--risk" mode.

        Please consider reading the file create.sql, and the related
        files that are source'd by it.  This is most of the documentation
        currently available about the database design, and you will need
        to understand that database in order to control the shim.  See
        also doc/ for a graph of selected foreign key dependencies.

    4.4 Display or process the resulting data.

        To see the log data, you may use "tail -f" on the file
        log/ShimText, or use the script bin/tail.window:

            bin/tail.window log/ShimText 2

        to scroll tick data.  I keep the resulting console window open,
        so I can see the results of regression tests; you may use one to
        provide a running ticker tape of the market data subscriptions
        you have requested, e.g., via a script such as exs/tick .

    4.5 Startup troubleshooting.

        Your goal for installation should be to run the shim and obtain
        a startup banner similar to that given in section 4.2

        This step *must* succeed in order for the shim to do useful work,
        that is function in "--data" or "--risk" modes.  No database, no
        tws api access via the trading shim.  Period.

        In addition to enabling the socket clients under the IB tws
        configuration menu, you must also have entered the IP address that
        the shim is connecting from as a trusted address.  Otherwise, the
        accept incoming connection dialogue will pop up, and the regression
        tests will not work.

        Messages such as the following indicate problems with connection to
        the tws:

            An attempt to connect to host localhost on port 7490 failed; you may
            need to start, restart, or provide access permissions to, the IB tws.
            Connect: Connection refused
            errno: 111; port 7490

            Problem: 520 the IB tws socket connect failed

        or with connecting to the database:

            An attempt to connect to the database [] on [] as user []
            failed; you may need to create it, start the server, or
            provide appropriate login info.

            mysql_real_connect() failed

            Problem: 511 could not initialize mysql connection

        Your downstream scripts will need configuration information also,
        and this includes the test.rb script, which represents the database
        connection info via literal text in exs/rsc/CannedCmds.rb .  You
        need to update that file if you see a message similar to the above
        when running that regression script; for the general case, you'll
        need to provide connection info as noted in 4.1 above, and explained
        furthur in the sample shimrc file included with the sources.

Please understand that the trading shim is a work in progress, with more
development to go.  Good luck, and please consider joining the mailing
list ts-general to keep us posted on your progress. 


Bill Pippin

HomeSearchInterior documentationProgram documentationFAQDownloadPDFsScreen shots ]  [ Contact UsSite MapBugzillaMailman |  Mailing List Archives: (MainLicenseAboutPressCopyright ]

Copyright (c) 2006 ... 2009, LLC, Columbus, OH