Per-strategy configuration

Override input. More...

Macros
#define	PINEFORGE_HAS_SYMBOL_FEED_V1   1
	Feature probe for strategy_set_symbol_feed: the first of four opt-in setters of another symbol's data for request.security (lane XSYM-D), each behind its own feature probe.
#define	PINEFORGE_HAS_SYMBOL_FEED_COLUMN_V1   1
	Feature probe for strategy_set_symbol_feed_column.
#define	PINEFORGE_HAS_SYMBOL_FACTS_V1   1
	Feature probe for strategy_set_symbol_facts.
#define	PINEFORGE_HAS_RECORDED_SERIES_V1   1
	Feature probe for strategy_set_recorded_series.
#define	PINEFORGE_HAS_RUN_FAILURE_CODES_V1   1
	Compile-time probe for the two run-failure code getters below (and the generated-code helpers of <pineforge/run_failure.hpp>).

Functions
void	strategy_set_input (pf_strategy_t s, const char *key, const char *value)
	Override a Pine input.
void	strategy_set_override (pf_strategy_t s, const char *key, const char *value)
	Override a strategy(...) declaration parameter.
void	strategy_set_magnifier_volume_weighted (pf_strategy_t s, int on)
	Toggle volume-weighted bar-magnifier sampling.
int	strategy_declares_bar_magnifier (void)
	Report the script's strategy(..., use_bar_magnifier = true) declaration.
void	strategy_set_trace_enabled (pf_strategy_t s, int on)
	Toggle per-bar trace recording.
void	strategy_set_trade_start_time (pf_strategy_t s, int64_t timestamp_ms)
	Set the earliest Unix-ms timestamp at which strategy order commands may fire.
void	strategy_set_chart_timezone (pf_strategy_t s, const char *tz)
	Set the strategy's chart timezone (IANA / POSIX TZ string).
void	strategy_set_syminfo_timezone (pf_strategy_t s, const char *tz)
	Plumb the symbol's exchange timezone (IANA string) into syminfo.
void	strategy_set_syminfo_session (pf_strategy_t s, const char *session)
	Set the symbol's session string (e.g.
void	strategy_set_syminfo_type (pf_strategy_t s, const char *type)
	Set the instrument class (syminfo.type: "forex", "stock", "crypto", "futures", "index", "fund", "cfd", ...; default "crypto").
int	strategy_set_syminfo_string (pf_strategy_t s, const char *key, const char *value)
	Set one of the remaining string members of syminfo by Pine member name: "ticker", "tickerid", "currency", "basecurrency", "description", "volumetype" (and "type").
void	strategy_set_syminfo_mintick (pf_strategy_t s, double mintick)
	Set the instrument tick size (syminfo.mintick, default 0.01).
void	strategy_set_syminfo_pointvalue (pf_strategy_t s, double pointvalue)
	Set the instrument point value (syminfo.pointvalue, default 1.0) — the $-per-point-per-contract multiplier applied to every money path: realized PnL and MFE/MAE, open profit / mark-to-market equity (and the drawdown / runup extremes), percent-of-equity and cash position sizing, percent commission notionals, and the margin admission check.
