13. Appendix

This appendix collects the reference tables that the preceding chapters rely on: the numeric values of every enumeration exported by tse_enums.h, tse_duration.h and tse_log.h; the complete name map from every user-facing action to its C, C++ and Python spelling; the status and last-error contract shared by all three surfaces; the labels, identifiers, boundary conventions and fixed buffer capacities of the C ABI; the schema of the SQLite table into which the blotter journals executed trades; and the defaults that the two wrappers apply on top of a default-free C surface. Sections A through D and F are taken from the current headers of ABI generation 6; section E has no header behind it and is taken from the engine's own blotter SQL, which is internal to the library.

A. Enumerations

Enumeration values are identical across all three surfaces; only the spelling differs. The C constants live in the named headers; the C++ wrapper mirrors each as an enum class in namespace tse with the same lower-snake enumerator names (exceptions are noted per table); the Python wrapper mirrors each as an IntEnum class in module tse with PascalCase member names. For string forms the library exports tse_instrument_to_string, tse_underlying_to_string, tse_venue_to_string, tse_side_to_string, tse_cmp_to_string, tse_price_type_to_string, tse_quantity_mode_to_string, tse_tif_to_string, tse_txn_type_to_string and tse_priority_to_string in tse_enums.h, plus tse_duration_to_string in tse_duration.h. In the tables below the C prefix named in each lead is stripped from the constant column.

TseInstrument (tse_enums.h, prefix tse_instrument_) — C++ tse::Instrument, Python tse.Instrument.

TseUnderlying (tse_enums.h, prefix tse_underlying_) — C++ tse::Underlying, Python tse.Underlying.

TseVenue (tse_enums.h, prefix tse_venue_) — C++ tse::Venue, Python tse.Venue; the enumerator names are identical on all three surfaces.

TseSide (tse_enums.h, prefix tse_side_) — the full mirror of the engine's side/quotation enumeration; the numeric values are the engine codes, and long carries the aliases bid/buy while short carries ask/sell. C++ tse::Side spells the keyword collisions long_ and short_; Python tse.Side uses Long and Short.

TseCmp (tse_enums.h, prefix tse_cmp_) — C++ tse::Cmp, Python tse.Cmp. Directions: ge >=, lt <, gt >, le <=, eq =, ne !=.

TsePriceType (tse_enums.h, prefix tse_price_) — C++ tse::PriceType; the Python class is named tse.Price.

TseTxnType (tse_enums.h, prefix tse_txn_) — the transaction kind of a multileg leg, engine codes. C++ tse::TxnType, Python tse.TxnType (Enter, Exit, StopLoss, StopLossTrailing, TakeProfit, Chaining, Forced, TakeProfitTrailing).

TsePriority (tse_enums.h, prefix tse_priority_) — the order priority of a multileg leg, engine codes. C++ tse::Priority, Python tse.Priority (NonReplaceable for the third value).

TseQuantityMode (tse_enums.h, prefix tse_quantity_) — C++ tse::QuantityMode; the Python class is named tse.Quantity, with FromSignal for the last value.

TseTif (tse_enums.h, prefix tse_tif_) — C++ tse::Tif, Python tse.Tif.

TseMode (tse_enums.h, prefix tse_mode_) — the account licensing mode set by tse_account_set_mode. C++ tse::Mode, Python tse.Mode.

TseDuration (tse_duration.h, prefix tse_duration_) — C++ tse::Duration with identical spellings; Python tse.Duration in PascalCase (Duration.FiveSeconds, Duration.ThirtyMinutes, ...).

TseLogLevel (tse_log.h, prefix tse_log_) — C++ tse::LogLevel ends in none; the Python member for value 6 is spelled LogLevel.Off.

The remaining exported enumerations are declared next to the surface they belong to. TseStatus (tse_types.h) is tabulated in the next section of this appendix; the others are tabulated in their own chapters: TseStorageRegime and TseCurrency in tse_types.h; TseMdType in tse_marketdata.h; TseRuleType in tse_rule.h; TseRiskPolicyType in tse_risk.h; TseOhlcvField and TseBidAskField in tse_execution.h; TseBookLevelKind, TseBookMessageKind and TseBookMissingLevel in tse_book.h.

B. Name map

The map below covers every user-facing action of the export layer. In the C++ column an unqualified name is a method of tse::Account; in the Python column an unqualified name is a method of tse.Account; a Market., Execution., Book., ExPost. or Storage. prefix marks the holder object, and a tse:: or tse. prefix marks a free function of the namespace or module. Where a family of C functions differs only in a type or kind suffix, the row writes the varying part as <t> or <kind> and lists the admissible values.

Library, versions and diagnostics.

Account and contracts.

Market data.

Execution.

Inputs and patterns.

Rules.

Robot lifecycle and bulk actions.

Results and external-trade booking.

Portfolio, reset and risk policies.

Order books.

ex_post statistics and features.

Persistence.

Data loading, timeserie toolbox and grid search.

C. Statuses and errors

