The ChartDataSeries is the main object you will work with when accessing data through the new chart data api. This object will handle requesting historical chart data, subscribing for live updates and raising events as live trades update the data.
When you create an instance of ChartDataSeries, you must keep a reference to it somewhere and be sure to properly dispose it when you are finished working with it. Disposing the ChartDataSeries object unsubscribes it from live market data, freeing up bandwidth and memory usage.
You can create a ChartDataSeries for either a market, or a contract. If you need long-term historical data that spans multiple markets, then you will want to request the data based off of the contract. By default, contract chart data requests will return chart data for the market with the highest trade volume for any given day.
Once you have created an instance of ChartDataSeries, you will call either LoadRealTimeChartData() or LoadHistoricalChartData().
LoadRealTimeChartData() takes a starting date as a sole parameter. It will load historical chart data from the date you specify all the way up to the current trading day. This method will also create a market subscription behind the scenes and apply live trades in real-time to the data to keep it up to date.
LoadHistoricalChartData() takes a starting and ending date as parameters. It will load historical chart data between the range of dates that you specify. It will not create a market subscription, nor will it keep the data loaded up to date with live trades.
' Load 15-Minute bars.
Dim oBarIntvl As NewBarInterval(ChartInterval.Minute, 15)
If Not moMarket Is Nothing Then
' Load the data for the selected market.
moBarData = New ChartDataSeries(moMarket, oBarIntvl, SessionTimeRange.Empty)
' Request the chart data and subscribe for updates.
moBarData.LoadRealTimeChartData(dtStartDate)
' Alternatively, load only load historical chart data.
'moBarData.LoadHistoricalChartData(dtStartDate, dtEndDate)
Else
' Load "continuation" data for the contract.
Dim oContinuation As New ContinuationSettings()
moBarData = New ChartDataSeries(moSelectedContract, oBarIntvl, SessionTimeRange.Empty, oContinuation)
' Request the chart data and subscribe for updates.
moBarData.LoadRealTimeChartData(dtStartDate)
' Alternatively, load only load historical chart data.
'moBarData.LoadHistoricalChartData(dtStartDate, dtEndDate)
End If
The ChartDataSeries raises two events: DataLoadComplete and DataSeriesUpdated.
DataLoadComplete is raised when the initial historical chart data load is complete. The event arguments passed (DataLoadCompleteEventArgs), will tell you:
- The date range requested.
- The date range processed (for situations where your request exceeded historical chart data limits).
- The status (success, fail) of the request.
- How long it took to process the request.
DataSeriesUpdated is raised when new trades cause a change in the data. The event arguments passed (DataSeriesUpdatedEventArgs) tell you what data has changed are where that change occurred.
The ChartDataSeries object stores bars, modes and settlements in three distinct lists accessible via the TradeBars, Modes and Settlements properties of the ChartDataSeries class. The DataSeriesUpdatedEventArgs object has three correspnding properties that will tell you the start index of the lastest change.
For example, supposed you have a ChartDataSeries object loaded and subscribed for live updates. ChartDataSeries.TradeBars.Count = 100 (there are 100 bars in the data series.) You get a DataSeriesUpdated event and the TradeBarIndexUpdate property of the event args = 99. You now know that the last bar of the series was changed due to one more trades since the last time the DataSeriesUpdated event took place. Furthermore, it might be possible that ChartDataSeries.TradeBars.Count now = 101. In this case, not only was the last bar updated, but a new bar was created as well.
You must pay particular attention when handling event and accessing ChartDataSeries data with respect to threads and locking. Though not difficult, it cannot be ignored. This will be explained in detail in the section Safely Handling Events and Accessing Chart Data below.