merge doc/twsxml

doc/TWSXML.txt

@@ -0,0 +1,77 @@
+** Draft **
+
+Introduction
+============
+
+TWSXML is an ad-hoc xml standard that facilitates easy translation from
+and to IB's TWS API.  While it is generally desirable to have a formal
+specification TWSXML is too tightly coupled with IB's API and hence any
+effort to formally specify TWSXML without direct access to the
+underlying API would cause severe maintenance pressure.
+
+For people that are acquainted with the C++ or Java API there should be
+no major surprises.  There is a direct one-to-one correspondance between
+class members and TWSXML attributes.  The only difference therefore lies
+in the bracketing tag names which are briefly described below.
+
+Bracket tags
+============
+
+TWSXML
+------
+This is always the root node and only the root node.  The name space
+http://www.ga-group.nl/twsxml-0.1.  This has no direct correspondance to
+anything in the API.  Any such document
+
+    <TWSXML xmlns="http://www.ga-group.nl/twsxml-0.1">
+      ...
+    </TWSXML>
+
+will be understood by twsdo.
+
+request
+-------
+Next down is the request.  A TWSXML document can contain a sequence of
+requests.  The only allowed and obligatory attribute is type.
+
+Its only children are query and response, see below.
+
+At the moment we allow:
+
+  - type="contract_details"     represents the full shebang of contract
+                                information as known to IB
+  - type="historical_data"      represents an excerpt of historical data
+  - type="market_data"          represents a live-feed of market data
+  - type="place_order"          represents orders
+
+It is common that a user will send a request with only the query child
+to twsdo, and in return twsdo will hand out a request where the query
+part is repeated and a response child contains the actual response from
+the TWS.
+
+query
+-----
+This is the query part of a request, so to speak the actual request.
+
+The child node(s) of the query depend on the request type, see above.
+
+response
+--------
+This is most likely filled in by twsdo with the result the TWS has given
+at the point in time when the query was executed.
+
+The child nodes of the response depend on the request type, see above.
+Here's a brief summary of what you might encounter:
+
+  + type="historical_data"
+    - sequence of "row"
+
+  + type="contract_details"
+    - sequence of "ContractDetails" 
+
+  + type="place_order"
+    - one "OpenOrder"
+    - sequence of "OrderStatus"
+
+For further information confer the sample/ directory in this repository
+or the (experimental) TWSXML.xsd.

doc/twsxml-0.1.rng

@@ -0,0 +1,88 @@
+<?xml version="1.0"?>
+<grammar xmlns="http://relaxng.org/ns/structure/1.0">
+	<start>
+		<element name="TWSXML" ns="http://www.ga-group.nl/twsxml-0.1">
+			<zeroOrMore>
+				<ref name="request"/>
+			</zeroOrMore>
+		</element>
+	</start>
+
+	<!-- level 1 -->
+	<define name="request">
+		<element name="request" ns="http://www.ga-group.nl/twsxml-0.1">
+			<attribute name="type">
+				<text/>
+			</attribute>
+			<ref name="query"/>
+			<zeroOrMore>
+				<ref name="response"/>
+			</zeroOrMore>
+		</element>
+	</define>
+
+	<!-- level 2 -->
+	<define name="query">
+		<element name="query" ns="http://www.ga-group.nl/twsxml-0.1">
+			<optional>
+				<ref name="qmeta"/>
+			</optional>
+			<ref name="anything"/>
+		</element>
+	</define>
+
+	<define name="response">
+		<element name="response" ns="http://www.ga-group.nl/twsxml-0.1">
+			<optional>
+				<ref name="rmeta"/>
+			</optional>
+			<ref name="anything"/>
+		</element>
+	</define>
+
+	<!-- level 3 -->
+	<define name="qmeta">
+		<element name="qmeta" ns="http://www.ga-group.nl/twsxml-0.1">
+			<attribute name="nick">
+				<text/>
+			</attribute>
+			<attribute name="tws">
+				<text/>
+			</attribute>
+		</element>
+	</define>
+
+	<define name="rmeta">
+		<element name="rmeta" ns="http://www.ga-group.nl/twsxml-0.1">
+			<attribute name="tws">
+				<text/>
+			</attribute>
+		</element>
+	</define>
+
+	<!-- we leave out all other elements as they are -->
+	<!-- specific to the api version used -->
+
+	<!-- helpers -->
+	<define name="any_attr">
+		<zeroOrMore>
+			<attribute>
+				<anyName/>
+			</attribute>
+		</zeroOrMore>
+	</define>
+
+	<define name="anything">
+		<zeroOrMore>
+			<attribute>
+				<anyName/>
+			</attribute>
+		</zeroOrMore>
+		<zeroOrMore>
+			<element>
+				<anyName/>
+				<ref name="anything"/>
+			</element>
+		</zeroOrMore>
+	</define>
+</grammar>

sample/sample_job_order.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0"?>
+<TWSXML xmlns="http://www.ga-group.nl/twsxml-0.1">
+	<request type="place_order">
+		<query orderId="1234">
+			<contract symbol="TNA"
+				secType="STK"
+				primaryExchange="ARCA"
+				exchange="SMART"
+                                currency="USD"/>
+			<order action="BUY"
+				totalQuantity="10"
+				orderType="MKT"
+				lmtPrice="0"
+				auxPrice="0"
+				tif="DAY"
+                                ocaGroup=""
+                                orderExchange="SMART" />
+		</query>
+	</request>
+</TWSXML>