void	strategy_set_syminfo_metadata (pf_strategy_t s, const char *key, double value)
	Inject a fundamental/exchange metadata value by Pine member name (e.g.
int	strategy_set_account_currency_fx_series (pf_strategy_t s, const int64_t *effective_from_ms, const double *account_per_quote, int n)
	Install a timestamped quote-to-account currency conversion curve.
int	strategy_set_aux_security_feed (pf_strategy_t s, const pf_bar_t *bars, int n, const char *input_tf)
	Copy a finer feed used exclusively by same-symbol request.security calls.
int	strategy_set_native_security_feed (pf_strategy_t s, const char *timeframe, const pf_bar_t *bars, int n)
	Copy the exchange's OWN bars of one higher timeframe for same-symbol request.security calls that request exactly that timeframe.
int	strategy_set_symbol_feed (pf_strategy_t s, const char *key, const char *timeframe, const pf_bar_t *bars, const int64_t *close_ms, int n)
	Copy another symbol's own bars of one timeframe, keyed by the exact symbol string a request site passes at run time (key) and by timeframe ("15", "60", "1D", ...; "D" and "1D" are one key).
int	strategy_set_symbol_feed_column (pf_strategy_t s, const char *key, const char *timeframe, const char *name, const double *values, int n)
	Copy one named column of an installed symbol feed: n values, one per bar of the feed of (key, timeframe), in bar order (a footprint delta, "fp_delta_100_70").
int	strategy_set_symbol_facts (pf_strategy_t s, const char *key, const char *field, const char *value)
	Set one fact of the symbol a request site names by key: field is one of "canonical", "valid" ("true" / "false"), "type", "timezone", "session", "currency" or "mintick" (a positive decimal).
int	strategy_set_recorded_series (pf_strategy_t s, const char *key, const int64_t *chart_open_ms, const double *values, int n)
	Copy a recorded request series: the values a request returned on the chart bars that opened at chart_open_ms (strictly increasing), keyed by the request key a generated strategy reads it under.
const char *	strategy_get_last_error (pf_strategy_t s)
	Returns the error message captured by the most recent run_backtest / run_backtest_full call on this strategy.
const char *	strategy_get_last_error_code (pf_strategy_t s)
	Stable code of the most recent failure on s: lower snake_case ASCII matching ^[a-z][a-z0-9_]{2,47}$, from the closed vocabulary published as run_failure_codes.json (schema pineforge-run-failure-catalog/v1); a code is never reused for another meaning.
const char *	strategy_get_last_error_args (pf_strategy_t s)
	The typed arguments of the failure strategy_get_last_error_code names, as one canonical JSON object: UTF-8, keys sorted, no whitespace; an integer is a JSON integer, a number the shortest round-trip double, every other kind a JSON string.

Detailed Description

Override input.

*() values, strategy(...) params, and runtime knobs.

Macro Definition Documentation

PINEFORGE_HAS_SYMBOL_FEED_V1

#define PINEFORGE_HAS_SYMBOL_FEED_V1   1

Feature probe for strategy_set_symbol_feed: the first of four opt-in setters of another symbol's data for request.security (lane XSYM-D), each behind its own feature probe.

They are the Pine source host's doors: a strategy that registers a request site for another symbol reads its bars, its facts and its recorded request values from what these installed before the run; during a run each answers -1, as a host with no source layer does. Every array is copied; a later call replaces what an earlier one installed under the same key. Historical runs only: stream_begin() fails closed while a symbol feed or a recorded series is installed.

Definition at line 1722 of file pineforge.h.

PINEFORGE_HAS_SYMBOL_FEED_COLUMN_V1

#define PINEFORGE_HAS_SYMBOL_FEED_COLUMN_V1   1

Feature probe for strategy_set_symbol_feed_column.

Definition at line 1724 of file pineforge.h.

PINEFORGE_HAS_SYMBOL_FACTS_V1

#define PINEFORGE_HAS_SYMBOL_FACTS_V1   1

Feature probe for strategy_set_symbol_facts.

Definition at line 1726 of file pineforge.h.

PINEFORGE_HAS_RECORDED_SERIES_V1

#define PINEFORGE_HAS_RECORDED_SERIES_V1   1

Feature probe for strategy_set_recorded_series.

Definition at line 1728 of file pineforge.h.

PINEFORGE_HAS_RUN_FAILURE_CODES_V1

#define PINEFORGE_HAS_RUN_FAILURE_CODES_V1   1

Compile-time probe for the two run-failure code getters below (and the generated-code helpers of <pineforge/run_failure.hpp>).

A runtime library without them lacks the symbols: look them up with dlsym.

Definition at line 1821 of file pineforge.h.

Function Documentation

strategy_set_input()

void strategy_set_input	(	pf_strategy_t	s,
		const char *	key,
		const char *	value )

Override a Pine input.

*() value before the next run.

Parameters

s	Strategy handle.
key	The input's title (or fallback identifier).
value	Serialized value — numbers as decimal strings, booleans as "true" / "false".

Calls after run_backtest are accepted but only take effect on subsequent runs.

References PF_API.

strategy_set_override()

void strategy_set_override	(	pf_strategy_t	s,
		const char *	key,
		const char *	value )

Override a strategy(...) declaration parameter.

Recognised key values: initial_capital, commission_value, default_qty_value, pyramiding, slippage, process_orders_on_close, close_entries_rule, default_qty_type, commission_type.

References PF_API.

strategy_set_magnifier_volume_weighted()

void strategy_set_magnifier_volume_weighted	(	pf_strategy_t	s,
		int	on )

Toggle volume-weighted bar-magnifier sampling.

Has no effect unless the bar magnifier is enabled in run_backtest_full.

References PF_API.

strategy_declares_bar_magnifier()

int strategy_declares_bar_magnifier

(

void

)

Report the script's strategy(..., use_bar_magnifier = true) declaration.

Exported only by a strategy whose declaration is that literal; every other .so lacks the symbol. TradingView backtests such a script on its bar magnifier, so a host runs it on a finer input with the magnifier on (run_backtest_full).

Returns

1.

References PF_API.

strategy_set_trace_enabled()

void strategy_set_trace_enabled	(	pf_strategy_t	s,
		int	on )

Toggle per-bar trace recording.

Default off (zero-cost when off).

Enables capture for // @pf-trace name=expr pragmas already compiled into the strategy .so. Trace records appear in pf_report_t::trace.

References PF_API.

strategy_set_trade_start_time()

void strategy_set_trade_start_time	(	pf_strategy_t	s,
		int64_t	timestamp_ms )

Set the earliest Unix-ms timestamp at which strategy order commands may fire.

Earlier bars still execute user code and warm TA/series state, but strategy.entry/order/exit/close commands are ignored.

References PF_API.

strategy_set_chart_timezone()

void strategy_set_chart_timezone	(	pf_strategy_t	s,
		const char *	tz )

Set the strategy's chart timezone (IANA / POSIX TZ string).

Pine builtins hour, minute, second, dayofmonth, dayofweek, month, year and weekofyear return the wall-clock for the chart's timezone — TV exports trade rows in chart TZ too. Engine bars are stored as Unix-ms (UTC), so without this override these builtins return UTC and silently diverge from TV by N hours when the chart is on a non-UTC zone (Asia/Taipei = UTC+8 is the validator default).

Pass NULL, "", "UTC" or "Etc/UTC" for the legacy UTC behaviour (cheap, mutex-free). Any other value names a TZ resolved by the system tzdata; the per-bar decomposition then runs under a process-global mutex so multi-threaded harnesses don't corrupt each other's wall time.

Should be called before run_backtest / run_backtest_full. Persists across runs on the same strategy handle until overridden.

References PF_API.

strategy_set_syminfo_timezone()

void strategy_set_syminfo_timezone	(	pf_strategy_t	s,
		const char *	tz )

Plumb the symbol's exchange timezone (IANA string) into syminfo.

Feeds session.ismarket / time(session) predicates. Defaults to "UTC" (crypto). Distinct from strategy_set_chart_timezone — the chart TZ drives wall-clock builtins and intraday-cap day rollover; this drives session membership. NULL is ignored. Call before run_backtest / run_backtest_full.

References PF_API.

strategy_set_syminfo_session()

void strategy_set_syminfo_session	(	pf_strategy_t	s,
		const char *	session )

Set the symbol's session string (e.g.

"0930-1600:23456", default "24x7"). Feeds session.ismarket / time(session). NULL ignored. Call before run_backtest / run_backtest_full.

