public method host:execute("getHistory", ...)

Brief

Loads the history of the specified instrument.

Declaration
Lua
string host:execute ("getHistory", cookie, instrument, barSize, from, to, bidOrAsk)

Parameters
cookie

The integer value to be passed to AsyncOperationFinished function of the indicator when data is loaded.
instrument

The name of the instrument.
barSize

The size of the bar. See also bar_stream:barSize() for information about the period codes.

Use "t1" to load ticks.
from

The date and time of the price collection begin as a number. That number means the number of days past midnight December 30, 1899. If from value is 0 (zero), the default number of bars (depends on the server settings, usually 300) will be loaded before the date specified in to parameter.
to

The date and time of the price collection end as a number. That number means the number of days past midnight December 30, 1899. Use 0 (zero) to get the data up to the current moment and left the collection subscribed for the new data, so when new tick arrives, the collection will be updated to contain the most fresh data.
bidOrAsk

The flag indicating whether bid (true) or ask (false) prices must be loaded.

Details

The function returns either bar_stream or tick_stream depending on the bar size specified in the request.

This function is asynchronous, i.e. the data isn't available immediately. This function only starts the loading of the data. When the loading is finished, the AsyncOperationFinished function of the indicator or strategy is called.

The recommended approach is the following:

1) Declare the global flag called loading and assign false by default.

2) In the Update() function check the loading flag and returns in case it is true.

3) When you indicator decides to load the data:

3.1) set the loading flag to true

3.2) set a bookmark on the output stream on the first period which cannot be calculated without additional data.

3.3) call host:execute("getHistory", ...) to start data loading.

4) In the AsyncOperationFinished()

4.1) set the loading flag to false

4.2) get the period of the bookmark set on the output stream.

4.3) call instance:updateFrom() using bookmarked period as a parameter. The method forces recalculation of the indicator starting at the specified period.

Note: This function is optional and may be not supported by the host application.

Note: Please keep the object returned by the method in a global variable to avoid removing it by the garbage collection. Storing of the open, close and other tick sub-streams of the bar stream does not protect the main stream from being removed by garbage collector.

The method can be used in both indicators and strategies.

