In the last section we looked at the layout of a study formula. After you write your first study formula, you will need to register that study formula with the ScanExpert system so that it recognizes your new indicator as a valid study object. You do this by creating an entry in a ScanExpert configuration file called functionsUser.pas. If you have not already done so, please review the Objects and Concepts section.
To recap from the Objects and Concepts section, there are two configuration files in ScanExpert that contain the necessary registration information for all study formulas in the system:
| • | functionsSystem.pas: Contains the study declarations for all of the built-in study formulas. You will NEVER edit this file but you can certainly view it, or print it out, and use it as a reference. |
| • | functionsUser.pas: Contains the study declarations for any custom study formulas that you write (or that others may send to you). This is the configuration file that you will edit and, again, you can use the functionsSystem.pas file as a reference. The two configuration files serve the same purpose. The only difference is that functionsSystem.pas is used to store the built-in studies while functionsUser.pas is used to store your custom study formulas. This distinction is important when it comes to program updates. The functionsSystem.pas file will always be overwritten when new ScanExpert program updates are installed (i.e., so that we can add new built-in study formulas as we develop them) while the functionsUser.pas file will not be touched. So while there is nothing that will prevent you from adding your custom study formulas into the functionsSystem.pas file instead of into the functionsUser.pas file, if you do so you will lose all of those custom study declarations the next time you install a ScanExpert program update. |
Both of these files are located in the Studies folder of the ScanExpert data directory, under My Documents.
Registering a Study Formula: Example
For example purposes, let us assume that we want to install the SMA study that we looked at in the last section as a new custom study in ScanExpert.
| • | Pull up the functionsUser.pas file in the Editor. If you have not previously added any custom study formulas then it will look something like this: |
| • | To register our custom study formula with the system, we need to: |
| • | Decide on a study formula function name. This name will be used to reference our custom study formula both in the Wizard and in any user scripts that we write ourselves. The name we choose should be descriptive and it must be unique (i.e., there can be no other study formula with the same function name in either the functionsSystem.pas or the functionsUser.pas configuration files); |
| • | Decide on a Wizard category (i.e., where in the Wizard Study Selection box we want our study formula displayed); |
| • | Specify a parameter name and parameter type for all input parameters; |
| • | Specify source input streams names (and type) for all input streams; |
| • | Call the actual study formula source file. |
Here is what this might look like:
We will go over this line-by-line.
| • | In the first line we assign our study formula to a category called "Averages". The category name that you select can be a category that already exists in the Wizard or it can be a completely new category, that is entirely up to you. The important thing is that you format the category definition correctly. |
{Category: <CatName>}
| • | The format is always curly brace, followed by the string "Category:", followed by the category name that you wish to use, followed by a closing curly brace. The category definition should always be on a line by itself. |
| • | The next line is our actual function declaration: |
function mySimpleMA( period: integer; source1: TEStream; inv: string=' ' ) : TEStream;
| • | The name of this study formula is "mySimpleMA". You can select any function name that you wish. Just make sure that it is at least somewhat descriptive and make sure that it is unique (i.e., that there is no other study formula, built-in or otherwise, that shares the same function name). |
| • | Our simple moving average study formula takes one input parameter (an Integer) and one input stream (a TEStream object). How do we know this? Well we determined this when we "wrote" the study formula in the last section. By the time you get to this part of the process (i.e., registering your custom study formula with the ScanExpert system) you will already know the number and type of input parameters as well as the number of input streams required by your custom study formula. |
| • | The names we have chosen for these two variables are "period" and "source1" respectively. Again, as with the actual function name, you can select any names you wish for your input parameters and streams. In practice it is best to keep them short and descriptive. |
| • | The last parameter in our function declaration is the bar interval that our study formula will be using. |
... inv: string=' ' ) : TEStream;
| • | Now we did not see anything about a bar interval in our discussion of the layout of a study formula file in the last section. That is because the study formula itself does not need this information. The assignment of the input stream (and therefore the bar interval associated with the input stream) is handled by ScanExpert. All the study formula needs is at least one input stream....it does not care what bar interval that stream comes from. |
| • | If you look through the functionsSystem.pas configuration file you will see that every built-in study formula has an inv interval parameter. Any custom study formulas that you develop will need to use it as well. |
| • | At the very end of our function declaration we have: |
) : TEStream;
| • | This indicates to the system the type of object being returned by our study formula. All study formulas return a stream object of type TEStream, no exceptions. |
| • | The next lines make the call to our underlying study formula source file. |
begin
result := Grid.createStudy( 'dsSMAStudy.pas', [period], [interval(inv,source1)] );
end;
| • | This is handled by the createStudy() method of the Grid object. The createStudy() method takes 3 parameters: |
| • | The file name of the study formula file; |
| • | An array containing all of the input parameters; |
| • | An array containing all of the input streams; |
| • | In our example, the name of the study formula file that we are calling is dsSMAStudy.pas. Any custom study formula(s) that you create will obviously have a different file name. |
| • | In our example, we have only one input parameter, called period. If we had more than one input parameter we would simply separate them with a comma. For example: |
[period,smoothing,factor1]
| • | Note the square brackets that enclose our list of parameters, these are required. |
| • | In our example, we have only one input stream, called source1. If we had more than one input stream we would simply separate them with a comma. For example: |
[interval(inv,source1),interval(inv,source2),interval(inv,source3)]
| • | Again, note the square brackets. All input streams will be formatted in exactly the same way in all custom study formulas that you create. |
Testing your Work
After you have finished typing in your custom study formula declaration, press the Syntax Check button in the Editor to check your work. If any syntax errors are found, you will be directed to the line number where the error occurred. When you are comfortable that there are no errors, launch the ScanExpert Wizard and check to see if your new study formula shows up in the list of available studies.
If your new custom study formula appears in the Wizard list of available studies (as it should) then you are ready to begin testing. You should use the Wizard to create a small script that just calls your new study formula. Generate the script and run it in ScanExpert Viewer with a small portfolio of symbols (i.e., 2 or 3). If any errors are generated at runtime, go back into the study formula source file and fix the problem(s) and then test again. Repeat this process until you are comfortable that the study formula is operating correctly as well as returning the correct calculation.
Add Parameter and Usage Information