Requests

A study sees the bars of its own chart. The req functions let it see further: a daily value on a five minute chart, the NIFTY index beside a stock, two option legs added into one premium. req.timeframe() reads an expression computed on a coarser interval of the chart's own instrument, req.symbol() reads one computed on another instrument, and req.isReady() and req.error() tell the script whether the answer has arrived. Two more, req.candle() and req.events(), are planned. This page is the reference for all six in OpenScript (also called OpenAlgo Script).

version 1
study("Relative strength", precision = 4)

indexName     = input("NIFTY", "Index")
indexExchange = input("NSE_INDEX", "Index exchange")

// The index's close at the chart's own interval. "developing" pairs each
// chart bar with the index bar at the same time (see The mode, below).
idx = req.symbol(indexName, chart.interval, close, exchange = indexExchange, mode = "developing")

// Absent until the index answers, so the line simply starts then.
ratio = close / idx

plot(ratio, "Close over index", aqua, width = 2)
plot(sma(ratio, 20), "Average of the ratio", fade(silver, 40))

// Red if the read failed, grey while it is still loading.
background(req.error(idx) != "" ? fade(red, 90) : (req.isReady(idx) ? none : fade(gray, 94)))

How a read works

A read takes an expression and computes it as a program of its own over the requested bars. Inside the expression, open, high, low, close, volume and time are the requested instrument's, at the requested interval, and every indicator reads those bars: req.timeframe("1D", ema(close, 20)) is a 20 day average of daily closes, not a longer average of five minute closes. The result is then lined up with the chart's bars by timestamp, one value per chart bar, and it has the type of the expression: a number, a bool for a comparison, a string for text.

History counts differently inside and outside the read:

Inside the expression you may write literals and input() calls, and read a name from the rest of the file only when that name holds an input(). Any other name is error OS6003, because a name computed on the chart's own bars has no meaning on the requested bars. That includes a name that holds a plain number, such as n = 20: write the 20 inside the expression instead. A var that starts from an input counts as computed too, because a later line may change it.

myAtr = atr(14)
wide  = req.timeframe("1D", high - low > myAtr)
plot(wide ? 1 : 0, "Wide day")

A read computes a value; it does not act or draw. An order call inside the expression is error OS7003, and a drawing, marker or alert call is error OS3006. The symbol and the timeframe are part of what the host, the application running the script such as the /trading page, fetches, so they too are fixed before the first bar: write each as a literal or an input(), because one that depends on bar data is error OS3003.

The mode

mode decides what a read is allowed to know on a bar where the coarser bar has not finished. It is the argument that makes a repainting study impossible to write by accident, because the default never repaints and the other two have to be written out.

On a five minute chart reading req.timeframe("1D", high), a bar at 11:00 today holds yesterday's high in "confirmed", today's high so far in "developing", and today's final high in "lookahead", which no one could have known at 09:15. Only the first is a number a rule could have acted on at 11:00, so for a timeframe coarser than the chart's it is the only mode a signal, an alert or an order should be built on. A backtest of a rule that reads "lookahead" looks excellent and means nothing.

Reading at the chart's own interval

A read at the chart's own interval, usually of another instrument, follows the same rule, and the result surprises people. On a five minute chart, the other instrument's 11:00 bar has not closed when the chart's 11:00 bar opens, so a "confirmed" read gives the 11:00 chart bar the other instrument's 10:55 bar: every value is one bar behind. Where the other instrument has no bar at all, a "confirmed" read keeps holding an older value rather than going absent.

To pair each chart bar with the other instrument's bar at the same time, as a ratio, a spread or a combined premium needs, write mode = "developing". On history each chart bar then gets the other instrument's bar at the same time, a chart bar with no counterpart is absent, and only the value on the newest bar can change, until that bar closes, just as the chart's own close does.

Warnings

The compiler warns about a "lookahead" read with OS8005. A "developing" read carries no warning: the mode written on the line is its disclosure. A file that sets onUnconfirmed = true gets warning OS8002 on every read in the file, whatever its mode or interval, because a forming chart bar that reads another bar still forming can be withdrawn twice over. Repainting covers the subject in full.

Timeframes

A timeframe is a count and a unit, written as a string. The unit letters are case sensitive.

Take a timeframe from the reader with input("1D", "Timeframe", kind = "interval"). A string the language does not recognise is error OS6001. Two more rules depend on the chart, so they are checked when the study loads, and a study that breaks either is refused before its first bar: a timeframe finer than the chart's is OS6002, because a daily chart does not contain the five minute bars that made it, and an intraday timeframe that is not a whole multiple of the chart's, such as "45m" on a "30m" chart, is OS6015. Day, week and month reads are grouped by the calendar in the instrument's timezone and are exempt from the multiple rule. Timeframes covers intervals in full.