Use host:execute("extendHistory, ...) for loading more data to the history.

See also the host:execute("getSyncHistory", ...) method if you want to have a history synchronized with an indicator source.

Note: When debugging such indicators always switch on the "Pre-deliver data" option in the indicator parameters.

Example: A template of the indicator which loads other instrument data. [hide]

 
   function Init()
       indicator:name("Sample oscillator");
       indicator:description(" ");
       indicator:requiredSource(core.Bar);
       indicator:type(core.Oscillator);
 
       indicator.parameters:addString("INST", "The instrument to load", "", "");
       indicator.parameters:setFlag("INST", core.FLAG_INSTRUMENTS);
   end
 
   local source;       -- the indicator source
   local other;        -- the additional data stream
   local loading;      -- flag indicating the other data stream is being loaded
   local load_from;    -- the date/time the data was loaded the last time from
   local instrument;   -- the instrument to be loaded
   local output;       -- the indicator output stream;
 
   function Prepare()
       source = instance.source;
 
       instrument = instance.parameters.INST;
       assert(instrument ~= instance.source:instrument(), "Please choose different instrument");
 
       local name;
       name = profile:id() .. "(" .. instrument .. ")";
       instance:name(name);
 
 
       output = instance:addStream("other", core.Line, name, "other", core.rgb(255, 0, 0), source:first());
   end
 
   function Update(period, mode)
       local from, to;
 
       if period < source:first() then
           return ;
       end
 
       if other == nil then
           -- if the data is not loaded yet at all
           -- load the data
           from = source:date(source:first());   -- oldest data to load
           if source:isAlive() then              -- newest data to load or 0 if the source is "alive"
               to = 0;
           else
               to = source:date(source:size() - 1);
           end
           load_from = from;
           loading = true;
           other = core.host:execute("getHistory", 1, instrument, source:barSize(), from, to, source:isBid());
           return ;
       end
 
       if loading then
           return ;
       end
 
       local curr_date = source:date(period);
       if curr_date < load_from then
           -- if the data we are trying to get is oldest than previously loaded
           -- the extend the history to the oldest data we can request
           from = source:date(source:first());     -- load from the oldest data we have in source
           if other:size() > other:first() then
               to = other:date(other:first());     -- to the oldest data we have in other instrument
           else
               to = load_from;
           end
           load_from = from;
           loading = true;
           core.host:execute("extendHistory", 1, other, from, to);
           return ;
       end
 
       -- the date is in the loaded range
       -- try to find it
       local other_period = core.findDate(other, curr_date, true);
       if other_period ~= -1 then
           output[period] = other.close[other_period];
       end
   end
 
   function AsyncOperationFinished(cookie, success, message)
       if cookie == 1 then
           loading = false;
           -- update the indicator output when loading is finished
           instance:updateFrom(source:first());
           return ;
       end
   end

Example: A template of the indicator which loads other time frame data. [hide]

   function Init()
       indicator:name("Sample indicator");
       indicator:description(" ");
       indicator:requiredSource(core.Bar);
       indicator:type(core.Indicator);
 
       indicator.parameters:addString("TF", "The timeframe to load", "", "");
       indicator.parameters:setFlag("TF", core.FLAG_PERIODS);
   end
 
   local source;                -- the indicator source
   local other;                 -- the additional data stream
   local loading;               -- flag indicating the other data stream is being loaded
   local load_from;             -- the date/time the data was loaded the last time from
   local TF;                    -- the timeframe to be loaded
   local output;                -- the indicator output stream;
   local offset, weekoffset;    -- params for candle calculation
 
   function Prepare()
       source = instance.source;
       TF = instance.parameters.TF;
 
       offset = core.host:execute("getTradingDayOffset");
       weekoffset = core.host:execute("getTradingWeekOffset");
 
       -- check whether chosen time frame is higher than
       local s1, e1, s2, e2;
       s1, e1 = core.getcandle(source:barSize(), offset, weekoffset);
       s2, e2 = core.getcandle(TF, offset, weekoffset);
       assert((e2 - s2) > (e1 - s1), "The chosen time frame must be longer than the source time frame");
 
       local name;
       name = profile:id() .. "(" .. TF .. ")";
       instance:name(name);
 
 
       H = instance:addStream("H", core.Line, name .. ".H", "H", core.rgb(255, 0, 0), source:first());
       L = instance:addStream("L", core.Line, name .. ".L", "L", core.rgb(255, 0, 0), source:first());
   end
 
   function Update(period, mode)
       local from, to;
 
       if period < source:first() then
           return ;
       end
 
       if other == nil then
           -- if the data is not loaded yet at all
           -- load the data
           from = source:date(source:first());   -- oldest data to load
           from = core.getcandle(TF, from, offset, weekoffset);
           if source:isAlive() then              -- newest data to load or 0 if the source is "alive"
               to = 0;
           else
               to = source:date(source:size() - 1);
               to = core.getcandle(TF, to, offset, weekoffset);
           end
           load_from = from;
           loading = true;
           other = core.host:execute("getHistory", 1, source:instrument(), TF, from, to, source:isBid());
           return ;
       end
 
       if loading then
           return ;
       end
 
       local curr_date = source:date(period);
       curr_date = core.getcandle(TF, curr_date, offset, weekoffset);
 
       if curr_date < load_from then
           -- if the data we are trying to get is oldest than previously loaded
           -- the extend the history to the oldest data we can request
           from = source:date(source:first());     -- load from the oldest data we have in source
           from = core.getcandle(TF, from, offset, weekoffset);
           if other:size() > other:first() then
               to = other:date(other:first());     -- to the oldest data we have in other instrument
           else
               to = load_from;
           end
           load_from = from;
           loading = true;
           core.host:execute("extendHistory", 1, other, from, to);
           return ;
       end
 
       -- the date is in the loaded range
       -- try to find it
       local other_period = core.findDate(other, curr_date, true);
       if other_period ~= -1 then
           H[period] = other.high[other_period];
           L[period] = other.low[other_period];
       end
   end
 
   function AsyncOperationFinished(cookie, success, message)
       if cookie == 1 then
           loading = false;
           -- update the indicator output when loading is finished
           instance:updateFrom(source:first());
           return ;
       end
   end

back