Every C entry point that can fail returns TseStatus; handle-creating functions (tse_account_create, tse_market_create, tse_exec_create_simulator, tse_exec_create_custom, tse_book_create, tse_ex_post_create) return the handle directly, or NULL on error. Every C entry point is wrapped in a noexcept try/catch inside the library: no exception ever crosses the C boundary. A failure comes back as tse_error or a NULL handle, and the reason is a human-readable text waiting in the last-error channel that owns the failed call.

TseStatus (tse_types.h) — the two constants of the status type.

Each area of the library has exactly one last-error channel, scoped to match the lifetime of what it reports on.

The C++ wrapper turns every failed status into an exception. It throws exactly one type, tse::Error, whose message carries the last-error text of the channel the failed call belongs to; the pre-account entry points stay exception-free (tse::setInitialParams is noexcept and returns bool, with the detail in tse::lastInitError()).

The Python wrapper raises tse.TseError under the same contract, and mirrors the pre-account channels as module-level functions tse.last_init_error(lib) and tse.last_csv_error().

struct Error final : std::runtime_error {
	using std::runtime_error::runtime_error;
};

try:
    account = tse.Account("research", tse.StorageRegime.Mem)
    account.start("robot")
except tse.TseError as error:
    print(error)

D. Labels, identifiers and capacities

Labels and identifiers. Entities are addressed by string labels: the account, the market adapters, the execution, the Inputs, the Patterns, the Rules and the Robots are all created under a label and referenced by it everywhere else — a Pattern names the Inputs it observes, a Rule names its Pattern, a Robot names its Rules. Contracts are the exception: they are addressed by symbol, or by the numeric uint64_t contract id returned by tse_add_contract_id / tse_get_contract_id. In a record that carries both, such as TseRetained, a contractId of zero means addressing by symbol.

Fixed string capacities. At the C boundary these strings live in fixed-size fields: labels occupy 64 bytes (63 useful characters); symbols and order identifiers occupy 32 bytes (31 useful characters). The useful length is one less than the capacity because of the NUL terminator. Oversized values fail loud: the call is rejected on input and the owning last-error channel carries the diagnostic — "the value exceeds the boundary capacity (63 characters for labels, 31 for symbols and identifiers)". Nothing is silently truncated.

The two order identifiers. An order carries two identifiers with distinct birthplaces. The client order id is minted on the client side when the order is created; the engine's intended-trade record carries it, the fill callback of a custom execution receives it in TseOrder, and tse_exec_apply_fill addresses fills by it. The broker order id is minted at the execution point — by the Simulator, or by the venue behind a custom execution — when the order is accepted or filled; the engine's executed-trade record carries it. The retained trade, journaled by the blotter, carries both, which is exactly the identifier block that recurs across TseTrade and TseRetained.

Capacity-in / count-out. tse_get_trades, tse_get_summaries and tse_book_levels_top share one protocol: pass the capacity of the output array in *inoutCount; on return it holds the number actually written; pass a null output pointer to query the required count without writing. When the capacity is smaller than the number of available elements the surplus is silently not written — query the count first. The wrappers hide the round trip entirely.

Count-then-buffer. The timeserie toolbox (tse_timeserie.h) and the ex_post feature readers (tse_ex_post.h) use the sibling convention: a NULL output buffer makes the call store the required element count (for features, the row count into *inoutRowCount) and touch nothing else.

Zero time bounds. In tse_get_trades, and fixed as part of the ABI: a zero fromNanoseconds means the 1970 epoch and a zero toNanoseconds means the 2100 epoch, so zero bounds mean "no bound" and 0, 0 selects everything.

Whole-row truncation of matrix extraction. tse_csv_reader_read_matrix_by_name / _by_index return a row-major flat buffer whose capacity and written count are in double elements; on a short buffer truncation drops whole rows only, so the written count always stays a multiple of the column count.

structSize stamping. TseBookMessage, TseCsvOptions and TseCsvWriterOptions carry a leading structSize field that the caller must set to sizeof of the struct; the C++ and Python wrappers fill it automatically.

Borrowed strings. A char const* returned by a CSV reader or writer handle stays valid until the next read on the same handle or its destruction. tse_last_csv_error is thread-local and stays valid until the next load on the same thread. tse_ex_post_robot_label copies into a caller buffer, NUL-terminated and truncated to the given capacity; tse_csv_reader_cell_* writes up to capacity-1 bytes plus a NUL, and with a NULL output stores the cell length instead.

Absent-value markers. TSE_ABSENT_HIGH_PRICE ((double)INT64_MIN) and TSE_ABSENT_LOW_PRICE ((double)INT64_MAX) mark a position with no observed extreme yet, with the matching timestamps written as zero (tse_trades.h); C++ mirrors them as tse::absentHighPrice / tse::absentLowPrice. TSE_ABSENT_MULTIPLE (zero) marks a placeholder exposure node in TsePositionState.multiple (tse_portfolio.h).

Versions. tse_abi_version() returns 6; the robot recipe written by tse_save uses persistence schema version 3, and a mismatched schema is rejected on load with a diagnostic.

Reading the two identifiers off a retained trade:

