O*U*C*H

Version 0.5 - DRAFT

 

By Joshua Levine

September 17, 1997

  1. Overview

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.

    1. Architecture
    2. 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.

       

       

    3. Fault Redundancy
    4. 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.

       

    5. Service Bureau Configuration
    6. 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.

       

    7. Development Guidelines

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.

  1. Access
  2. 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.

     

     

  3. Outbound Sequenced Messages
  4. 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.

    1. Outbound Sequenced Message Header
    2. 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.

      1. Event Messages
      2. 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.

         

         

         

      3. Text Messages
      4. 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.

         

      5. Order Messages
      6.  

        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.

         

         

         

        1. Accepted Order Message
        2.  

          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.

           

           

           

        3. Canceled Order Message
        4.  

          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.

           

           

           

           

        5. Executed Order Message
        6.  

          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.

           

           

           

        7. Broken Trade Message

       

      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.

       

       

       

    3. Outbound Reject Messages
    4. Outbound Reject Messages tell you that an Enter Order or Cancel Order Inbound Message was rejected. These messages are not sequenced.

       

        1. Rejected Order Message
        2.  

          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.

           

           

           

        3. Reject Cancel Message

       

      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.

       

    5. Heartbeat Message

    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.

  5. Inbound Messages
  6.  

    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.

     

     

    1. Enter Order Message
    2. 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.

    3. Cancel Order Message
    4. 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.

       

    5. Inbound Link Control Messages
    6. Link Control Messages do not effect the current outbound sequence number.

      1. Login Request Message
      2. 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.

         

         

         

      3. Logout Request Message
      4. 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.

         

      5. Heartbeat Response Message
      6. 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.

         

      7. Rewind Request Message

       

      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.

       

       

       

    7. Outbound Un-Sequenced Messages
    8. During an OUCH connection, the machine can send these messages to you to alert you to changes in the connection status.

       

      1. Welcome Message
      2. 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.

         

      3. Goodbye 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.

     

  7. Debug Messages
  8. 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.

     

  9. On Minimums and Invisible Orders
  10. 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.

  11. Implementation Ideas
  12.  

    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.

     

    1. Database Detail
    2. 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.

       

       

    3. Processing Engine Pseudo-code

    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.

     

     

  13. Support
  14.  

    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

  15. Current Restrictions
  16.  

    The current OUCH software implementation has the following restrictions:

     

    1. Minimum share orders are currently rejected with a reason of "SHARES", you must use a minimum of zero. I have still not come up with a fair and computationally efficient rule for executing minimum share orders. If you have any ideas, please send me an e-mail.
    2. Exempt short sales are currently rejected with a reason of "BUYSELL". Only regular short sales are accepted. Support for exempt short sales will be added in the next software release.
    3. Invisible Orders are currently rejected with a reason of "DISPLAY". Only visible orders are accepted. Support for invisible orders will be added in the next software release.
    4. Prices finer than 1/256ths will be rejected with a reason of "PRICE". While Island can process numbers down to 10 decimal places, I've added this check just to be safe. I will permit full decimalization as soon as I am sure that I have a robust way to report these trades to NASDAQ.
    5. Island does not currently reject locking/crossing orders. The production system will optionally reject any order that would lock/cross the market.

     

  17. Revision History
    1. Version 0.3 - 8/4/97
      1. Initial dissemination to a select few developers.
    2. Version 0.4 - 9/15/95
      1. Miscellaneous spelling and format fixes.
      2. Changed all references to an OUCH port to OUCH machine; there was too much confusion with OUCH ports and TCP/IP port numbers.
      3. Added to Section 4.0 to make it clear that Inbound Messages are not sequenced, they can and should be resent if necessary.
      4. Made the Reject Order and Reject Cancel messages un-sequenced. This makes more sense conceptually especially when dealing with mirrored machines. A rejected order (or cancel) was never accepted by Island; it has no reference number and should not have a sequence number either. If one machine of a mirrored pair enters an order that is rejected, the other machine will get no messages about the rejected order. This makes sense because the rejected order did not effect the state of either machine in any way. It is as if rejected orders never existed from Island's point of view. You can re-send a rejected order as many times as you like and you will keep getting identical reject messages back.
      5. Added Debug Messages to help people see what was going on. These also make it very nice if you Telnet into an OUCH machine because you can see what's going on.
      6. Added a line feed at the end of all outbound messages. If you've already coded to just returns, you can just ignore out any line feeds. I ignore them on incoming messages, so needn't send them either. I know it wastes a little bandwidth, but it's worth it. Now people can use line based functions to read and parse the stream and everything looks so nice and neat when you Telenet into an OUCH port. It's all about aesthetic, man.
    3. Version 0.5 - 9/17/97
      1. Changed the Reason field on the Broken Trade Message. It is now 4 long rather than 8 and the Reason Specifiers have been condensed. I did this to be more consistent with the Reduce Order Reasons. I also reduced the length of the reason field on the Reject Cancel Message.
      2. Added the legend that "malformed numbers produce undefined results" under Architecture. For now, I do a standard atoi() type conversion so trailing spaces are tolerated, but that may change in the future.
      3. Added a new Reject Order Reason "THRSHOLD" that indicates the number of shares in this order exceeds the preset threshold for this Account.
      4. Made the Firm Field in the Enter Order message mandatory. Before you could leave this filed blank and you would get the default firm for this Account. This way is a double check to make certain that you are entering the right orders in the firm on the right account. If this is a problem, I can override it from here, but your software should know what firm it's entering orders for.
      5. Added Current Restrictions section to detail the limitations of the current OUCH software revision.
      6. Added word "incremental" to the description of the Executed Shares field of the Executed Order message to make it clear that this is the number of shares just executed, not the cumulative number of shares executed.
      7. Removed the paragraph that said that you could send a Rewind Request Message with a sequence number of zero. This didn't add any functionality above requesting a rewind to Sequence Number 1, so I took it out. This way we'll have zero for a special use in the future.