Accessing Instruments

Instrument Context:

Instrument Context is a process that provides direct access to instrument information.  


During the initialization of test, each instrument's data is automatically loaded into an instrument object.  Information in an instrument object can easily be accessed in script sections where Trading Blox Builder automatically provides instrument context.  In script sections where instrument context information is not automatically provided, instrument data can still be accessed using the Instrument Object's LoadSymbol function.


The LoadSymbol function uses the BPV Instrument Type as a container to access an instrument in a script section where instrument context is not automatically provided.  Examples showing how to create the scripts statements is available in the LoadSymbol topic.


The LoadSymbol function can also be used to bring additional instruments into a script location where another instrument is active.  This ability to access more than one instrument provides information that might influence how the script logic might want to consider.  An example of how this can  be used is with a spread value difference between two instruments, or a ranking comparison of group of instruments.


Script sections where instrument context in automatic by default is shown in the Blox Script Timing table, and in the table here.


Instrument Data:

Instrument data loaded from a symbol's data file cannot be changed by scripting, but it is easy to retrieve data in script sections where Trading Blox Builder  provides Automatic Instrument Context.  


Adding other information to an instrument is done by adding an IPV variable.  There is no practical limit to how many variables can be added to an instrument.  IPV additional variables listed in the IPV list section are available when the instrument is being accessed.  Instruments it can be used in testing or reporting.  User added information can be changed during a test using script statements.  


Instrument Objects have many functions for different purposes.  For example, when updating an instrument's protective stop, the instrument.SetExitStop will update a position's protective exit price after a new price has been calculated so that it is active for the next price bar.


Script sections where Automatic Instrument Context is not provided, scripting can use the Instrument Object's LoadSymbol function to gain access to a specific instrument's information.  The Instrument Object's LoadSymbol function can be used in a looping structure that accesses many or all of the instruments in the portfolio.


These script sections get get automatic instrument context.  

Automatic Instrument Context Script Sections:

Rank Instrument

Can Fill Order

Filter Portfolio

Exit Order Filled

Before Instrument Day

After Instrument Open

Exit Orders

Adjust Stops

Entry Orders

Compute Instrument Risk

Unit Size

Adjust Instrument Risk

Can Add Unit

After Instrument Day

Update Indicators



Click Blox Script Timing to get more information about when these scripts sections are available to access.


How to know when a script section has instrument context?

Use the  Trading Blox Builder Basic property block.instrumentExists.  Wen this property returns a True (or a 1) the script section where this property is accessed will have automatic instrument-context.  If the return is a False, that script section will need the LoadSymbol() function to access an instrument's information.


Script sections that do not automatically provide instrument context will always need the LoadSymbol() function.  When multiple instruments are looped into the same BPV Instrument variable name, the information in the BPV instrument name will change to last instrument that was accessed.  


The LoadSymbol()function loads  symbol's information as a bi-directional connection.  This means that information changed in the BPV instrument name that is the load symbol's information container, that change will be represented in the instrument object's information for that symbol.  When the instrument is changed in the instrument object in later processing, the information will also change in the BPV instrument information if the same instrument is still in the BPV instrument.


Does Automatic Instrument Context allow access to IPV variables?

Yes.   Any data specific to a symbol is available once the instrument-context has been established.  This happens when a script section is automatic-context, and it is available when an instrument is assigned to a BPV instrument type using the LoadSymbol()function.


Click LoadSymbol for more information.

BPV Instrument-Context Variable Example:

Click to Enlarge; Click to Reduce.

BPV Instrument Variable Type

This BPV Instrument Type and LoadSymbol() function can used with any symbol that is available.  It can also be used to access information in another system that is in the same test suite.   Access to instruments in other systems in the same suite requires the test.SetAlternateSystem(systemIndex) example.


When a BPV Instrument Type variable is used to load an instrument's information, that name can be used elsewhere in the module to reference the values of the last loaded instrument.  In some cases a series of BPV - Instrument types are created with recognizable names so they can each load a different instrument and provide simple access to that instrument's information whether it is in context or not where it is needed.


When an instrument doesn't get automatic context, or an additional instrument is needed in script were it is provided (think spreads), this example can be used to make an additional symbol accessible.


'  In a script with Automatic-Context, this is how
'  the date of the instrument record is obtained.
variable1 =
'  In a script section where Automatic Instrument-Context is Not
'  provided, this is how an instrument's record date is obtained
'  Create a BPV Instrument Type name that will accept an instrument's
'  information (See BPV Dialog Above).
'  Call LoadSymbol with a instrument's reference.  
'  Next example is using the instrument's symbol.
'  There are more ways for LoadSymbol to bring an
'  instrument into context and so the instrument's
'  information can be assigned.

'  Set the portfolio instrument.
aBpvName.LoadSymbol( "GC" )

'  Pass the instrument's date to another variable
anyDate =


Scripts with automatic instrument context will execute the same script name for each of the instruments in the portfolio.  This repetitive loop of each instrument is necessary so that all the symbols in the portfolio have a chance to be processed on each test date.  Click this topic Comprehensive Simulation Loop for more information about the testing process actions.


When an instrument doesn't have a data current date the next market date, the instrument record that will be processed with the previous record in the data file.  When an instrument does not have a current date for the next market date, the instrument.tradesOnTradeBar property will return a False value so scripting can prevent a calculation from counting a previous record more than once.  When there is a current date for the next market date, the return is True.


Instrument Priming:

When indicators are contained in a system, the parameter with the largest calculation look-back value will determine when the system can be allowed to generate orders.  This means a system that is expected to generate orders by the Suite Start-Date will need information before that Start-Date so there no Start-Date trading delay.  


How much data is needed can be calculated, but the value must be the enough for all the calculations in the system to have begun their calculations prior to the planned Start-Date.


Trading Blox helps to make this possible by examining the parameters in the system that have enabled the parameter’s Look-Back option.  


When this option is enabled, Trading Blox Builder will use all the available data ahead of the Start-Date so that the calculations will be primed and ready for the system.


Providing data to be available for calculation is controlled by the user’s “Years of Priming” setting in the Data Folders and Options section of the Trading Blox Builder Preference setting dialog:

Years-of-Priming Preference Setting

By default, this setting is set at “5” years of information.  This means that  Trading Blox Builder will attempt to load up to five-years of available records for each of the instruments in system’s portfolio.  This extra-data value allows the system to begin calculation ahead or on the Start-Date set for testing to begin.  When there isn't enough data to start on the Start-Date, Trading Blox Builder will begin the system's calculation at the earliest possible time.  


Some instruments in the portfolio may not have enough trading information ahead of the Start-Date.  When the system encounters this condition, any instrument that hasn't primed its calculation will not be allowed to trade until its data is primed.  However, once the look-back requirements are met, the Instrument Priming.


To know when an instrument has been primed for the current look-back requirements, use the instrument.isPrimed property.  When this property returns a TRUE (or 1) value, the instrument is ready to test.  When a FALSE (or a 0) is the returned, the instrument has not been primed.


  '  Is this instrument primed?
  If instrument.isPrimed = TRUE THEN
    '  Instrument is ready for testing
  ENDIF '  i.isPrimed = TRUE


System Testing Sequencing:

When a test is started, Trading Blox Builder creates a list of all the trade day dates that from the start, usually this means just the weekday dates.


The dates used in a test day numbers in the test.currentDay property.  


Edit Time: 3/7/2018 3:53:36 PM

Topic ID#: 112


Created with Help & Manual 7 and styled with Premium Pack Version 2.80 © by EC Software