NAME
Finance::InteractiveBrokers::TWS - Lets you talk to Interactivebrokers Trader's Workstation using Perl.
This module is a wrapper around InteractiveBroker's Trader's Workstation (TWS) Java interface, that lets one interact with the TWS using Perl, via the vendor supplied API. This means that all the functionality available to Java programmers is also available to you.
VERSION
This document describes Finance::InteractiveBrokers::TWS
SYNOPSIS
package Local::Callback;
use strict;
sub new {
bless {}, shift;
}
sub nextValidId {
my $self = shift;
$self->{nextValidId} = $_[0];
print "nextValidId called with: ", join(" ", @_), "\n";
}
sub error {
my ($self, $return_code, $error_num, $error_text) = @_;
print "error called with: ", join('|', $return_code,
$error_num, $error_text), "\n";
# sleep for some predetermined time if I get a 502
# Couldn't connect to TWS. Confirm that "Enable ActiveX and
# Socket Clients" is enabled on the TWS "Configure->API" menu.
if ($error_num == 502) {
sleep 60;
}
}
sub AUTOLOAD {
my ($self, @args) = @_;
our $AUTOLOAD;
print "$AUTOLOAD called with: ", join '^', @args, "\n";
return;
}
package main;
use Finance::InteractiveBrokers::TWS;
my $connected = 0;
while (1) {
if ($connected) {
process_queue();
}
else {
connect_to_tws();
}
}
# connect_to_tws, connects to the tws and sets up a few
# objects that we want clean at every new connection
sub connect_to_tws {
my $callback = Local::Callback->new();
my $tws = Finance::InteractiveBrokers::TWS->new(
callback => $callback
);
my $client_socket = $tws->get_EClientSocket();
my $api = $tws->get_api();
#### Host Port Client_ID
#### ---- ---- ---------
my @tws_GUI_location = qw/ 127.0.0.1 7496 15 /;
while (! $tws->get_EClientSocket->isConnected()) {
$client_socket->eConnect(@tws_GUI_location);
}
$api->OpenCallbackStream();
# spin until we get a nextValidId, that way we know the connection
# is complete
while (! defined $callback->{nextValidId}) {
process_queue($api);
}
# Just process the queue for a little to make sure all connection
# messages have been processed, otherwise if I interact with TWS
# too early I get weird errors
foreach (0..100) {
process_queue($api);
}
my $contract_id = 50; # this can be any number you want
my $contract = $tws->Contract->new();
$contract->{m_symbol} = 'YHOO';
$contract->{m_secType} = 'STK';
$contract->{m_exchange} = 'SMART';
$client_socket->reqMktData($contract_id, $contract);
my $connected = 1;
return;
}
# process_queue, process all the current messages that have been sent
# from the TWS at this point. The callback will be called for each
# message in the queue
sub process_queue {
my ($api) = @_;
while ($api->WaitForCallback(.05)) { # .05 works good here, I had
$api->ProcessNextCallback(); # problems with .01
}
return;
}DESCRIPTION
Finance::InteractiveBrokers::TWS - Is a wrapper around InteractiveBrokers Traders Workstation (TWS) Java interface, that lets one interact with the TWS using Perl, via the vendor supplied API.
It uses Inline::Java to wrap InteractiveBrokers' Java API that IB supplies to communicate with the TWS. After numerous attempts at writing a pure perl module I opted for this solution because:
Using Inline::Java resulted in a much simpler and smaller module
The interaction and call syntax is identical to the Java API (because it is the Java API) and as such, you can ask questions on the IB bulletin board and yahoo, and be using the same method names and call syntax as they are. In other words, people will know what you're talking about.
IB changes their interface with some frequency, which required re-writing my interface every time
IB changes there message stream, which required me to modify my parser
Whenever IB changes something I'd have to diff the old API versus the new API and try to figure out what changed and how that affected my code
INTERFACE
The interface is identical to the Java API supplied by InteractiveBrokers. There are 2 interfaces to be exact. The calling interface, i.e. the methods you call to send data to the TWS, and the callback interface, that is the data that is sent back to your custom event handler (callback).
I'm not going to document the interface (unless you make me) since InteractiveBrokers already did.
Calling Interface
IB's documentation is pretty weak. But here is a list of methods you can call once you have created a Finance::InteractiveBrokers::TWS object
http://www.interactivebrokers.com/php/webhelp/Interoperability/Socket_Client_Java/java_eclientsocket.htm
Callback Interface
http://www.interactivebrokers.com/php/webhelp/Interoperability/Socket_Client_Java/java_ewrapper.htm
DIAGNOSTICS
Finance::InteractiveBrokers::TWS::java::lang::NullPointerException=HASH(0x8b671cc) - This means you did not supply a callback object when you instantiated a Finance::IB:TWS object.
The error message was:
TWS_661f.java:21: incompatible types
found : int
required: java.lang.Object
tickerId, field, price, canAutoExecute
^The above error is sort of a bug, sort of an inconsistancy. But basically if you are running Java <= 1.4 then you need to alter the TWS.pm source and change the lines that look like:
perlobj.InvokeMethod("tickPrice", new Object [] {
tickerId, field, price, canAutoExecute
});and manually cast the variables into their types directly, like this:
perlobj.InvokeMethod("tickPrice", new Object [] {
new Integer (tickerId), new Integer (field), new Double (price),
new Integer (canAutoExecute)});I don't feel like going through all the code to do this, especially since most people will be using Java 1.5 and above shortly
CONFIGURATION AND ENVIRONMENT
You need to compile the *.java API source files into java class files prior to using this module. Do it like:
$ cd ~/IBJts/java/com/ib/client/
$ javac *.javaFurthermore Finance::InteractiveBrokers::TWS does require that you set your CLASSPATH environmental variable to the location of the IBJts/java directory where you installed the IB API. Such as:
$ export CLASSPATH=~/IBJts/javaDEPENDENCIES
Java SDK
InteractiveBrokers TWS GUI application
Inline::Java v.50_92 or greater
INCOMPATIBILITIES
See above DIAGNOSTICS
BUGS AND LIMITATIONS
See above DIAGNOSTICS
Please report any bugs or feature requests to bug-finance-ib-tws@rt.cpan.org, or through the web interface at http://rt.cpan.org.
SPECIAL THANKS
Patrick LeBoutillier - Author of Inline::Java, and for all his help while I learned how to use Inline::Java
AUTHOR
Jay Strauss <tws_at_heyjay.com>
LICENCE AND COPYRIGHT
Copyright (c) 2006, Jay Strauss <tws_at_heyjay.com>. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.
DISCLAIMER OF WARRANTY
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.