O*U*C*H
Version 0.5 - DRAFT
By Joshua Levine
September 17, 1997
OUCH is a protocol that allows subscribers to enter orders into and receive executions from the Island ECN. It is intended to allow subscribers and their software developers to integrate Island into their proprietary trading systems or build new front ends to Island.
Island is an Electronic Communications Network (ECN) as defined by the SEC in rule 17a-23. Island accepts limit orders from system subscribers and executes matching orders against each other. Non-matching orders are added to the Island Limit Order Book, a database of available limit orders, where they wait to be matched in price-time priority. All Island subscribers are anonymous, that is no subscriber’s identity is disclosed. The top of the Island book is represented in the NASDAQ Level II quote by the ISLD identifier to give Island orders the maximum opportunity for discovery. Island accepts orders from about 8:00 AM until about 4:30 PM EST, but those hours could be extended. Island does not accept "Good ‘Till Canceled" orders, all orders are dead when Island closes each night.
OUCH only provides a method for subscribers to send orders to Island and receive executions on those orders, it does not convey any information about other subscribers’ orders in the book. For a data feed of all orders on the Island book, please see the ITCH feed specification.
The OUCH protocol is composed of messages passed between the OUCH machine and your application. Each message ranges in length from 1 to about 100 bytes in length and is composed of non-control ASCII bytes terminated by an ASCII carriage return (13 decimal, 0x0D hex) line feed (10 decimal 0x0A hex) pair. The trailing line feed is optional on inbound messages. Each Sequenced Outbound Message is assigned a day unique Sequence Number. The first Sequenced Message sent at the beginning of the day is always the Start of Day Message with a sequence number of 1. The last Sequenced Message is always the End of Day Message.
Each OUCH host machine is assigned a six character Account Name. This Account Name is used during the login and appears on the monthly Island bill. Each subscriber can have one or more OUCH machines to connect to, and each can have a different Account Name corresponding to a separate office or department.
Every order entered on OUCH is uniquely identified by the combination of the Account Name, User, and Token fields. The User field is an arbitrary four character field that can be used for anything, but should ideally be used to identify the user who entered the order because Island monthly bills are broken out based on the User field. The Token field is an arbitrary ten character field that must be day unique for this OUCH Account Name and User. Other than day uniqueness per Account Name and User, there are no other requirements for the Token, so you may wish to use your own system’s internal tracking number as the token for convenience.
All numeric fields are right justified, blank padded. Malformed numbers produce undefined results.
All decimal numeric fields are zero filled on the right and blank padded on the left. Malformed decimals produce undefined results.
All alpha fields are left justified, blank padded.
A single Account Name can also be assigned to multiple OUCH machines. These OUCH machines could then be used as mirrors of each other for fault redundancy. In this configuration, both machines would be able to accept orders and any Outbound Sequenced Messages sent would be transmitted by both machines. All un-sequenced messages are machine distinct, so you could log in and out, request rewinds, and enter orders on the two machines independently.
For maximum redundancy, the mirrored machines should be located at geographically diverse data centers with communications carrier access diversity. For example, if a subscriber had two mirrored machines, one could be located at Island’s downtown New York data center and one at Island’s New Jersey Backup Site. The subscriber could increase reliability by using an MCI line to New York for primary connection and an AT&T line for connection to the New Jersey Backup Site. The two lines could also terminate at different subscriber locations on distinct computing platforms.
A single OUCH Account Name can accept orders for one or more firms, allowing a service bureau configuration. The service bureau Account Name must be specifically authorized to enter trades on behalf of each represented subscriber with an Island Service Bureau Agreement. Once an agreement has been submitted, the Account Name set up as the service bureau may enter orders for the represented firm by putting the represented firm’s Market Maker Identifier in the Firm field upon order entry.
Your application should ignore any extra characters appearing at the end of a message, allowing this specification to be extended in the future while maintaining compatibility with written code. You should also deal gracefully with unknown Reason Codes.
You should provide your users with a "Manual Restart" function that will disconnect from OUCH, purge your local database, reset your expected sequence number to one, and reconnect. This will give your application a sure fire way to recover from almost any error.
With the sole exception of the "Duped Token" Rejected Order Message which could indicate a serious problem, all "Reasons" are given for human informational purposes only. There is no need for you to parse or understand these messages, you can safely pass them to the user.
OUCH is currently available on a dedicated point-to-point basis via either TCP/IP or ASYNC. TCP/IP connections are provided as a 10BaseT standard RG-45 Ethernet jack suitable for connection to a router. ASYNC connections are provided as a standard RS232 DB9 male connection running at 56.8K baud, even parity, 7 data bits, 1 stop bit, suitable for connection to a modem or CSU/DSU.
If you don’t like any of these, I can accommodate pretty much any other delivery mechanism you like, just ask.
Leased circuits can be DEMARCed to either of our data center locations, or to both for disaster recovery:
Smith Wall Associates 50 Broad Street 6th Floor Data Center New York, NY 10004 212-514-7675 |
Smith Wall Associates-Recovery Site 100 Wood Avenue South 4th Floor Data Center Iselin, NJ 08830 908-906-1800 |
All leased circuits are ordered and maintained by the subscriber, along with any communication equipment like routers and CSU/DSUs.
Both TCP/IP and ASYNC connections can also be provided on a dialup basis for development, testing, or backup purposes.
MCI frame relay network connections are also available to both Island data centers.
Outbound sequenced Messages are transmitted by the OUCH machine to your application. You need to receive every single Outbound Sequenced Message to know where you stand, so there are ways to re-request messages to recover from gaps.
The most important messages are the outbound sequenced messages. All outbound sequenced messages share this common header:
Outbound Sequenced Message Header |
|||
Name |
Length |
Value |
Notes |
Type |
1 |
"S" |
A single ASCII byte identifying this message as one of the Outbound Sequenced Message types. |
Sequence |
10 |
numeric |
This day-unique sequence number counts up with each new outbound sequenced message generated. It starts with 1. |
Time |
5 |
numeric |
This timestamp indicates when this message was originally generated. It is expressed in seconds past midnight., so , for example 9:30:00AM would be (((9*60)+30)*60)=34200. |
Event messages are outbound sequenced messages that tell you about some predefined event. They look like this:
Event Message Body |
|||
Name |
Length |
Value |
Notes |
Outbound Sequenced Header |
16 |
See above |
See outbound sequenced message header. |
Event Message Identifier |
1 |
"E" |
Tells you that this outbound sequenced message is an event message. |
Event Specifier |
1 |
alpha |
The event specifier tells you which event just happened. See Event Specifiers below. |
Event Specifiers |
|
Specifier |
Event Explanation |
"S" |
Start Of Day. This is the first message generated each day and always has a sequence number of one. This tells you that Island is open and ready for business. It can come anytime from 6:00AM EST to 9:15AM EST, but currently comes at about 8:30AM based on demand. |
"E" |
End of Day. This is the last message generated. It tells you that Island is done for the day and we are going home to go to sleep. You should clear out any remaining open orders still in your book and get ready for a brand new day. It can come anytime after 4:00PM on non-holidays, but currently comes at about 5:00PM based on demand. |
Text messages are the way I can let you and your users know important special information. They are sent only when necessary and should be displayed somewhere where the user can see them, preferably as a popup window. Some examples of text messages are "NASDAQ SelectNet is suspended, Island orders not mirrored" and "Nationwide MCI outage, all open orders being purged."
Text Message Body |
|||
Name |
Length |
Value |
Notes |
Outbound Sequenced Header |
16 |
See above |
See outbound sequenced message header. |
Text Message Identifier |
1 |
"T" |
Tells you that this Outbound Sequenced Message is a free form text alert message. |
Text |
80 |
text |
Text. This is the actual text alert as a series of ASCII characters, padded with spaces on the right. |
Order messages inform you about every event in the lifetime of your orders, from creation to execution to disposition.
Order Message Header |
|||
Name |
Length |
Value |
Notes |
Outbound Sequenced Header |
16 |
See above |
See Outbound Sequenced Message Header. |
Order Message Identifier |
1 |
"O" |
Tells you that this Outbound Sequenced Message is an order message. |
Order User Identifier |
4 |
alphanum |
This is just the User field that was transmitted with the order when entered. |
Order Token |
10 |
alphanum |
This is just the order Token field as was transmitted with the order when entered. |
An Accepted Order Message acknowledges the receipt of a valid order. The Accepted Order Message repeats back all of the information originally entered with the order so you can recover from a local database failure or build a redundant remote database of orders on a mirrored machine. The Accepted Order Message also includes a day unique order reference number. Note that if a duplicate User and Token combination is received and all terms of the duped order are identical to the order as it was originally received, the duplicate is ignored.
Accept Order Message |
|||
Name |
Length |
Value |
Notes |
Order Message Header |
31 |
See above |
See Order Message Header. |
Order Action Specifier |
1 |
"A" |
Accept Order Action Specifier. Tells that this new order was accepted into Island. |
Order Reference Number |
9 |
numeric |
A unique reference number assigned by Island to the new order. Sequential, but not necessarily continuous. You can safely ignore this, but may wish to database it for problem resolution. It could also be used to cross reference orders into Island’s ITCH data feed. |
Buy/Sell Indicator |
1 |
alpha |
Can be "B" for a buy order, "S" for a sell order, "T" for Short Sale, "E" for Exempt Short Sale |
Shares |
9 |
numeric |
Total number of shares entered. |
Minimum Shares |
9 |
numeric |
Minimum executable shares. This is the smallest number of shares that can be executed from the total order. If Minimum equals Shares, the order is an All or None order. If Minimum equals 0, any number of shares can be executed. |
Stock |
6 |
alpha |
NASDAQ assigned stock symbol. Currently a four or five letter designator, but someday it may be longer. As soon as Island is able to do NYSE issues, three letter symbols will appear also. |
Price |
20 |
decimal numeric |
The limit price of the order. The price appears as a 9 digit whole number portion followed by a period followed by a 10 digit decimal portion. The whole number part is left padded with spaces, the decimal part is right filled with zeros. Example " 12.1250000000" represents 12 1/8. |
Time in Force |
5 |
numeric |
The number of seconds that this order will live before timing out. There are two special values for Time in Force, 99998 indicates that the order will live until the market close on the primary market, and 99999 indicates that the order will live until the end of the Island trading day. |
Firm |
4 |
alpha |
The NASDAQ Market Maker Identifier for the order entry firm. |
Principal/ Agency |
1 |
alpha |
Can be "P" for Principal trade or "A" for Agency Trade. For reporting purposes only. |
Displayed |
1 |
alpha |
Can be "N" for Invisible or "Y" for Visible. Invisible orders do not appear on the book, they are not reflected in the ISLD quote, and they have the lowest execution priority on the book. |
A Canceled Order Message informs you that an order has been reduced or canceled. This could be acknowledging a Cancel Order Request or it could be as a result of the order timing out. Note that a Cancel Order Message does not necessarily mean the entire order is dead, some portion of the order may still be alive.
Canceled Order Message |
|||
Name |
Length |
Value |
Notes |
Order Message Header |
31 |
See above |
See Order Message Header. |
Order Action Specifier |
1 |
"C" |
Canceled Order Action Specifier. Tells you that this order has been reduced or canceled. |
Decrement Shares |
9 |
numeric |
The number of shares decremented from the order. This could be any number less than or equal to the number of shares previously left in the order. This number is incremental, not cumulative. |
Remaining Shares |
9 |
numeric |
The number of shares currently left alive in this order. Sent only as a reference for double checking. If this is zero, the order is dead. |
Reason |
4 |
alpha |
The reason the order was reduced or canceled. Reasons include User Cancel, Timeout, and Halt. See Reason Specifiers below. |
Reduce Order Reason Specifiers |
|
Specifier |
Event Explanation |
"#USR" |
User requested cancel. You previously sent a Cancel Request Message on all or part of this order. |
"#IOC" |
Immediate or Cancel order. This order was originally sent with a timeout of zero, and no further matches were available on the book, so these remaining shares were immediately canceled out. |
"#TME" |
Timeout. This specifier lets you know that this order has timed out after the number of seconds specified in the Time in Force field elapsed. |
"#HLT" |
Halt. The stock was halted on its primary market so Island automatically canceled any open orders in that stock. The number of shares in the Decrement Shares field should exactly equal the number of pending shares left in the order. This order is now dead. |
"#SUP" |
Supervisory. This order was manually canceled or reduced by an Island supervisory terminal. This is usually in response to a user requested purge via telephone. |
An Executed Order Message informs you that all or part of an order has been executed.
Executed Order Message |
|||
Name |
Length |
Value |
Notes |
Order Message Header |
31 |
See above |
See Order Message Header. |
Order Action Specifier |
1 |
"E" |
Executed Order Action Specifier. Tells you that all or some of this order has been executed. |
Executed Shares |
9 |
numeric |
Incremental number of shares just executed. This could be any number less than or equal to the number of shares previously left in the order. |
Remaining Shares |
9 |
numeric |
The number of shares currently left alive in this order. Sent only as a reference for double checking. If this is zero, the order is dead. |
Execution Price |
20 |
decimal numeric |
The price at witch these shares were executed. The execution price will always be equal to or better than the entry price. The price appears as a 9 digit whole number portion followed by a period followed by a 10 digit decimal portion. The whole number part is left padded with spaces, the decimal part is right filled with zeros. Example " 12.1250000000" represents 12 1/8. |
Executing Firm |
4 |
alpha |
This field may contain the NASDAQ Market Maker Identifier of the executing firm if the order was executed by a non-Island subscriber. Otherwise, this field will contain blanks if the order was executed internally on Island. Note: Each subscriber firm must sign a "primary limit order system" agreement with Island to receive this data, otherwise this field will be blank on all executions. |
Liquidity Flag |
1 |
alpha |
Can be "A" if this execution added liquidity or "R" if this order removed liquidity. |
A Broken Trade Message informs you that a previously executed trade has been broken. The trade is no longer good and will not clear. The reason for the break is given.
Broken Trade Message |
|||
Name |
Length |
Value |
Notes |
Order Message Header |
31 |
See above |
See Order Message Header. |
Order Action Specifier |
1 |
"B" |
Broken Trade Specifier. Tells you that this order had been executed but is now broken. |
Reason |
4 |
alpha |
The reason the trade was broken. Left justified, blank filled. |
Broken Trade Reason Specifiers |
|
Specifier |
Event Explanation |
"#ERR" |
The trade was deemed clearly erroneous pursuant to the primary exchange’s administrative procedure. |
"#OUT" |
The trade was to far away from the inside market as defined by Island’s published parameters. Both sides were informed before the trade was broken. |
"#CON" |
By mutual consent. The two parties agreed to break the trade. |
"#SUP" |
The trade was manually broken by an Island supervisory terminal. |
Outbound Reject Messages tell you that an Enter Order or Cancel Order Inbound Message was rejected. These messages are not sequenced.
A Rejected Order Message may be sent in response to an Enter Order Message if for some reason the order can not be entered. The reason for the rejection is given. Since the order was never accepted, the order is dead. No further actions are permitted on this order. Unless the reason for rejection was Duped Token, the token of the rejected order may be reused if desired.
Your application should handle unknown Rejected Order Reason Specifiers resiliently and alert with the unknown reason.
Rejected Order Message |
|||
Name |
Length |
Value |
Notes |
Type |
1 |
"J" |
A single ASCII byte identifying this as an Outbound Reject Message. |
Reject Specifier |
1 |
"O" |
Rejected Order specifier. Tells you that was a reject of an order sent using the Enter Order Message. |
Order User |
4 |
alphanum |
This is just the User field that was transmitted with the order when entered. |
Order Token |
10 |
alphanum |
This is just the order Token field as was transmitted with the order when entered. |
Reason |
8 |
alpha |
The reason the order was rejected. Left justified, blank filled. |
Rejected Order Reason Specifiers |
|
Specifier |
Event Explanation |
"DUPETOKN" |
Duped Token. The specified token was already used today for this Account Name and user. Try again with a fresh token. |
"TESTMODE" |
This Account Name is configured for test mode and is not able to accept orders in non-TEST securities. |
"HALT" |
There is currently a trading halt on the primary exchange, no orders can be accepted. |
"MMID" |
This Account Name is not authorized to accept orders for the specified firm. |
"LOCK" |
This order, as entered, would lock or cross the NASDAQ inside market. |
"BUYSELL" |
The Buy Sell field must be "B", "S", "T", or "E". |
"SHARES" |
The Shares field must be all numeric. |
"MINIMUM" |
The Minimum field must be all numeric and less than or equal to the Shares field. |
"THRSHOLD" |
The number of shares entered must be less than the safety threshold on this Account. The threshold can be changed by the subscriber at any time. |
"STOCK" |
The Stock field must be a valid issue, tradable on Island. |
"PRICE" |
The Price filed must be a well formed numeric. |
"PA" |
The Principal/Agency field must be "P" or "A". |
"DISPLAY" |
The Displayed field must be "Y" or "N". |
"FIRM" |
The Firm entered must be authorized for this account name. To authorize additional firms, use the Island Service Bureau Agreement. |
"TIF" |
The TIF entered must be a positive number. |
A Reject Cancel Message is sent in response to a Cancel Order Message that could not be honored. The reason for the rejection is given. Note that there is no response to a too late to cancel condition. If a Cancel Order Message is sent for an order that has already been fully canceled or executed, it will be ignored. A Reject Cancel Message is only sent if you try to cancel an unknown order.
Reject Cancel Message |
|||
Name |
Length |
Value |
Notes |
Type |
1 |
"J" |
Identifies this as an Outbound Reject Message. |
Reject Specifier |
1 |
"K" |
Reject Cancel Specifier. Indicates that a Cancel Order Message was rejected. |
Order User |
4 |
alphanum |
The User field that was transmitted with the order when entered. |
Order Token |
10 |
alphanum |
This is just the order Token field as was transmitted with the order when entered. |
Reason |
4 |
alpha |
The reason the order could not be reduced or canceled. Left justified, blank filled. |
Can Not Cancel Reason Specifiers |
|
Specifier |
Event Explanation |
"#UNK" |
The requested order, as specified by the User and Token fields, was never accepted for this Account Name today. |
A Heartbeat Message is transmitted about once every 15 seconds during periods of inactivity. The Heartbeat Message’s primary purpose is to periodically let you know the current sequence number so you can detect missed messages even during times of low message traffic levels. Seeing the frequent Heartbeat Messages can also reassure your application of link integrity during times when there is no message traffic.
A Heartbeat message only indicates the sequence number of the most recently transmitted Outbound Sequenced Message, it does not increment that sequence number.
You must respond to a Heartbeat Message by immediately transmitting a Heart Beat Response Message. If you fail to respond to four consecutive Heartbeat Messages, your will receive a Goodbye Message and be disconnected.
The Time field in the Heartbeat Message is based on the local clock of the machine you are connected to. The Time field in Outbound Sequenced Messages is based in the Island global clock.
Heartbeat Message Format |
|||
Name |
Length |
Value |
Notes |
Type |
1 |
"H" |
Tells you that this is indeed a Heartbeat Message. |
Sequence |
10 |
numeric |
This is the Sequence Number of the most recently transmitted Outbound Sequenced Message. |
Time |
5 |
numeric |
This timestamp indicates when this Heartbeat Message was generated. Because Heartbeat Messages are not buffered or queued, this should be the exact time less transmission delays. It is expressed in seconds past midnight., so , for example 9:30:00AM would be (((9*60)+30)*60)=34200. |
Inbound messages are sent from your application to the OUCH machine. They are not sequenced. Inbound Messages may be repeated benignly. This gives you the ability to re-send any Inbound message if you are not sure weather it was received by your OUCH machine. For example, if your line goes down immediately after you send an Enter Order Message, you can safely re-send the message to any OUCH machine assigned to the same Account Name without worrying about duping the order. You could even technically send the same order down multiple lines simultaneously, although it's not recommended. If you ever feel like you've waited too long for a response to any Inbound Message, just re-send it.
The Enter Order Message lets you enter a new order into Island. Each new order must have a day unique User and Token combination for this Account Name. If you send a valid order, you should receive an Accepted Order Message. If you re-send an order with the same User and Token and identical terms, the duplicate order will be ignored. If you send an invalid order or an order with a previously used User and Token combination, you will receive a Rejected Order Message.
It is the subscriber's responsibility to comply with any applicable short sale rules, Island does not take any special actions to prevent short sales from being executed on a downtick.
Enter Order Message |
|||
Name |
Length |
Value |
Notes |
Type |
1 |
"O" |
Identifies this message an Enter Order Message type. |
Order User |
4 |
alphanum |
This is a freeform alphanumeric field. You can place any information you like here with the restriction that the combination of the User plus the Token must be day unique for each order entered. This field has lexical meaning in so far as the monthly Island bills are broken out on it. |
Order Token |
10 |
alphanum |
This is a freeform alphanumeric field. You can place any information you like here with the restriction that the combination of the User plus the Token must be day unique for each order entered. |
Buy/Sell Indicator |
1 |
alpha |
Can be "B" for a buy order, "S" for a sell order, "T" for Short Sale, "E" for Exempt Short Sale. This field is for reporting purposes only, Island does not prevent short sales from executing on a downtick. |
Shares |
9 |
numeric |
Total number of shares. |
Minimum |
9 |
numeric |
Minimum executable shares. This is the smallest number of shares that can be executed from the total order. If Minimum equals Shares, the order is an All or None order. If Minimum equals 0, any number of shares can be executed. Must be less than or equal to Shares. |
Stock |
6 |
alpha |
NASDAQ assigned stock symbol. Currently a four or five letter designator, but someday it may be longer. As soon as Island is able to do NYSE issues, three letter symbols will appear also. |
Price |
20 |
decimal numeric |
The limit price of the order. The price is a 9 digit whole number portion followed by a period followed by a 10 digit decimal portion. The whole number part must be left padded with spaces and the decimal part must be right filled with zeros. Example " 12.1250000000" represents 12 1/8. |
Time in Force |
5 |
numeric |
The number of seconds that this order will live before being timed out. There are two special values for Time in Force, 99998 indicates that the order should live until the market close on the primary market, and 99999 indicates that the order should live until the end of the Island trading day. |
Firm |
4 |
alpha |
This field should contain the all caps NASDAQ Market Maker Identifier for the order entry firm. One Account Name can enter orders for multiple firms in a Service Bureau configuration. |
Principal/ Agency |
1 |
alpha |
Can be "P" for Principal trade or "A" for Agency Trade. Indicates the nature of the account this trade benefits. Used for reporting purposes only. |
Displayed |
1 |
alpha |
Can be "Y" for Displayed or "N" for Invisible. Invisible orders are not visible on the Island book, they are not reflected in the ISLD quote, and they receive the lowest execution priority. |
The Cancel Order Message is used to request that a previously entered order be canceled or reduced. You can request that any number of shares be canceled. If you request a cancel on more shares than are currently remaining, all remaining shares will be canceled. If you request a cancel on less than the number of shares currently remaining, the order is reduced by the requested number of shares with the balance left open. If you request a cancel on an order that is no longer open, the request is ignored. If request a cancel on an order that had never been accepted, you will receive a Reject Cancel Message.
If you reduce and order such that the number of shares open is less than the Minimum, the Minimum will automatically be reduced to the current number of open shares. For example, if you entered a 200 share order with a 100 share minimum and than reduced that order by canceling 150 shares, the minimum would be adjusted to 50 shares.
Order Message Header |
|||
Name |
Length |
Value |
Notes |
Type |
1 |
"X" |
A single byte identifying this message as a Cancel Order Message. |
Order User |
4 |
alphanum |
This is the User I.D. that was transmitted with the order when entered. |
Order Token |
10 |
alphanum |
This is the order token as was transmitted with the order when entered. |
Shares |
9 |
numeric |
The number of shares you would like to cancel. If this is greater than the number of shares remaining open, all remaining shares will be canceled. |
Link Control Messages do not effect the current outbound sequence number.
The first thing you should do upon establishing a link layer connection to an OUCH machine is to request a login with a Login Request Message. Both the Account Name and Password fields will be assigned to you when you request an OUCH connection, both are case insensitive and may only contain alphanumerics.
You can re-log in even if you are currently logged in.
After you send a Login Request, you should wait for either a Welcome Message or a Goodbye Message and react accordingly.
Login Request Message Format |
|||
Name |
Length |
Value |
Notes |
Type |
1 |
"L" |
Tells the OUCH machine that this is a Login Request Message. |
Account Name |
6 |
alphanum |
This is your assigned OUCH Account Name. It is case insensitive. You must fill with spaces on the right. |
Password |
10 |
alphanum |
This is your assigned OUCH Password. It is case insensitive. You must fill with spaces on the right. |
After you send a Logout Request Message, you will receive a Goodbye Message. It’s a good idea to send a Logout Request Message before terminating your application.
Login Request Message Format |
|||
Name |
Length |
Value |
Notes |
Type |
1 |
"F" |
Tells the OUCH machine that this is a Logout Request Message. |
You must respond to each Heartbeat Message you receive by immediately transmitting a Heartbeat Response Message. If you miss four consecutive Heartbeat Response Messages, you will be disconnected with a Goodbye Message and will have to send another Login Request Message to get back in.
Heartbeat Response Message Format |
|||
Name |
Length |
Value |
Notes |
Type |
1 |
"I" |
Tells the OUCH machine that this is a Heartbeat Response. |
The Rewind Request Message empowers you to recover from message loss. When your OUCH machine receives a Rewind Request Message from you it will immediately begin re-sending messages to you starting with the sequence number you requested. It will keep sending these messages as fast as it can until it is all caught up to the current sequence number. This is nice because your application can treat these re-sent messages just as if they were virgin messages, no additional retransmission logic is necessary.
If you request a sequence number higher than the current sequence number, you will cancel any retransmissions in progress and will not receive any Outbound Sequenced Message until a new one is generated.
Rewind Request Message Format |
|||
Name |
Length |
Value |
Notes |
Type |
1 |
"W" |
This tells your OUCH machine that this is a Rewind Request Message. |
Sequence |
10 |
numeric |
This is the Sequence Number of the next message you wish to receive. |
During an OUCH connection, the machine can send these messages to you to alert you to changes in the connection status.
After sending a Login Request Message with the correct Account Name and Password fields, you will be greeted with a Welcome Message telling that your credentials have been accepted and that data will now begin to flow.
Welcome Message Format |
|||
Name |
Length |
Value |
Notes |
Type |
1 |
"W" |
Tells you that you are in. Your login was accepted and the data will begin to flow. |
Version |
5 |
numeric |
OUCH Version. This five digit numeric gives you the three digit major and two digit minor revision level of this machine. For example, " 100" would represent that this machine supports version 1.00 of the OUCH spec. This is for reference purposes only. |
Copyright |
60 |
text |
This is a freeform copyright message. |
A Goodbye Message is sent to let you know that your connection is being terminated. Once you get a Goodbye Message, you will have to send another Login request Message before sending or receiving any more data.
Goodbye Message Format |
|||
Name |
Length |
Value |
Notes |
Type |
1 |
"G" |
Tells you just got hung up on. |
Reason |
1 |
alpha |
This lets you know exactly why you are getting this Goodbye Message. See the table of Goodbye Reason Specifiers below to find out why you were hung up on. |
Goodbye Reason Specifiers |
|
Specifier |
Event Explanation |
"O" |
Requested. Logout Request Message received. |
"E" |
Expired. You failed to respond to four consecutive Heartbeat Messages with any Heartbeat Response Messages. Be more thoughtful next time. |
"J" |
Rejected. You sent a Login request Message, but your Account Name or Password was rejected. Check your spelling and try again. |
"N" |
Goodnight. It’s time to go home. Island is shutting down for the night. See you bright and early tomorrow. |
"M" |
Manual. An Island Supervisor terminal has manually logged you out. This will probably only happen at your own request. |
Debug Messages may be sent by the OUCH machine. These messages are intended to help debug problems and are meant for human consumption only. These messages should simply be ignored or maybe displayed by your software. A debug message always starts with a plus sign, is followed by a variable number of characters.
You can request to have debug messages sent to your Account Name during software development. Debug messages can give you a human readable reference to keep track of what's going on during your connection.
Debug Message Format |
|||
Name |
Length |
Value |
Notes |
Type |
1 |
"+" |
Identifies this as a Debug Message. Please ignore it. |
Text |
variable |
text |
This is a freeform English text message. |
The Minimum executable shares field sets the smallest number of shares of an order that can be executed. If an execution is only available for less than the Minimum, no shares will be executed. I included this feature to satisfy the complaints of subscribers who did not want to get odd lot executions.
Orders with a Minimum higher than 100 shares will not be reflected in the Island quote on NASDAQ.
Personally, believe that using Minimums is very bad trading. It is bad for the party who enters the order because is can prevent you from getting good executions. It is bad for the market because it places arbitrary restrictions that hamper accurate price discovery. It is bad for Island because it leads to situations where a buyer and seller can have matching or overlapping prices but are unable to consummate a trade.
Invisible orders are not displayed on the Island book, they are not disseminated on the Island data feeds, and they are not included in the Island quote. They are bad for price discovery.
An order that has either a Minimum or is Invisible has less priority that an order that does not, that is if an order with a restriction is entered before an unrestricted order at the same price, the unrestricted order will execute first.
Your software should default to no restrictions.
Here are some ideas of how I’d write an application to communicate with OUCH. If you can do it better, let me know and I’ll send you a free OUCH T-shirt.
You will need a database to hold all of your Island orders for today. Here’s a minimal example:
Sample ITCH Book Database |
|||
Name |
Length |
Value |
Notes |
Order User |
4 |
alphanum |
The user who entered this order |
Order Token |
10 |
alphanum |
Can be "B" for a buy order or "S" for a sell order. |
Open Shares |
9 |
numeric |
Total number of available shares in this order. |
You will need to be able to quickly locate records in this database by Order User + Order Token, so I’d put an index on that.
Here’s an example of one way to handle the program logic:
Set expected sequence number to 1.
Send Login Request Message.
Loop1:
Wait for receipt of incoming message with 15 second timeout.
If receive timed out
Go to Loop1.
If received a Welcome Message
Goto Loop2.
If received a Goodbye Message
Alert that login was rejected.
Exit.
Go to Loop1.
Loop2:
Wait for new incoming message with a one minute timeout.
If user requested program termination
Send Logout Request Message.
Exit.
If receive timed out
Alert that connection has been lost.
Exit.
If received a Heartbeat Message
Send a Heartbeat Response Message.
If received sequence number not equal to expected sequence number
Alert to lost messages.
Send Rewind Request Message with expected sequence number.
Go to Loop2.
If received a Goodbye Message
Alert that the connection terminated with the Reason Specifier.
Exit.
if received a debug message
Go to Loop2.
If received sequence number not equal to expected sequence number
Alert to lost messages.
Send a Rewind Request Message with expected sequence number.
Go to Loop1.
Increment expected sequence number.
[Process Message]
Go to Loop1.
To receive automatic notification of updates to this document, send an email to
list@josh.com with the line "subscribe ouch your_name_here" in the message body. You may also want to subscribe to the Island News list server by sending an email to list@josh.com with the line "subscribe island your_name_here" in the message body.
If you have any questions about this specification, just E-mail me at
josh@josh.com.
Thanks for reading my specification. I’ve read a lot of bad specs in my life and I’ve tried to make sure mine wasn’t one of them. I am very flexible and accept constructive criticism well, so please don’t hesitate to let me know about any changes you’d like to see.
-josh
The current OUCH software implementation has the following restrictions: