Represents a reference to an internally managed order object. Working with class order directly is not required as class order_ref exposes all necessary functionality for working with trading orders. Class order itself is undocumented. More...

#include <TSAOrder.h>

Inheritance diagram for tsa::order_ref:

Constructors and Assignment
	order_ref (void)
	Constructor for an uninitialized order_ref object ( defined() returns false).

	order_ref (order *order_ptr)
	Constructor for an initialized order_ref object. The object does not assume ownership of order_ptr and only increses its reference count. More...

	order_ref (const order_ref &other)
	Copy constructor, Both self and other now hold a reference on the same order object. More...

void	operator= (const order_ref &other)
	Assignment operator. Both self and other will subsequently hold each their own reference on the same order object. This operation will throw an exception if self references an active order (see is_active()). To avoid an exception, and if doing so makes sense, the release() member can be called to release the reference to the active order before assigning a new one. More...

	~order_ref (void)
	Destructor. Releases any reference.

Send, Cancel, Replace
void	send ()
	Sends the order to the trading platform. This member will throw an exception if the order status (see status()) is not order::created.

void	cancel (void)
	Sends a request to cancel the order. The order must be in an 'active' state (see is_active()). If the order status is already order::pending_cancel, then the function returns silently.

void	update_price (double new_price)
	Cancels the existing order and replaces it with a copy of the order with the new_price. More...

void	update_price (double new_price, double new_aux_price)
	Cancels the existing order and replaces it with a copy of the order with the new_price and new_aux_price. More...

void	update_quantity (quantity_t new_quantity)
	Cancels the existing order and replaces it with a copy of the order with the new_quantity. More...

void	release (void)
	Releases the order object and decrements its reference count. The order object can now be deleted by the instrument unless the reference count is not zero.

order *	get (void) const
	Returns a pointer to the order object. Throws an exception if self is not defined. See defined() More...

void	print (std::ostream &stream) const
	Prints a human readable description of the order. More...

Idendity and Tag
const std::string &	symbol (void) const
	Returns the symbol denoting the security (e.g. 'IBM', 'ES'). More...

const std::string &	exchange (void) const
	Returns the exchange name/acronym (e.g. 'NYSE', 'GLOBEX'). More...

identifier_t	id (void) const
	Returns the 'native' order ID, which is unique to the strategy. This ID is distinct from any ID assigned by any trading platform! More...

identifier_t	instrument_id (void) const
	Returns the ID of the instrument that created and manages the order. More...

order_ref	tag (const std::string &tag_string)
	Sets the order-tag which is a user defined string that is displayed in reports and can otherwise be used to identify an order or a group of orders. There is no requirement that an order tag be unique within a strategy. More...

const std::string &	tag (void) const
	Returns the 'tag' as previously set by order_ref::tag(const std::string& tag_string).

Properties
void	time_in_force (order::time_in_force tif, const date_time &expiry_time_point=date_time())
	Sets the order's time-in-force type. The time-in_force determines when orders are deleted by the trading platform or matching-engine. The default time-in-force is order::gtc (good til cancelled'. This default can be reset on an instrument basis via instrument::default_time_in_force(). More...

order::time_in_force	time_in_force (void) const
	Returns the value set via time_in_force(order::time_in_force tif, const date_time& expiry_time_point).

date_time	expiry_time_point (void) const
	Returns the expiry time-point as set by time_in_force(order::time_in_force tif, const date_time& expiry_time_point). Throw an exception if time-in-force is not order::user_defined. More...

double	price (void) const
	Returns the order price, which is either the 'stop' or the 'limit' price, depending on the order type.

void	fixed_fill_price (double fixed_fill_price)
	In some strategy simulations it may make sense to to force an transaction at a pre- determined price. For order accounting purposes the order will show as having been filled at the given fixed_fill_price. This functionality may allow users to mimic orders that can otherwise not be simulated. Responsibility lies with the user to ensure that prices are realistic. More...

double	fixed_fill_price (void) const
	Returns the price set via order_ref::fixed_fill_price(double). More...

quantity_t	quantity (void) const
	Returns the 'remaining' quantity of the order still to be bought or sold. More...

quantity_t	remaining (void) const
	identical to quantity(). Use whichever function name makes the most semantic sense given the situation. More...

quantity_t	size (void) const
	identical to quantity(). Use whichever function name makes the most semantic sense given the situation. More...

quantity_t	min_fill_quantity (void) const
	Returns the value previously set via min_fill_quantity(quantity_t quantity). More...

void	min_fill_quantity (quantity_t quantity)
	Sets the 'minimum fill quantity' which is the minimum number of units to be filled by this order. The order is to be left unfilled otherwise. Use this only if supported by the execution platform/matching-engine. More...

order::action	action (void) const
	Returns the order action (order::buy or order::sell). More...

order::type	type (void) const
	Returns the order type (order::stop, order::limit, order::market). More...

order::exec_interval	exec_interval (void) const
	Returns the orders 'execution interval' which determines when the order is supposed to be executed. You will not need to change this, as 'market' orders are always executed immediately at the open and 'stop' and 'limit' orders are always active until they expire or are cancelled. In some simulations it may make sense to use order::exec_interval::this_close to force an order to be filled at the close of the bar that most recently closed. This is only useful for end-of-day strategies where in practice a transaction could happend in the minutes before the session close. More...

double	aux_price (void) const
	Returns the auxiliary price, such as the 'limit' price of a 'stop limit' order.

bool	is_stop_limit (void) const
	Returns true if the order is a stop-limit order.

quantity_t	filled_quantity (void) const
	Returns the quantity that has so far been filled. Use the remaining() or quantity() members to check how many units still need to be filled. More...

date_time	last_fill_timestamp (void) const
	Returns the timestamp corresponding to when the order was filled. If the order is partially filled the function returns the most recent transaction timestamp. More...

date_time	create_timestamp (void) const
	Returns the timestamp of the bar on which the order was created.