References PF_API.

strategy_set_syminfo_type()

void strategy_set_syminfo_type	(	pf_strategy_t	s,
		const char *	type )

Set the instrument class (syminfo.type: "forex", "stock", "crypto", "futures", "index", "fund", "cfd", ...; default "crypto").

Scripts branch on it for instrument conventions (e.g. the forex pip size). NULL / empty ignored. Call before run_backtest / run_backtest_full.

References PF_API.

strategy_set_syminfo_string()

int strategy_set_syminfo_string	(	pf_strategy_t	s,
		const char *	key,
		const char *	value )

Set one of the remaining string members of syminfo by Pine member name: "ticker", "tickerid", "currency", "basecurrency", "description", "volumetype" (and "type").

Returns 0 when set, -1 for an unknown key, empty value or NULL. Call before run_backtest / run_backtest_full.

References PF_API.

strategy_set_syminfo_mintick()

void strategy_set_syminfo_mintick	(	pf_strategy_t	s,
		double	mintick )

Set the instrument tick size (syminfo.mintick, default 0.01).

Drives the directional stop-entry snap and slippage = N*mintick economics. Set per-instrument (e.g. 0.25 for ES, 0.00001 for FX). Non-positive ignored. Call before run_backtest / run_backtest_full.

References PF_API.

strategy_set_syminfo_pointvalue()

void strategy_set_syminfo_pointvalue	(	pf_strategy_t	s,
		double	pointvalue )

Set the instrument point value (syminfo.pointvalue, default 1.0) — the $-per-point-per-contract multiplier applied to every money path: realized PnL and MFE/MAE, open profit / mark-to-market equity (and the drawdown / runup extremes), percent-of-equity and cash position sizing, percent commission notionals, and the margin admission check.

Set per-instrument (e.g. 50 for ES). Non-positive ignored. Call before run_backtest / run_backtest_full.

References PF_API.

