If I make a call saying like this:
signal.mpl?cmd=signalstatus&signalid=26618011&pw=myc2password&c2email=matthew@collective2.com&showrelated=children&showdetails=1
I get back a parent order with multiple children (such as stoploss and takeprofit). However, the ocagroupid for all is ‘0’ (not blank). First of all - is this correct? Should the ocagroupid be zero? Additionally, could I cancel one (or both) of the ‘child’ orders and replace them with new orders such as a new stoploss and takeprofit that will be linked thru a subsequent getrelated call?
The OCA group will be zero if there is no OCA group. That will inevitably be the case when there is only one child order. In cases where there are two children (conditional) orders – such as a case where you submit an entry order, a stop, and a profit target all at once – then an OCA group will automatically be created. (There is a way to turn this feature off; see parameter forcenooca=1, below.)
I’ve created a mini tutorial which will demonstrate the use of some of the API calls. I intend to add this to the formal documentation shortly. Here it is. (Long urls will be broken into two lines to prevent ugly formatting, but of course they should remain on a single line.)
----
Here is an example of how you can submit orders, get information about them, and use the comment field to store information internal to your application.
First, we place an entry order with an associated stop loss and profit target.
http://www.collective2.com/cgi-perl/signal.mpl?systemid=13889808&
pw=PASSWORD&instrument=future&symbol=@ESZ7&cmd=signal&
action=BTO&quant=10&limit=1300&stoploss=1200&profittarget=1400
Response:
<collective2>
<signalid>29148577</signalid>
<comments>Signal 29148577 accepted for immediate processing.</comments>
<oca></oca>
<delay></delay>
<profittargetsignalid>29148580</profittargetsignalid>
<stoplosssignalid>29148580</stoplosssignalid>
<autoOCAgroupid>29148580</autoOCAgroupid>
</collective2>
Note that the signal IDs have been assigned for us. Since there are 2 children orders (stop loss and profit target), they are made into an OCA group (one cancels another). This means that if either is filled or cancelled, the other order will be canceled and will not be left “hanging.” If you prefer to manage you own OCA groups, you can prevent an autoOCAgroupID from being assigned by adding a &forcenooca=1 parameter to the cmd=signal call. This may be preferable because it will allow you to change stop losses (by canceling the stop loss and then submitting a new order) without affecting the profit-target order, or vice-versa.
Now let’s look at the signals that are pending for a particular user. The getallsignals command will return the signals that are pending for a given C2 customer. If I am subscribed to 10 systems, when I send my email/password combination, I will receive a list of 20 nodes, one for each system. System developers/owners are treated automatically as subscribers to their own systems, even if they do not formally subscribe on C2.
http://www.collective2.com/cgi-perl/signal.mpl?c2email=MYEMAIL&
pw=PASSWORD&cmd=getallsignals
<collective2>
<status>OK</status>
<allPendingSignals>
<system>
<systemid>13889808</systemid>
<pendingblock>
<signalid>29148580</signalid>
<signalid>29148582</signalid>
<signalid>29148577</signalid>
</pendingblock>
</system>
</allPendingSignals>
</collective2>
One can imagine writing an app which will cycle through the appropriate signalids above, requesting more information using the signalstatus command. Here is an example request.
http://www.collective2.com/cgi-perl/signal.mpl?cmd=signalstatus&
signalid=29148580&c2email=MYEMAIL&pw=PASSWORD&
showrelated=children&showdetails=1
<collective2>
<signal>
<signalid>29148580</signalid>
<systemname>Absolute Returns</systemname>
<postedwhen>2007-11-13 09:36:18:000</postedwhen>
<emailedwhen>2007-11-13 09:36:55:000</emailedwhen>
<killedwhen>0</killedwhen>
<expiredwhen>0</expiredwhen>
<tradedwhen>0</tradedwhen>
<tradeprice>0</tradeprice>
<action>STC</action>
<quant>10</quant>
<symbol>@ESZ7</symbol>
<limit>1400</limit>
<stop>0</stop>
<market>0</market>
<tif>GTC</tif>
<ocagroupid>29148579</ocagroupid>
<comment></comment>
</signal>
</collective2>
Using Comment Field to Store Information
Some C2 software developers have begun to use the <comment> field to store their own internal program state information. This wasn’t what the field was originally intended for, but it is ingenious. To aid these efforts, I have added a new API command called newcomment. You call it with a particular signalid and it overwrites the commentary field for that signal. Only system owners have permission to do this, obviously. You should be aware that once a signal has been emailed to subscribers, if you change the comment field, email subscribers will NOT receive the new commentary, although it will be visible to ITM subscribers or to anyone visiting the system page on the C2 Web site who turns on “show comments.” Given that the newcomment command is really meant only to store internal state information for your application, this is not necessarily a limitation. Here’s an example of how to use the newcomment field:
(Comment text must be URL encoded.)
http://www.collective2.com/cgi-perl/signal.mpl?systemid=13889808&
pw=PASSWORD&signalid=29148580&cmd=newcomment&
commentary=This+is+a+simple+%26+short+test.
<collective2>
<status>OK: Signal 29148580 comment created</status>
<signalid> 29148580</signalid>
<previousComment></previousComment>
</collective2>
The previousComment field will contain the comment text you are overwriting. This will be URL Encoded.
Now, to answer your question a bit more specifically: the only thing that links orders together in the “showrelated” sense is a parent/child relationship – in other words, a conditional order status.
You will create conditional orders automatically if you submit an entry along with either a stop loss, a profit target, or both. For example, if you submit:
cmd=signal&action=BTO&symbol=IBM&quant=1&limit=10&profittarget=20
you will essentially create two orders. The STC limit 20 will be a child order of (that is, conditional upon) the parent entry order.
You can create a conditional order manually by submitting a separate and single order, and specifying that it is conditional upon a parent. For this, you would use the &conditionalupon=xxx parameter, where xxx is the signalid of the parent. Of course, for this to work, you need to know the parent’s signal id. This can be accomplished either by parsing the signalid from C2’s response when you first submit the order, or by using your own local order numbering scheme (and including your own unique integer signalid with each order). All this is explained in more detail in the Signal Entry API documentation, reachable in the left menu bar.
Thanks, Matthew.
And just to clarify ( I know you mentioned this earlier), the conditionalupon parameter only works when the signal being specified is pending. In other words, once a parent order has been filled, no more children can be added to it (speaking in terms of the parent / child relationship). Is this correct?
Yes, I should probably make this fact more explicit in the documentation. If you attempt to add a new order and make it conditional on an order that has already been filled or canceled, this will not be permitted. The parent order must still be pending.
Is this also true for xReplace? will the xReplace fail if the parent has already been filled?
I also had a slightly related question. If I use noOCA what eventually happens to the STC and BTC orders that may be left behind if I don’t explicitly cancel them? Are they ever cleaned up by the system?
Sorry for the slow reply, Nathan. In answer to your questions:
>> Is this also true for xReplace? will the xReplace fail if the parent has already been filled?
Yes. xReplace (cancel-and-replace) will fail if the order you are trying to cancel (and replace) has filled.
>> If I use noOCA what eventually happens to the STC and BTC orders that may be left behind if I don’t explicitly cancel them? Are they ever cleaned up by the system?
Yes, they are cleaned up. If C2 sees a closing order (STC or BTC) lying around, with no matching current position, the orders will be unceremoniously canceled.