When a read fails

A read that cannot be answered is never an empty series, which would look exactly like an instrument that did not trade. It stays absent on every bar, req.isReady() stays false, and req.error() returns a sentence naming the problem. The rest of the study keeps drawing.

A few problems stop the whole study instead, when it loads and before its first bar, so nothing is drawn:

Each distinct symbol, exchange and timeframe is one series the host fetches and keeps in step with the chart, so make one read per series, give it a name and reuse the name. Arithmetic on reads you already have is free: the midpoint of yesterday's range is (prevHigh + prevLow) / 2, not a third read.

Reads in /trading

The /trading chart does not tell a study its instrument's exchange, so chart.exchange is none there. A req.symbol() call that names no exchange is fetched on the chart's own exchange, which suits a peer stock on the same exchange; name exchange whenever the other instrument trades elsewhere, such as NIFTY on NSE_INDEX from an NSE stock chart.

/trading calls its daily interval D, which is not a timeframe the language reads, so on a daily chart a read that passes chart.interval stops the study with OS6001. Write "1D" there instead.

Reading another timeframe

req.timeframe(timeframe: string, expr: T, mode?: string = "confirmed") -> T

version 1
study("Previous day levels", overlay = true, precision = 2)

// "confirmed" is the default: these are yesterday's numbers, and they never repaint.
prevHigh  = req.timeframe("1D", high)
prevLow   = req.timeframe("1D", low)
prevClose = req.timeframe("1D", close)

// Derived, not a fourth read.
prevMid = (prevHigh + prevLow) / 2

pHigh = plot(prevHigh, "Previous high", aqua, width = 2, style = "step")
pLow  = plot(prevLow, "Previous low", orange, width = 2, style = "step")
plot(prevClose, "Previous close", silver, style = "step")
plot(prevMid, "Previous mid", fade(silver, 50), style = "step")
fill(pHigh, pLow, color = aqua, opacity = 0.05)

version 1
study("Daily candle", overlay = true)

o = req.timeframe("1D", open,  mode = "lookahead")
h = req.timeframe("1D", high,  mode = "lookahead")
l = req.timeframe("1D", low,   mode = "lookahead")
c = req.timeframe("1D", close, mode = "lookahead")

plotCandles(o, h, l, c, "Daily", colorUp = fade(lime, 60), colorDown = fade(red, 60))

Reading another instrument

req.symbol(
    symbol: string,
    timeframe: string,
    expr: T,
    exchange?: string = chart.exchange,
    mode?: string = "confirmed"
) -> T

version 1
study("Combined premium", precision = 2)

// Type the two contract symbols into the study's settings.
callLeg = input("", "Call leg")
putLeg  = input("", "Put leg")
legs    = input("NFO", "Legs exchange")
lots    = input(1, "Lots", min = 1, max = 100)
// chart.lotSize describes the chart's instrument, not the legs: enter the
// contract's current lot size here.
lotSize = input(1, "Units in one lot", min = 1)

callPrice = req.symbol(callLeg, chart.interval, close, exchange = legs, mode = "developing")
putPrice  = req.symbol(putLeg, chart.interval, close, exchange = legs, mode = "developing")

// If either leg has no bar at this instant, the sum is none, not half a position.
premium = callPrice + putPrice

plot(premium, "Combined premium", orange, width = 2)
plot(premium * lots * lotSize, "Position value", aqua, scale = "left")

Request status

req.isReady(read: any) -> series bool

version 1
study("Loading shade", precision = 2)

peer = req.symbol("RELIANCE", chart.interval, close, exchange = "NSE", mode = "developing")

plot(close / peer, "Close over RELIANCE", aqua)

// Grey until the other instrument's bars have arrived.
background(req.isReady(peer) ? none : fade(gray, 94))

req.error(read: any) -> series string

version 1
study("Peer status", precision = 2)

peerName     = input("RELIANCE", "Compare with")
peerExchange = input("NSE", "Its exchange")

peer = req.symbol(peerName, chart.interval, close, exchange = peerExchange, mode = "developing")
why  = req.error(peer)

plot(close / peer, "Close over peer", aqua)

panel = table("Status", 1, 2, position = "topRight", textColor = silver)
if bar.isLast
    cell(panel, 0, 0, peerName)
    cell(panel, 0, 1, why != "" ? why : (req.isReady(peer) ? "ready" : "loading"), textColor = why != "" ? red : (req.isReady(peer) ? lime : silver))

Planned

req.candle(timeframe: string, mode?: string) -> array<number>

req.events(kind: string) -> series number

Related

Higher timeframes, Other instruments, Repainting, Timeframes, chart.*, Absent values, Backtesting.