strategy_set_syminfo_metadata()

void strategy_set_syminfo_metadata	(	pf_strategy_t	s,
		const char *	key,
		double	value )

Inject a fundamental/exchange metadata value by Pine member name (e.g.

"shares_outstanding_total", "target_price_average"). These have no OHLCV source; reads of un-injected members return na. Call before run_backtest / run_backtest_full.

References PF_API.

strategy_set_account_currency_fx_series()

int strategy_set_account_currency_fx_series	(	pf_strategy_t	s,
		const int64_t *	effective_from_ms,
		const double *	account_per_quote,
		int	n )

Install a timestamped quote-to-account currency conversion curve.

Each value is account-currency units per one unit of the symbol's quote currency and becomes active, inclusively, at the corresponding Unix-ms timestamp. The latest active value carries forward; broker events before the first point use the scalar account_currency_fx metadata fallback. Installing a curve also selects the converted account-currency broker ledger, including during that pre-first fallback interval; it is not equivalent to a same-currency run merely because a rate happens to be 1. Arrays are copied. Timestamps must be strictly increasing and rates positive and finite. Pass n == 0 to clear the curve and restore scalar behavior. Timestamped curves currently support ordinary historical runs. Broker-open rate changes: carried 1× longs and 1× shorts are supported; leveraged positions fail closed at the crossing. Streaming, calc-on-order-fills, and bar-magnifier runs also fail closed.

Returns

0 on success, -1 for a null strategy or invalid arrays.

References PF_API.

strategy_set_aux_security_feed()

int strategy_set_aux_security_feed	(	pf_strategy_t	s,
		const pf_bar_t *	bars,
		int	n,
		const char *	input_tf )

Copy a finer feed used exclusively by same-symbol request.security calls.

The next ordinary run_backtest_full call must receive native chart bars with input_tf equal to script_tf and bar magnifier disabled. Chart OHLCV, broker fills, and bar_index continue to advance only from that native chart feed; bars advance only request.security evaluators. Every auxiliary bar must map to exactly one native chart bar and every native chart bar must have at least one auxiliary bar, otherwise the run fails closed via strategy_get_last_error. Arrays are copied. Pass n == 0 to clear the auxiliary feed.

Returns

0 on success, -1 for a null strategy or invalid input.

References PF_API.

strategy_set_native_security_feed()

int strategy_set_native_security_feed	(	pf_strategy_t	s,
		const char *	timeframe,
		const pf_bar_t *	bars,
		int	n )

Copy the exchange's OWN bars of one higher timeframe for same-symbol request.security calls that request exactly that timeframe.

On intraday charts of CME futures and US/Indian equities TradingView's request.security(syminfo.tickerid, "D", close) returns the exchange's daily bar – the 15:00 CT settlement on ES1!/NQ1!, the official closing print on NASDAQ/NYSE/NSE – which no aggregation of the intraday feed can reproduce. With a native feed installed for timeframe ("D", "1D", "W", ...), every completed request.security bucket of that timeframe carries the native bar's OHLCV (matched by the bucket's own label: the session-day stamp for D/W/M, the grid open for intraday) instead of the aggregate; bucket TIMING – when the bar completes relative to the chart – and every other timeframe's request are unchanged, and so are chart OHLCV, broker fills and bar_index. A "W" / "M" request with no feed of its own reads the daily feed's bars aggregated per week / month (TradingView builds its W/M bars from the native daily bars, never from intraday prints), keyed by the period's first session-day. A completed bucket with no native bar keeps its aggregate (counted, not fatal). Bars must be strictly increasing; arrays are copied; pass n == 0 to clear the feed for timeframe. Historical runs only: stream_begin() fails closed while a native feed is installed.

Returns

0 on success, -1 for a null strategy or invalid input.

References PF_API.

strategy_set_symbol_feed()

int strategy_set_symbol_feed	(	pf_strategy_t	s,
		const char *	key,
		const char *	timeframe,
		const pf_bar_t *	bars,
		const int64_t *	close_ms,
		int	n )

Copy another symbol's own bars of one timeframe, keyed by the exact symbol string a request site passes at run time (key) and by timeframe ("15", "60", "1D", ...; "D" and "1D" are one key).

Each bar carries its own close, close_ms[i]: after its open (bars[i].timestamp) and at or before the next bar's open. No calendar is guessed for the symbol. Bars must be strictly increasing with finite prices; a volume the symbol does not publish is NaN. The feed reaches the kernel as a NativeRunSpec instrument feed: on each chart bar, a site with lookahead off reads the last bar that has closed by the chart bar's close, one with lookahead on the last bar that opened by its open, and the site's expression runs over every bar of the feed, in order. Installing a feed drops the columns of the feed it replaces; n == 0 installs a feed without bars, whose sites read na. Historical runs only: stream_begin() fails closed while a symbol feed is installed.