int64_t	create_bar_ordinal (void) const
	Returns the ordinal number (see strategy::bar_count() of the bar on which the order was created. More...

int64_t	age_in_bars (void) const
	Returns the 'age' of the order in terms of the number of bars evaluated by the strategy since the order was created. More...

duration	age (void) const
	Returns the 'age' of the order as the duration between the current bar's timestamp and the order's creation timestamp. More...

Status
bool	defined (void) const
	Returns true if self references an order. More...

	operator bool (void) const
	Returns true if self references a active order. It is equivalent to order_ref::defined(). More...

bool	is_filled (void) const
	Returns true if the order was filled in its entirety. Returns false if order was only 'partially' filled or not filled at all.

bool	active (void) const

bool	is_active (void) const
	Returns true if the order is 'active'. An order is 'active' if its status is any of the following: More...

bool	is_partially_filled (void) const
	Returns true if the order if partially filled. More...

bool	cancelled (void) const
	Returns true if the order is confirmed cancelled.

bool	is_cancelled (void) const
	Returns true if the order is confirmed cancelled.

bool	marked_for_deletion (void) const
	Returns true if the order is market for deletion by the strategy. It will be deleted at the end of the current bar unless its reference count is non-zero.

order::status	status (void) const
	Returns the order status. See order::status.

order::status	prev_status (void) const
	Returns the previous order status, before the most recent change. See order::status. More...

bool	is_pending_submit (void)
	Returns true if the order has been transmitted but submission has not yet been confirmed (status::pending_submit). More...

bool	is_pre_submitted (void)
	Returns true if the order is confirmed pre-submitted (status::pre_submitted). More...

bool	is_acknowledged (void)
	Returns true if the order has either status::pre_submitted or status::submitted. More...

bool	is_submitted (void)
	Returns true if the order is confirmed submitted (status::submitted). More...

bool	is_pending_cancel (void)
	Returns true if a cancel request has been sent for the order (status::pending_cancel), but the cancellation is still unconfirmed. More...

bool	is_cancelled (void)
	Return true if the order is confirmed cancelled (status::cancelled) More...

Platform
void	update_status (order::status)

void	external_id (identifier_t)

identifier_t	external_id (void) const
	The session based order-id as notified by the execution platform. More...

identifier_t	permanent_id (void) const
	The 'permanent' order-id as notified by the execution platform. More...

Linking Orders (One-Cancels-Other)
void	one_cancels_other (order_ref &other_order)
	Sets a flag to cancel the remaining order if either self or other_order is filled.

void	oco (order_ref &other)
	Short name for order::one_cancels_other(). Same functionality.

void	on_fill_cancel (const order_ref &other_order)
	Sets a flag to cancel the other_order when self is filled. Self is not affected by any change in status of other_order. More...

void	on_fill_cancel (identifier_t order_id, identifier_t instrument_id)
	Sets a flag to cancel the order with the given order_id and instrument_id when self is filled. Self is not affected by any change in status of the given order. More...

bool	has_orders_to_cancel_on_fill (void) const
	Returns true if there are any linked orders to be cancelled when self is filled.

const std::vector< order::order_info > &	orders_to_cancel (void) const
	Returns a container with details on the related orders to be cancelled when self is filled.

Execution Interval
void	exec_interval (order::exec_interval execution_interval)
	Sets the order execution_interval.

Additional Inherited Members
Public Member Functions inherited from tsa::object
	object (void)
	Constructor.

virtual	~object (void)
	Destructor.

const char *	class_name (void) const
	Returns the class name as returned by the 'Real Time Type Information' (RTTI) mechanism. More...

bool	has_same_class_as (const object &other) const
	Returns true if self has the same type as other object. More...

Detailed Description

Represents a reference to an internally managed order object. Working with class order directly is not required as class order_ref exposes all necessary functionality for working with trading orders. Class order itself is undocumented.

Order Lifetime

The lifetime of orders is managed automatically. Orders are automatically destroyed once they become inactive (cancelled or filled). An order_ref object increments the reference count on the order object it refers to and prevents it from being destroyed, even when it becomes inactive. This is useful as it allows users to access order properties, such as the order status, even when the order is no longer active. Orders are not destroyed until the last order_ref object releases it. Use the order_ref::release() member to decrement the order's reference count.

Order Identification

In simuation, each order is simply assigned an ID, referred to as the 'native order-id'. This value can be retrieved via the order_ref::id() member. This number will look something like

The '1' at the beginning refers to the 'instrument' and the '1' at the end refers to the actual order number for that instrument. This scheme allows an immediate mapping of each order to the corresponding instrument, but this is otherwise not relevant to the user.

In live trading evironments, there are two more order ID's. One is the 'external order-id' as returned by order_ref::external_id(). This is the order number linked to the platform session. When the server connects to the platform, it is normally given the 'next valid order- id' from which the server derives new order-id's simply by incrementing this counter.Upon receiving a new order message, the server will immediately return a new message notifying the strategy of the corresponding 'external order-id'.

The platform may also make available a 'permanent order-id' that transcends the session. This id can be accessed via the order_ref::permanent_id() member.

Active vs. Inactive

An order is considered 'active' if its status, as returned by the order_ref::status() member is any of the following:

pending_submit
pre_submitted
submitted
pending_cancel
pending_cancel_replace
paused

An order is considered 'inactive' if its status is any of the following:

created
filled
cancelled
rejected

Orders are thus considered 'active' from the moment they are transmitted to the moment they are confirmed 'filled', confirmed 'rejected' or confirmed 'cancelled'.

Order Assignment

You cannot assign a new order to an order_ref that holds an active order! Doing so would throw an exception. Use the order_ref::is_active() member to check whether an order is active. This is to prevent the strategy from losing track of active working orders. Once an order reference is lost, the only way to get a handle on an order is via its order-ID, which, unless it was explicitly saved somewhere, is not available. If you want to force assignment of a new order(ref) then invoke the order_ref::release() first. This decrements the reference count on the order and resets the order_ref object.

Defined vs. Undefined

Use the order_ref::defined() member to check if the order_ref object is initialized at all. order_ref also has a cast operator to type 'bool'.

order_ref o;
if(o.define()){
//...
}

can also be written simply as:

order_ref o;
if(o){
//...
}

Order Transmission

By default, orders are transmitted immediately upon creation. Once transmitted, most order properties cannot be changed. Some order properties, those that are not relevant to the matching engine, can be changed at any time. One such example is the user 'tag' property set via the order_ref::tag() member. The user tag is a way to name an orders or even group multiple order by a common name.

In order to prevent immediate order transmission, an alternate set of order functions is available. These have function names with the postfix '_order'.

order_ref o;
instrument ibm;
//...
o = ibm.buy_order(100);
assert(!o.is_active()); //not sent yet
o.min_fill_quantity(10);
o.send();
assert(o.active());

Note:

Order objects, and thus also order_ref objects, can represent all types of orders ('limit', 'stop', 'stop limit' and 'market') and hence not all available properties are relevant to all order types!

Constructor & Destructor Documentation

tsa::order_ref::order_ref ( order * order_ptr )

Constructor for an initialized order_ref object. The object does not assume ownership of order_ptr and only increses its reference count.

Parameters

[in,out] order_ptr If non-null, the order pointer.

tsa::order_ref::order_ref ( const order_ref & other )

Copy constructor, Both self and other now hold a reference on the same order object.

Parameters

other The other order order_ref.

Member Function Documentation

order::action tsa::order_ref::action ( void ) const

Returns the order action (order::buy or order::sell).

Returns: An order::action.

duration tsa::order_ref::age ( void ) const

Returns the 'age' of the order as the duration between the current bar's timestamp and the order's creation timestamp.

Returns: A duration.

int64_t tsa::order_ref::age_in_bars ( void ) const

Returns the 'age' of the order in terms of the number of bars evaluated by the strategy since the order was created.

Returns: An int64_t.

int64_t tsa::order_ref::create_bar_ordinal ( void ) const

Returns the ordinal number (see strategy::bar_count() of the bar on which the order was created.

Returns: The new bar ordinal.

bool tsa::order_ref::defined ( void ) const

Returns true if self references an order.

Returns: true if it does, else false.

const std::string & tsa::order_ref::exchange ( void ) const

Returns the exchange name/acronym (e.g. 'NYSE', 'GLOBEX').

Returns: A std::string&.

order::exec_interval tsa::order_ref::exec_interval ( void ) const

Returns the orders 'execution interval' which determines when the order is supposed to be executed. You will not need to change this, as 'market' orders are always executed immediately at the open and 'stop' and 'limit' orders are always active until they expire or are cancelled. In some simulations it may make sense to use order::exec_interval::this_close to force an order to be filled at the close of the bar that most recently closed. This is only useful for end-of-day strategies where in practice a transaction could happend in the minutes before the session close.

Returns: An order::exec_interval.

date_time tsa::order_ref::expiry_time_point ( void ) const

Returns the expiry time-point as set by time_in_force(order::time_in_force tif, const date_time& expiry_time_point). Throw an exception if time-in-force is not order::user_defined.

Returns: A date_time.

identifier_t tsa::order_ref::external_id ( void ) const

The session based order-id as notified by the execution platform.

Returns: An identifier_t.

quantity_t tsa::order_ref::filled_quantity ( void ) const

Returns the quantity that has so far been filled. Use the remaining() or quantity() members to check how many units still need to be filled.

Returns: A quantity_t.

void tsa::order_ref::fixed_fill_price ( double fixed_fill_price )

In some strategy simulations it may make sense to to force an transaction at a pre- determined price. For order accounting purposes the order will show as having been filled at the given fixed_fill_price. This functionality may allow users to mimic orders that can otherwise not be simulated. Responsibility lies with the user to ensure that prices are realistic.

Parameters

fixed_fill_price The fixed fill price.

double tsa::order_ref::fixed_fill_price ( void ) const

Returns the price set via order_ref::fixed_fill_price(double).

Returns: A double.

order * tsa::order_ref::get ( void ) const

Returns a pointer to the order object. Throws an exception if self is not defined. See defined()

Returns: Valid order pointer.

identifier_t tsa::order_ref::id ( void ) const

Returns the 'native' order ID, which is unique to the strategy. This ID is distinct from any ID assigned by any trading platform!

Returns: An identifier_t.

identifier_t tsa::order_ref::instrument_id ( void ) const

Returns the ID of the instrument that created and manages the order.

Returns: An identifier_t.

bool tsa::order_ref::is_acknowledged ( void )

Returns true if the order has either status::pre_submitted or status::submitted.

Returns: true if acknowledged, false if not.

bool tsa::order_ref::is_active ( void ) const

Returns true if the order is 'active'. An order is 'active' if its status is any of the following:

pending_submit
pre_submitted
submitted
pending_cancel
pending_cancel_replace
paused

bool tsa::order_ref::is_cancelled ( void )

Return true if the order is confirmed cancelled (status::cancelled)

Returns: true if cancelled, false if not.

bool tsa::order_ref::is_partially_filled ( void ) const

Returns true if the order if partially filled.

Returns: true if partially filled, false if not.

bool tsa::order_ref::is_pending_cancel ( void )

Returns true if a cancel request has been sent for the order (status::pending_cancel), but the cancellation is still unconfirmed.

Returns: true if pending cancel, false if not.

bool tsa::order_ref::is_pending_submit ( void )

Returns true if the order has been transmitted but submission has not yet been confirmed (status::pending_submit).

Returns: true if pending submit, false if not.

bool tsa::order_ref::is_pre_submitted ( void )

Returns true if the order is confirmed pre-submitted (status::pre_submitted).

Returns: true if pre submitted, false if not.

bool tsa::order_ref::is_submitted ( void )

Returns true if the order is confirmed submitted (status::submitted).

Returns: true if submitted, false if not.

date_time tsa::order_ref::last_fill_timestamp ( void ) const

Returns the timestamp corresponding to when the order was filled. If the order is partially filled the function returns the most recent transaction timestamp.

Returns: A date_time.

quantity_t tsa::order_ref::min_fill_quantity ( void ) const

Returns the value previously set via min_fill_quantity(quantity_t quantity).

Returns: A quantity_t.

void tsa::order_ref::min_fill_quantity ( quantity_t quantity )

Sets the 'minimum fill quantity' which is the minimum number of units to be filled by this order. The order is to be left unfilled otherwise. Use this only if supported by the execution platform/matching-engine.

Parameters

quantity The quantity.

void tsa::order_ref::on_fill_cancel ( const order_ref & other_order )

Sets a flag to cancel the other_order when self is filled. Self is not affected by any change in status of other_order.

Parameters

other_order The order to cancel.

void tsa::order_ref::on_fill_cancel	(	identifier_t	order_id,
		identifier_t	instrument_id
	)

Sets a flag to cancel the order with the given order_id and instrument_id when self is filled. Self is not affected by any change in status of the given order.

Parameters

order_id	Identifier of the order to cancel.
instrument_id	Identifier of the instrument owning the order to cancel.

tsa::order_ref::operator bool ( void ) const

Returns true if self references a active order. It is equivalent to order_ref::defined().

Returns: true if it does, else false.

void tsa::order_ref::operator= ( const order_ref & other )

Assignment operator. Both self and other will subsequently hold each their own reference on the same order object. This operation will throw an exception if self references an active order (see is_active()). To avoid an exception, and if doing so makes sense, the release() member can be called to release the reference to the active order before assigning a new one.

Parameters

other The other order_ref.

tsa::identifier_t tsa::order_ref::permanent_id ( void ) const

The 'permanent' order-id as notified by the execution platform.

Returns: An identifier_t.

order::status tsa::order_ref::prev_status ( void ) const

Returns the previous order status, before the most recent change. See order::status.

Returns: The order::status.

void tsa::order_ref::print ( std::ostream & stream ) const

Prints a human readable description of the order.

Parameters

[in,out] stream The stream.

quantity_t tsa::order_ref::quantity ( void ) const

Returns the 'remaining' quantity of the order still to be bought or sold.

Returns: A quantity_t.

quantity_t tsa::order_ref::remaining ( void ) const

identical to quantity(). Use whichever function name makes the most semantic sense given the situation.

Returns: A quantity_t.

quantity_t tsa::order_ref::size ( void ) const

identical to quantity(). Use whichever function name makes the most semantic sense given the situation.

Returns: A quantity_t.

const std::string & tsa::order_ref::symbol ( void ) const

Returns the symbol denoting the security (e.g. 'IBM', 'ES').

Returns: A std::string&.

order_ref tsa::order_ref::tag ( const std::string & tag_string )

Sets the order-tag which is a user defined string that is displayed in reports and can otherwise be used to identify an order or a group of orders. There is no requirement that an order tag be unique within a strategy.

Parameters

tag_string String describing the order.

Returns: An order_ref.

void tsa::order_ref::time_in_force	(	order::time_in_force	tif,
		const date_time &	expiry_time_point = `date_time()`
	)

Sets the order's time-in-force type. The time-in_force determines when orders are deleted by the trading platform or matching-engine. The default time-in-force is order::gtc (good til cancelled'. This default can be reset on an instrument basis via instrument::default_time_in_force().

Parameters

tif	time-in-force value.
time_point	The time point the order expires. Set this value only if the time_in_force is set to order::user_defined.

order::type tsa::order_ref::type ( void ) const

Returns the order type (order::stop, order::limit, order::market).

Returns: An order::type.

void tsa::order_ref::update_price ( double new_price )

Cancels the existing order and replaces it with a copy of the order with the new_price.

Parameters

new_price The new price.

void tsa::order_ref::update_price	(	double	new_price,
		double	new_aux_price
	)

Cancels the existing order and replaces it with a copy of the order with the new_price and new_aux_price.

Parameters

new_price	The new price.
new_aux_price	The new auxiliary price.

void tsa::order_ref::update_quantity ( quantity_t new_quantity )

Cancels the existing order and replaces it with a copy of the order with the new_quantity.

Parameters

new_quantity The new quantity.

Constructors and Assignment

Send, Cancel, Replace

Idendity and Tag

Properties

Status

Platform

Linking Orders (One-Cancels-Other)

Execution Interval

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation