Introduction

Next

What is the ESPL language ?

The Ensign Software Programming Language (ESPL) allows Ensign Windows users to develop and program custom tools for Chart Studies, Reports, Custom Symbols, Trading Systems, Draw Tools, etc.

How was the ESPL developed for Ensign Windows ?

Ensign Software developed the language specifically for 'Ensign Windows'.  The language is very similar to Delphi and Pascal.  There are over 300 functions and commands.  The language can be thought of as a large toolbox, from which you can build many programs.

How do I get started ?

First you should open the ESPL Script Editor Window and get familiar with how to use it.  Next, start reading the ESPL documentation and learn how to write some small programs.  Build on your knowledge by further reading, and studying ESPL examples.

Are there any books that I can read to learn the ESPL language ?

Any books that teach basic programming for Delphi would be helpful.  However, the best resources include the On-Line ESPL Help documentation, and the Ensign Software ESPL Reference Manual.

What if I don't want to learn programming ?

Ensign Software can provide references to programmers who can develop a custom ESPL tool for you (for a fee). 

Learning to Use the ESPL Script Editor Window

In order to program a tool in the ESPL Language you must first open and become familiar with the ESPL Script Editor Window.  This is where you type-in the programming code, and run the programs.

1) To open the ESPL Script Editor Window click on the ESPL button on the main toolbar, or select File | Open | ESPL Editor from the menu.  This will open the Script Editor Window.  The window contains a Code window (the left half of the window), an Output window (the right half of the window), and several buttons.  The ESPL programs are typed into the Code window.  The Output window can be used to print output and reports from your programs.

2) Position the ESPL Script Editor Window on the screen so that the Code window and Output window are both comfortably visible.  A center divider can be dragged left or right to adjust the size of the Code and Output windows.

3) Learning the buttons in the ESPL Script Editor Window

New
Open
Save (default saves to the \ensign\macro folder )
Cut (Ctrl-X)
Copy (Ctrl-C)
Paste (Ctrl-V)
? Opens the Help window
Clear the Output window
Start a Timer
RUN (ESPL=0)
1-9 Additional RUN buttons (ESPL=1-9)
Close Closes the ESPL window
Line Indicates what Line of the program the cursor is on

Writing your first Program

ESPL programs must start with the begin statement, and end with the end; statement.  One of the first ESPL programming commands to learn should be the Writeln command.  This command allows you to print text in the Output window (the command stands for 'write line' ).  Type the following program in the Code window, and then click the RUN button .

begin
  writeln('Hello World');
end;

The words Hello World will print in the OUTPUT window.

Make sure that you include the parentheses and single quotes on each side of the text. Make sure that you always complete each ESPL line with a semi-colon ' ; ' (except the begin statement).  The semi-colon is used as a separator character and indicates the end of a command.  Spaces and carriage returns are ignored.  For example, the following program is exactly the same as the program above.

begin writeln('Hello World'); end;

NOTE: Programming languages are very picky in how you type-in the program commands.  The rules for each command are known as the Syntax.  You must obey the defined Syntax or each command to avoid program errors or 'bugs'.  Programming errors will be reported to you in the Output window.  The error will indicate which Line the error occurred on, and suggest a possible cause.  This helps you to debug your program.  'Bug' is the word used to indicate a problem with a program.  When you find and fix the error in the Syntax or program Logic, then you have 'fixed the bug'.  For example, if you fail to include a semi-colon at the end of a program command then an error will be reported.

Understanding the 'ESPL'  variable

When a program is RUN in the ESPL language, there is a variable (named 'ESPL') that is assigned a specific numeric value.  For example, clicking on the RUN button assigns 'ESPL' the value of 0 (zero).  You can program ESPL commands to RUN only when the 'ESPL' value contains a certain value.  Use the If…Then command to determine if the 'ESPL' value is correct for your program.  Change your code to the following program which will print Buy Here in the Output window if the 'ESPL' value equals 1.

begin
  if ESPL = 1 then writeln('Buy Here');
end;

You could add the previous Hello World print statement to RUN when 'ESPL' equals 0 (zero).

begin
  if ESPL = 0 then writeln('Hello World');
  if ESPL = 1 then writeln('Buy Here');
end;

Click on ESPL button 1 in the Script Editor window to RUN the program with an 'ESPL' value of 1.
Click the RUN button in the Script Editor windows to RUN the program with an 'ESPL' value of 0.

Additional print statements could be added to the program with reference to other 'ESPL' values. The following shows how to print Sell Here by clicking on button 2.

begin
   if ESPL = 0 then writeln('Hello World');
   if ESPL = 1 then writeln('Buy Here');
   if ESPL = 2 then writeln('Sell Here');
end;

The Output window can be cleared (or erased), by using the Output(eClear); statement. We can add this feature to the ESPL program as follows (when 'ESPL' equals 3).

begin
   if ESPL = 0 then writeln('Hello World');
   if ESPL = 1 then writeln('Buy Here');
   if ESPL = 2 then writeln('Sell Here');
   if ESPL = 3 then Output(eClear);
