MORE SPECIAL EVENT DRIVEN FUNCTIONS Going forward, I will be referring to the post March 2014 start functions I've considered in recent posts as "special event driven functions" rather than as "new start functions." And as it turns out, the OnStart(), OnCalculate(), and OnTick() functions are just the first three among several special event driven functions I need to learn about, all of which will begin with the word "On." Two event driven functions that are always included among the files by default in an indicator or EA when starting from an empty template—whether they are desired or not—are the OnInit() function and the OnDeinit() function. Other special event driven functions include OnTimer() and OnChartEvent().
An EA has two ways of taking action: either when a new tick comes in, or when a timer is triggered. You can set a timer which, for example, triggers every minute. The actions performed on a new tick can be different from action triggered by the timer.
PASSING BY REFERENCE When I typed the example of what an OnCalculate() function looks like in real code, I took a moment to explain the meaning of const, but I did not bother explaining the meaning of the ampersand (&) because it would have interrupted the flow of the subject matter. At this point, that is not a problem, so I am going to address the ampersand here… The terms time, open, high, low, close, volume, and spread in the above text represent certain parameters, or values... values to which different places in your code might need to have access. However, if each of them copied the given value, and then one of them needed to change that value, all of the other places in your program would still be working with the old (i.e., wrong) original number. If you failed to update the rest of the program with the new number, different parts of your code would end up using different values for the same variable—and that would be a problem! To avoid this, instead of the function retrieving the value itself, the ampersand sends it to an "address" where the value is stored—a location in memory where the value of the parameter is tucked away. So then, the & means: "the address of" and what it does is called… ...passing a parameter by reference. The actual address will be a long hexadecimal number that might look something like this: 0x0000003B. Since all of the different places in your code will have access to this one address where the parameter can be found, if any of them modifies or alters the parameter, all of them will instantly be dealing with (will be "passed") that same updated value, because they will all be getting if from (will be referred to) that same identical address.
The OnInit() Function This is one of two special event driven functions that are always included among the files if starting with an empty template. This is the function that the platform looks for first, which only makes sense, given that it initializes stuff and sets up parameters as designated by whatever's typed between its braces. Accordingly, if it is used, it runs the moment a file is attached to the chart, before any other function, including the OnStart() (the script) function. It can be of either the void or int data type. If the latter, it will need to include a return() function in order to return something at the end. (An example of each appears below.) void OnInit() { Xxxxxx xxxxx xx xxxxx xxxxxx; } int OnInit() { Xxxxxx xxxxx xx xxxxx xxxxxx; return(INIT_SUCCEEDED); } But, wait just a cotton picking second! Isn't the int data type supposed to return an integer? Yes it is, so what I need to understand is that INIT_SUCCEEDED is defined as being equivalent to zero (0) so that what the program will "see" is a "0" whenever it reads INIT_SUCCEEDED. There is another predefined term—INIT_FAILED—which the program will always read as the numeral "1." Whenever the OnInit() function returns this integer, the function will quit running. The advantage of using words that the program "sees" as the numbers instead of the numbers themselves is that the words are able to better communicate (express more clearly) what is happening or going on with the program than would using either of those two digits. Be aware however that whereas a return(0) in any other int type function would ordinarily just make the function stop running and wait for the next event… in the OnInit() function it has the special meaning that everything went fine on initialization and that it is therefore okay to proceed to the next task or function. The fact that other int type functions might also return the numeral 1 is not an issue, because it is only with the OnInit() function that this signifies something is wrong and that the program will therefore stop anything else from happening until it is fixed. Accordingly, you can use the OnInit() function to check to see that you are doing everything in accordance with whatever parameters you have set or require so that it will go no further whenever or if ever this is not the case.
The OnDeinit() Function This is the second/other function that is always included in the files when creating/writing code starting from an empty template. It runs when a program is removed from a chart. The platform uses it to keep track of why the program got de-initialized (but typically, whatever this reason is will not concern you). Like the OnCalculate() function, it always has something (const int reason), which appears between its parentheses when you opt to use it, as illustrated below... void OnDeinit(const int reason) { Xxxxxxx xxxx xx xxxxxx xxxxxxx; }
Metaquotes Software Corporation Added These Two Special Event Driven Functions in February 2014… The OnTimer() Function You can use this void data type function to generate a "fake" tick event (to artificially fire off the OnTick() function) when testing code on the weekend (when the markets will not be generating any ticks). You do so by typing OnTick() between its braces: void OnTimer() { OnTick() } What you are doing is using the OnTimer () function to call the OnTick() function. (Functions calling other functions is a major part of programming, as is functions calling return().) Firing off the OnTick() function is normally accomplished by something that is included in the OnInit() function and is set when the EA starts. To make this happen via the OnTimer() function requires the use of a function called EventSetTimer(), which is typed between the braces of the OnInit() function, as illustrated below... void OnInit() { EventSetTimer(1); } The number which appears between the parentheses specifies how often, in seconds, the OnTimer() function will fire off. (In the above example, it is set to fire off every second.) (The second special event driven function introduced in February 2014 is the On Tester() function, but I have yet to come across a description of how it is utilized.) If you want or need the OnTimer() function to update the time more frequently, you can use EventSetMillisecondTimer() insted of EventSetTimer(). For example, if you wanted it to update every half second (i.e., every 500 milliseconds), you would type the number 500 between the parentheses, like so... void OnInit() { EventSetMillisecondTimer(500) } In my next post I will write directions for how to use the functions discussed thus far to create a Local Time Expert Advisor.
HOW TO DISPLAY YOUR LOCAL TIME ON YOUR CHARTS: Click on the MetaQuotes Language Editor Icon. When the MetaEditor opens up, click on File in the upper left-hand menu and select New Project from the drop-down menu. Then use the MQL Wizard: Project window that appears to select Expert Advisor (template) from among your options, and then click on the Next > button. Fill in the Name (but do not delete Experts\), Author and Link, and then click the Next > button. In the next window, select the OnTimer Expert Advisor event handler, and the click the Next > button once again. Since you won’t need a Tester event handler, simply click on the Next > when the new window opens. When the new window appears, click on the Local Timemq4 tab in the upper left-hand corner, if necessary, since this is where you will be working—not in Local Time mqproj. You will see that you are starting with four functions: The initialization and de-initialization functions, the start function for expert advisors, and the OnTimer function which you will be using to artificially fire off the EA starter function via the EventSetTimer() function. So, there are the three things you need to do… First go to the initialization function (where the program has automatically created an EventSetTimer() function to be used by the OnTimer() function once things get going), and change the number 60 to the numeral 1 to let the OnTimer() function know that you want it to tell the EA function to fire off once every second instead of once every minute. Second, go to the OnTimer function and have it call the EA function (above it) so that it can tell the EA to fire off once every second. Do this by typing the name of the EA function between its braces. And finally, tell the EA function to display in the comment section (in the upper left-hand corner of the chart) what it is doing once every second by typing the Comment() and LocalTime() functions between its braces...
HOW TO DISPLAY THE LOCAL TIME ON YOUR CHARTS—PART II: As previously mentioned, expert advisers are responsible for executing tasks, such as managing trades. However, the only thing that the EA which was just created in the previous post did was display the local time; and delivering or displaying information is the job of a (custom) indicator—not the job of an expert advisor. Accordingly, this post will explain how to display the local time using a custom indicator. So then, why even bother with the previous exercise? Recall that it was to illustrate how you can make an EA run, even when no ticks are coming in, by using the OnTimer() function to call the OnTick() function containing the Comment() function line. Another reason that it is better to use a custom indicator for this kind of task is that only one EA can be put on a chart at a time. So, if an EA is used just to display information, there is not going to be any way to have the program execute and/or manage trades. It therefore makes more sense to code the local time as a custom indicator rather than an expert advisor. Do this by using the following steps... STEP ONE: As before, click on the MetaQuotes Language Editor Icon, and when the MetaEditor opens up, click on File in the upper left-hand menu and select New Project from the drop-down menu. However, this time, when the MQL Wizard: Project window appears, select the Custom Indicator option rather than Expert Advisor (template). Then click on the Next > button. STEP TWO: Once again, fill in the Name (but do not delete Indicators\), Author and Link, and then click the Next > button. STEP THREE: In the window that follows, select the OnTimer custom indicator event handler, and then click the Next > Button once again. STEP FOUR: My guess is that the "Indicator in separate window" option is for creating lower panel indicators, which you will not be doing. So, skip this widow by simply clicking on the Finish button and move on. STEP FIVE: Click on the Local Time.mq4 tab if necessary, and then go to the initialization function and insert the timer line, which is… EventSetTimer(1); …directly under the words: "indicator buffers mapping." STEP SIX: Note that the next section is for the Custom indicator iteration function. In other words, this time the template did not automatically provide an OnDeinit() function for the EvenKillTime() function to terminate the relevant/related activity at the proper time. Consequently, you will need to copy and paste the corresponding text from the previous expert advisor. Here it is again… //+------------------------------------------------------------------+ //| Expert deinitialization function | //+------------------------------------------------------------------+ void OnDeinit(const int reason) { //--- destroy timer EventKillTimer(); // } STEP SEVEN: Note that in actuality, the OnCalculate() function will not be used in this indicator. Nonetheless, the Custom indicator iteration function text must remain given that an indicator will not compile without it, because without it, the program will recognize that this is an indicator. So, just skip this section and move on to the Timer function. STEP EIGHT: Before, when you created the EA, the OnTimer() function had to call the expert advisor function so that it could tell it to fire off every second, which was then told in turn to display what it was doing in the chart's comment section. But here, you are simply going to tell the timer function to display this information directly itself by typing Comment (TimeLocal()); between its braces... STEP NINE: Click on the Compile button. If you get an error, double click the error to make in jump the cursor to where the problem is.
Very interesting, I'm following along in MQL5. For your EA, I'm not quite sure why you take the circuitous route of OnTimer() -> OnTick() -> Comment(), when you can just have OnTimer() calling Comment(), with OnTick() empty.