|
License |
About |
Press |
Copyright ] copyright (c) 2005--2007 Trading-shim.com, LLC Columbus, OH
GPL version 3 or later, see COPYING for details
Installation:
Prerequisites: You need, at a minimum, a C++ compiler; a Java; a
running Trader Workstation, available by download from
http://www.interactive.brokers.com/ ; 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 http://www.centos.org.
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
system.
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 www.trading-shim.com, 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)
mysql>
________________________________________
2.5 Type quit at the prompt to end the mysql session:
mysql> quit
Bye
sql$
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
development.
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 127.0.0.1 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:
false
true
true
false
7496
127.0.0.1
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]
Modes:
# 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.:
quit;
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/foreign.ps 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
Exiting
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
Exiting
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.
Thanks,
Bill Pippin
pippin@trading-shim.com
[ Home |
Search
|
Interior documentation |
Program documentation
|
FAQ |
Download |
PDFs |
Screen shots ]
[ Contact Us |
Site Map |
Bugzilla |
Mailman
|
Mailing List Archives: (Main) |
License |
About |
Press |
Copyright ]