end;

Click on buttons 1, 2, 3 or RUN to see the printing and clearing in the Output window.

Sounds can be added to ESPL programs using the Beep and Play commands.  The Beep command will play a simple beep sound through the computer speakers.  The Play command can be used to play a specific sound file from the computer.  The Play command requires that you specify the exact Path and Filename of the sound file that you want to hear.  The following example adds these commands to our growing program (using 'ESPL' values of 4 and 5). Click buttons 4 and 5 in the ESPL Script Editor window to hear the sounds.

begin
  if ESPL = 0 then writeln('Hello World');
  if ESPL = 1 then writeln('Buy Here');
  if ESPL = 2 then writeln('Sell Here');
  if ESPL = 3 then Output(eClear);
  if ESPL = 4 then Beep;
  if ESPL = 5 then Play('c:\windows\media\chord.wav');
end;

Charts can be opened from an ESPL program by using the Chart command. The Chart command requires that you specify the chart file to open. The following example will open a daily IBM chart when 'ESPL' equals 6.

begin
  if ESPL = 0 then writeln('Hello World');
  if ESPL = 1 then writeln('Buy Here');
  if ESPL = 2 then writeln('Sell Here');
  if ESPL = 3 then Output(eClear);
  if ESPL = 4 then Beep;
  if ESPL = 5 then Play('c:\windows\media\chord.wav');
  if ESPL = 6 then Chart('IBM.D');
end;

Introduction to Customized Chart Studies

Custom studies can be programmed and plotted on charts using the ESPL language.  Almost any line or calculation imaginable can be programmed in ESPL and plotted on a chart.  The following program example will illustrate how to draw two lines.  One will connect all of the bar High prices on a chart.  The second line will connect all of the bar Low prices on a chart.

Custom studies are RUN by clicking the 'RUN' button, and then an ESPL Studies button (from 51 to 59).  For example, if you click on ESPL button 51, then the 'ESPL'  variable will equal 51.  The ESPL program can test for  'ESPL=51'  and RUN the appropriate code.

In the following example, a sub-routine Procedure (a separate section of program code) has been added that contains the programming code to draw the High and Low lines.  The procedure has been named 'ColorHighLow' (any name could have been used).  If the 'ESPL' value equals 51, then the 'ColorHighLow' programming code will be run.  This means that the ESPL program will jump up to the 'ColorHighLow' procedure code and RUN the commands there.  The 'ColorHighLow' procedure uses a For loop, and the Plot command to loop through all the chart bars and plot the two lines.  The example which follows is the entire program that should be showing in the editor.

To RUN the program, you must first open a chart.  Once the chart is open, then click the ESPL button 51.  The two lines will be drawn on the chart (connecting all the Highs and Lows).  The study will remain active on the chart until you remove the study.  The study will be live and continue to draw and update the lines as new bars are added to the chart during the day.  Some comments have been added to the program to help explain some of the code.  Comments begin with two forward slash characters // and are ignored by the ESPL program.  The finished program should look like the following.  If desired, you can Copy and Paste the code directly into the ESPL Script Editor window to try the program for yourself.

procedure ColorHighLow;                  // 'ColorHighLow' procedure is declared
var i: integer;                          // A variable named 'i' is declared
begin                                    // Start of the procedure code
  SetUser(ePlot1,True); SetUser(eShow1,True);
  SetUser(ePlot2,True); SetUser(eShow2,True);
  SetUser(eWindow,0);                    // Plot on the chart
  SetUser(ePercent,false);               // Plot using price scale
  for i := BarBegin to BarEnd do         // Loop through all the bars
  begin                                  // Start of the Loop code
    Plot(1,High(i),i);                   // Draw a Line between the Highs
    Plot(2,Low(i),i);                    // Draw a Line between the Lows
  end;                                   // End of the Loop code
end;                                     // End of the procedure
 
                                         //***Main Program***
begin                                    // Start of Main Program
  if ESPL=0 then writeln('Hello World');  // Print if ESPL=0
  if ESPL=1 then writeln('Buy Here');     // Print if ESPL=1
  if ESPL=2 then writeln('Sell Here');    // Print if ESPL=2
  if ESPL=3 then Output(eClear);          // Clear if ESPL=3
  if ESPL=4 then Beep;                    // Beep if ESPL=4
  if ESPL=5 then Play('c:\windows\media\chord.wav');   // Play if ESPL=5
  if ESPL=6 then Chart('IBM.D');          // Open IBM chart if ESPL=6
  if ESPL=51 then ColorHighLow;           // Run 'ColorHighLow' if ESPL=51
end;                                     // End of Main Program

You can save the program by clicking on the 'Save' button in the ESPL Script Editor window.

Note:  Procedures that are called (referenced) from the Main Program, must be typed-in and declared before the Main Program code.  Notice that the 'ColorHighLow' procedure is entered in the program before (above) the Main Progam code.  Happy programming.  Get your feet wet, and then start experimenting with new commands and ideas.

Next