In ScanExpert, the user script (i.e, the grid layout) would typically be created using the ScanExpert Wizard module. In the Wizard, you select and/or build all of the indicators that will be used, create any required user-defined conditions and/or alerts, select the columns that will actually be displayed in ScanExpert, and customize the column titles.
While we refer to it as a "user script" in reality it is intended to be more of a layout definition file for the main grid and, while you can integrate custom logic and/or functions into a user script, in most cases it is more efficient to implement the custom logic in the form of a study formula. In fact, prior to Version 1.0.15.0 of ScanExpert, the user script was only called AFTER all historical data was loaded and processed so the functionality of any customizations was limited.
Other than minor customizations or cosmetic changes, in general you should avoid editing user scripts for the following reasons:
| • | Once you customize a user script in any way, you will no longer be able to use the Wizard to make changes to that script. When a script is created by the Wizard, a binary definition file is created in the Scripts folder. If you make changes to a user script outside of the Wizard, those changes will NOT be reflected in the binary definition file. If you pull that user script back into the Wizard to make changes and/or generate a new copy of the script, any customizations that you applied outside of the Wizard will be lost. |
| • | Due to the internal structure of ScanExpert the code in study formulas is processed much more efficiently than code in a user script. Keeping all calculations in study formulas and outside of the user script results in lower memory requirements and faster processing time. |
| • | Multi-interval data is not guaranteed to be synchronized in the context of the user script, while it is synchronized in study formulas. So, for example, if you build a user script that accesses price data and/or indicators created on different bar intervals, the user script will be called each time new price data comes in on the portfolio interval but there is no guarantee that price data from alternate bar intervals has even been processed yet. So any custom formulas that you implement directly in the user script that depend on price data from alternate bar intervals (or depend on other studies based on that price data) may not update correctly. In the context of a study formula, however, any time a component data source (regardless of interval) is updated, the study formula will be updated and synchronized to reflect the correct calculations as of that price bar. |
So, unlike the eSignal EFS environment where you would typically pack most of the functionality and formulas directly into the main script, in ScanExpert it is much more efficient (and accurate) to offload all calculations and analyses to the realm of study formulas, and leave the user script untouched.
If you do find a need to integrate custom logic directly into a user script, you need to be aware of how and when that code will be executed so that you can place the code in the correct location.
Logic that must be Primed with Historical Data
For logic that must begin executing as of the first bar of historical price data, you should place this code AFTER the script initialization block but BEFORE the "isHistoryLoaded" check. If you generate a script in the Wizard you will see tags in the source code that identify this.
Remember that a user script is called whenever a new price bar (in the portfolio bar interval) comes in AND whenever a intrabar update takes place. So if you have custom logic that, for example, must only be executed once per bar then you need to set up your logic accordingly.
Logic that does NOT need to be primed with Historical Data.
Logic that does not need to be primed with historical data should be placed AFTER the "isHistoryLoaded" check but BEFORE the "Grid.Return" call.
If you generate a script with the Wizard that makes use of Conditions and/or Alerts, you will see that the calls to those condition or alert functions are placed AFTER the "isHistoryLoaded" check. This is because we definitely do not want alerts being triggered while historical data is being loaded....we only want alerts to go off in realtime.
Variables
If you require any custom variables to be used in conjunction with the custom logic that you are adding to the user script, declare these variables in the "Global Variable Declaration" section.
In terms of the scope of global variables, please note that Integers, Doubles, and Booleans will all retain their state between iterations of the script. However String variables and Static Array variables WILL NOT retain their state between iterations of the script.
General Guidelines
| • | Never explicitly call the "Initialize" function that you see at the top of each user script. This function is called internally by ScanExpert and is roughly the equivalent of the preMain() function in eSignal EFS. |
| • | If you create custom functions in the user script, you should place these functions AFTER the "Global Variable Declaration" section and BEFORE the "Script Begins" section. This is the same general area where Alert functions and Condition functions will be placed by the Wizard if that functionality is used. |
| • | Be sure to use Symbol.getBarState() and similar constructs to control the execution of your logic. |
| • | Bear in mind how much price data you have available. By default, ScanExpert will download 300 bars of price data for each symbol in your portfolio. This number can be adjusted up to 600 bars in the ScanExpert Configuration Manager. If you are using 24-hour 1-min bars and, for example, you write a custom function in your user script to record the open price of the first bar of the day...depending upon when you run this script during the day you may or may not obtain that value. There are 1440 1-min bars in a 24-hour day so even if you preload 600 bars there may not be enough data available to obtain the price as of the first bar of the day. |
| • | Check your work carefully and look for possible logic errors (i.e., divide by zero conditions, etc.). |
| • | Use the Syntax Check feature in the Editor to check your work any time you customize a user script. |
| • | To test your work, create a portfolio of one or two symbols and run your modified script against this portfolio. |
| • | Use the debugPrint() function in conjunction with the Formula Debug Window as a debugging tool |