std::vector<tse::Trade> const trades {account.getTrades()};
std::string const
	client {trades.front().clientOrderId},
	broker {trades.front().brokerOrderId};

for trade in account.get_trades():
    print(trade.clientOrderId.decode(), trade.brokerOrderId.decode())

The C capacity-in / count-out round trip, and what the wrappers do in its place:

size_t count = 0;
tse_get_trades(account, 0, 0, NULL, NULL, &count);

TseTrade* trades = calloc(count, sizeof(TseTrade));
tse_get_trades(account, 0, 0, NULL, trades, &count);

free(trades);

std::vector<tse::Trade> const trades {account.getTrades()};

trades = account.get_trades()

E. The retained trades table

An account created under a storage regime that includes the database — tse_storage_regime_db, C++ tse::StorageRegime::db, Python tse.StorageRegime.Db — journals every executed trade into a SQLite file. The file lives in the data folder passed as TseInitialParams.dataFolderPath to tse_set_initial_params; when no data folder has been configured the engine places it next to the running executable. Its name is the account label followed by _Blotter_retained_trades.sqlite3.db. The trades themselves occupy one table, retained_trades, and this section is its schema, so that a client can open the file and query it with plain SQL instead of going through the API.

The columns fall into six groups. The order identifiers are client_order_id and broker_order_id, the pair described above under labels and identifiers. The labels are rule_label, which is stored inline, robot_id, which is a foreign key into the strategies table whose label column holds the robot label, and contract_id, which is the numeric contract id rendered as decimal text and is a foreign key into the contracts table whose name column holds the symbol. The timestamps are ts_mkt_event and ts_execution, both nanoseconds since the 1970 epoch. The price and quantity block is price, quantity, fee and booked_pl together with the codes that classify the trade and the order behind it. The contract-exposure snapshot taken at the moment of the trade is the prev_contract_exposure_* family plus the four position-extreme columns. The portfolio-exposure snapshot is the prev_portfolio_exposure_* family.

Every *_code column is declared as a foreign key into a small seeded lookup table that names its values, and the numbers are the same engine codes tabulated in the enumerations section. Three of those tables are seeded short of the enumeration they name, which matters the moment a query joins on them. side_types, referenced by all five side columns, holds exactly three rows — 1 neutral, 2 long_, 4 short_, the two directional names carrying the trailing underscore of the C++ keyword workaround — and has no row for the undefined side, code 0. price_types holds 0 undefined, 1 market and 2 limit, and has no row for general, code 3. quantity_types holds 0 undefined, 1 all and 2 fixed, and has no row for from_signal, code 3. The remaining tables cover their enumerations in full: book_mode_types (0 undefined, 1 main, 2 split), execution_types (0 undefined, 1 ongoing, 2 completed_full, 4 completed_partial), tif_types matching TseTif and priority_types matching TsePriority. Because the seeding is partial, resolve a code with a LEFT JOIN: an inner join on side_types, price_types or quantity_types silently drops every row whose code has no lookup row.

The table carries one compound uniqueness constraint, written out at the end of this section. The insert is written as ON CONFLICT ... DO NOTHING against exactly this tuple, which makes journaling idempotent: one executed trade cannot be written twice. A fill that reaches the blotter a second time — a replayed message, a reconnect that redelivers the same execution report, a repeated run over the same data into the same file — matches the constraint and is dropped instead of inflating the trade count and double-counting booked_pl. Note what the tuple deliberately omits: the two order identifiers and the price play no part in it, so a duplicate is recognized even when the broker restates an identifier. Indexes cover the two timestamps, the rule label, the contract and the robot, each alone and in the combinations a reporting query normally uses, so time-ranged and per-robot selections stay cheap on a large file.

The same records reach the caller without any SQL through tse_get_trades, which fills an array of TseTrade — C++ getTrades, Python get_trades. TseTrade carries the identifiers, the labels, both timestamps, the price and quantity block and both exposure snapshots, resolving contract_id back into the symbol character field and robot_id back into robotLabel; rule_label, stored inline in the table, is copied straight into ruleLabel with nothing to resolve. Four column families stay in the table only: the exchange-rate pair, the order-detail codes price_type_code, tif_type_code, quantity_type_code and priority_type_code, which are exposed instead through TseRetained, the prev_contract_exposure_market_price_seeded flag, and prev_portfolio_exposure_market_value_side.

The constraint reads:

UNIQUE(contract_id, rule_label, robot_id, ts_mkt_event, ts_execution,
       quantity, book_mode_code, pos_side_code,
       exchange_rate_numerator, exchange_rate_denominator)

F. Wrapper defaults

The C ABI itself carries no defaults: every struct field and every argument is required, and coreId parameters are mandatory (a negative value runs the component without a separate pinned thread). The two wrappers reintroduce the following defaults — everything not listed here remains required on all three surfaces.

Note the one asymmetry in the CSV readers: the C++ CsvReader default (CsvOptions {}) assumes a header row, while the Python CsvReader default (has_header=False), like the C-level tse_csv_reader_create(NULL), assumes none. The Python tick-loader helper make_csv_options assumes a header row, matching its C++ counterpart.

Version 5.0.0.0