Returns

0 on success, -1 for a null strategy, invalid input (the reason in strategy_get_last_error) or a host with no source layer.

References PF_API.

strategy_set_symbol_feed_column()

int strategy_set_symbol_feed_column	(	pf_strategy_t	s,
		const char *	key,
		const char *	timeframe,
		const char *	name,
		const double *	values,
		int	n )

Copy one named column of an installed symbol feed: n values, one per bar of the feed of (key, timeframe), in bar order (a footprint delta, "fp_delta_100_70").

NaN is an absent value. A column of the same name is replaced. Historical runs only: stream_begin() fails closed while a symbol feed is installed.

Returns

0 on success, -1 for a null strategy, a feed that is not installed, a length that is not the feed's, a name the kernel refuses, or a host with no source layer.

References PF_API.

strategy_set_symbol_facts()

int strategy_set_symbol_facts	(	pf_strategy_t	s,
		const char *	key,
		const char *	field,
		const char *	value )

Set one fact of the symbol a request site names by key: field is one of "canonical", "valid" ("true" / "false"), "type", "timezone", "session", "currency" or "mintick" (a positive decimal).

Inside that site's expression syminfo.* reads these facts (syminfo.tickerid reads key itself). A symbol whose valid is "false" makes a site with ignore_invalid_symbol read na and fails any other site's run closed. Facts only describe an installed feed, so historical runs only: stream_begin() fails closed while a symbol feed is installed.

Returns

0 on success, -1 for a null strategy, an unknown field, a value the field refuses, or a host with no source layer.

References PF_API.

strategy_set_recorded_series()

int strategy_set_recorded_series	(	pf_strategy_t	s,
		const char *	key,
		const int64_t *	chart_open_ms,
		const double *	values,
		int	n )

Copy a recorded request series: the values a request returned on the chart bars that opened at chart_open_ms (strictly increasing), keyed by the request key a generated strategy reads it under.

On a chart bar with no row the series reads na, and on every bar when n == 0. Historical runs only: stream_begin() fails closed while a recorded series is installed.

Returns

0 on success, -1 for a null strategy, invalid input or a host with no source layer.

References PF_API.

strategy_get_last_error()

const char * strategy_get_last_error

(

pf_strategy_t

s

)

Returns the error message captured by the most recent run_backtest / run_backtest_full call on this strategy.

Returns an empty string when the run completed normally, or NULL only when s itself is NULL. The pointer is owned by the engine and remains valid until the next run_backtest / run_backtest_full call (which clears the captured error before it begins).

The runtime catches every std::exception derivative inside the engine's run loop so the C ABI never unwinds a C++ exception across the extern "C" boundary. Consumers must check this after every run to surface engine-rejected configurations such as a script timeframe finer than the input timeframe, a request.security timeframe below the chart timeframe without a supported lower-TF emulation, or a missing input timeframe when securities are registered.

References PF_API.

Referenced by main(), and run_mode().

strategy_get_last_error_code()

const char * strategy_get_last_error_code

(

pf_strategy_t

s

)

Stable code of the most recent failure on s: lower snake_case ASCII matching ^[a-z][a-z0-9_]{2,47}$, from the closed vocabulary published as run_failure_codes.json (schema pineforge-run-failure-catalog/v1); a code is never reused for another meaning.

Returns "" exactly when the most recent run (or setter) on s recorded no failure, and NULL only when s is NULL. It is not keyed on the text: a script that stops with an empty runtime.error() message fails with strategy_get_last_error "" and the code strategy_runtime_error, and a non-empty error that no coded site wrote reads engine_unclassified_error, never "". A text a script writes never selects a code. The pointer has the lifetime of strategy_get_last_error's (until the next run or setter on s).

References PF_API.

strategy_get_last_error_args()

const char * strategy_get_last_error_args

(

pf_strategy_t

s

)

The typed arguments of the failure strategy_get_last_error_code names, as one canonical JSON object: UTF-8, keys sorted, no whitespace; an integer is a JSON integer, a number the shortest round-trip double, every other kind a JSON string.

"{}" when the code has no arguments, "" when there is no failure, NULL only when s is NULL. An argument is never a value the script computed while it ran. Same lifetime as strategy_get_last_error_code.

References PF_API.