Download MetaTrader 5

How to Exchange Data: A DLL for MQL5 in 10 Minutes

27 January 2010, 13:31
MetaQuotes
22
17 142

As a matter of fact, there are not many developers who remember exactly how to write a simple DLL library and what are features of binding different systems.

Using several examples, I will try to show the entire process of the simple DLL's creation in 10 minutes, as well as to discuss some technical details of our binding implementation. We will use Visual Studio 2005/2008; its Express versions are free and can be downloaded from the Microsoft website.

1. Creating a DLL project in C++ in Visual Studio 2005/2008

Run the Win32 Application Wizard using the 'File -> New' menu, select the project type as 'Visual C++', choose 'Win32 Console Application' template and define the project name (for example, 'MQL5DLLSamples'). Select a root directory for storing project 'Location', instead of the default offered one, disable the checkbox of 'Create directory for solution' and click 'OK':

Fig. 1. Win32 Application Wizard, DLL project creation

On the next step press 'Next' to go to the settings page:

Fig. 2. Win32 Application Wizard, project settings

On the final page, select the 'DLL' application type, leaving other fields empty as they are, and click 'Finish'. Don't set the 'Export symbols' option, if you don't want to remove the demonstration code added automatically:

Fig. 3. Win32 Application Wizard, Application settings

As a result you will have an empty project:

Fig. 4. The empty DLL project prepared by Wizard

To simplify testing, it's better to specify in 'Output Directory' options the output of DLL files directly to '...\MQL5\Libraries' of the client terminal - further, it will save you much time:

Fig. 5. DLL output directory


2. Preparing to Add Functions

Add '_DLLAPI' macro at end of the stdafx.h file, so that you can conveniently and easily describe exported functions:

//+------------------------------------------------------------------+
//|                                                 MQL5 DLL Samples |
//|                   Copyright 2001-2010, MetaQuotes Software Corp. |
//|                                        http://www.metaquotes.net |
//+------------------------------------------------------------------+
#pragma once

#include "targetver.h"

#define WIN32_LEAN_AND_MEAN             // Exclude rarely-used stuff from Windows headers
#include <windows.h>

//---
#define _DLLAPI extern "C" __declspec(dllexport)
//+------------------------------------------------------------------+

The DLL imported functions calls in MQL5 should have the stdcall and cdecl calling convention. Though stdcall and cdecl differ in the ways of parameter extracting from a stack, the MQL5 runtime environment can safely use both versions because of the special wrapper of DLL calls.

The C++ compiler uses  __cdecl calling by default, but I recommend explicitly specifying the __stdcall mode for exported functions.

A correctly written export function must have the following form:

_DLLAPI int __stdcall fnCalculateSpeed(int &res1,double &res2)
  {
   return(0);
  }

In a MQL5 program, the function should be defined and called as follows:

#import "MQL5DLLSamples.dll"
int  fnCalculateSpeed(int &res1,double &res2);
#import

//--- call
   speed=fnCalculateSpeed(res_int,res_double);

After the project compilation, this stdcall will be displayed in the export table as _fnCalculateSpeed@8, where the compiler adds an underscore and number of bytes, transmitted through the stack. Such a decoration allows to better control the security of DLL functions calls due to the fact that the caller knows exactly how many (but not the type of!) data that should be placed in the stack.

If the final size of the parameter block has an error in the DLL function import description, the function won't be called, and the new message will appear in the journal: 'Cannot find 'fnCrashTestParametersStdCall' in 'MQL5DLLSamples.dll'. In such cases it is necessary to carefully check all the parameters both in the function prototype and in the DLL source.

The search for the simplified description without decoration is used for compatibility in case the export table does not contain the full function name. Names like fnCalculateSpeed are created if functions are defined in the __cdecl format.
_DLLAPI int fnCalculateSpeed(int &res1,double &res2)
  {
   return(0);
  }


3. Methods to Pass Parameters and Exchange Data

Let's consider several variants of passed parameters:

  1. Receiving and passing of simple variables
    The case of simple variables is easy - they can be passed by value or by reference using &.
    _DLLAPI int __stdcall fnCalculateSpeed(int &res1,double &res2)
      {
       int    res_int=0;
       double res_double=0.0;
       int    start=GetTickCount();
    //--- simple math calculations
       for(int i=0;i<=10000000;i++)
         {
          res_int+=i*i;
          res_int++;
          res_double+=i*i;
          res_double++;
         }
    //--- set calculation results
       res1=res_int;
       res2=res_double;
    //--- return calculation time 
       return(GetTickCount()-start);
      }
        
    Call from MQL5:
    #import "MQL5DLLSamples.dll"
    int  fnCalculateSpeed(int &res1,double &res2);
    #import
    
    //--- calling the function for calculations
       int    speed=0;
       int    res_int=0;
       double res_double=0.0;
    
       speed=fnCalculateSpeed(res_int,res_double);
       Print("Time ",speed," msec, int: ",res_int," double: ",res_double);
    
    The output is:
    MQL5DLL Test (GBPUSD,M1) 19:56:42 Time  16  msec, int:  -752584127  double:  17247836076609
  2. Receiving and passing of an array with elements filling

    Unlike other MQL5 programs, array passing is performed through the direct reference to the data buffer without access to proprietary information about the dimensions and sizes. That's why the array dimension and size should be passed separately.

    _DLLAPI void __stdcall fnFillArray(int *arr,const int arr_size)
      {
    //--- check for the input parameters
       if(arr==NULL || arr_size<1) return;
    //--- fill array with values
       for(int i=0;i<arr_size;i++) arr[i]=i;
      }
        
    Call from MQL5:
    #import "MQL5DLLSamples.dll"
    void fnFillArray(int &arr[],int arr_size);
    #import
    
    //--- call for the array filling
       int    arr[];
       string result="Array: "; 
       ArrayResize(arr,10);
       
       fnFillArray(arr,ArraySize(arr));
       for(int i=0;i<ArraySize(arr);i++) result=result+IntegerToString(arr[i])+" ";
       Print(result);
    
    The output is:
    MQL5DLL Test (GBPUSD,M1) 20:31:12 Array: 0 1 2 3 4 5 6 7 8 9 
  3. Passing and modification of strings
    The unicode strings are passed using direct references to its buffer addresses without passing of any additional information.
    _DLLAPI void fnReplaceString(wchar_t *text,wchar_t *from,wchar_t *to)
      {
       wchar_t *cp;
    //--- parameters check
       if(text==NULL || from==NULL || to==NULL) return;
       if(wcslen(from)!=wcslen(to))             return;
    //--- search for substring
       if((cp=wcsstr(text,from))==NULL)         return;
    //--- replace it
       memcpy(cp,to,wcslen(to)*sizeof(wchar_t));
      }
    
    Call from MQL5:
    #import "MQL5DLLSamples.dll"
    void fnReplaceString(string text,string from,string to);
    #import
    
    //--- modify the string
       string text="A quick brown fox jumps over the lazy dog"; 
       
       fnReplaceString(text,"fox","cat");
       Print("Replace: ",text);
    The result is:
    MQL5DLL Test (GBPUSD,M1) 19:56:42 Replace:  A quick brown fox jumps over the lazy dog
    It's turned out that the line hadn't changed! This is a common mistake of newbies when they transmit copies of objects (a string is an object), instead of referring to them. The copy of the string 'text' has been automatically created that has been modified in the DLL, and then it has been removed automatically without affecting the original.

    To remedy this situation, it's necessary to pass a string by reference. To do it, simply modify the block of importing by adding & to the "text" parameter:
    #import "MQL5DLLSamples.dll"
    void fnReplaceString(string &text,string from,string to);
    #import
    After compilation and start we will get the right result:
    MQL5DLL Test (GBPUSD,M1) 19:58:31 Replace:  A quick brown cat jumps over the lazy dog

4. Catching of exceptions in DLL functions

To prevent the terminal crushes, each DLL call is protected automatically by Unhandled Exception Wrapping. This mechanism allows protecting from the most of standard errors (memory access errors, division by zero, etc.)

To see how the mechanism works, let's create the following code:

_DLLAPI void __stdcall fnCrashTest(int *arr)
  {
//--- wait for receipt of a zero reference to call the exception
   *arr=0;
  }

and call it from the client terminal:

#import "MQL5DLLSamples.dll"
void fnCrashTest(int arr);
#import

//--- call for the crash (the execution environment will catch the exception and prevent the client terminal crush)
   fnCrashTest(NULL);
   Print("You won't see this text!");
//---

As s result, it will try to write to the zero address and generate an exception. The client terminal will catch it, log it to the journal and continue its work:

MQL5DLL Test (GBPUSD,M1) 20:31:12 Access violation write to 0x00000000

5. DLL calls wrapper and loss of speed on calls

As already described above, every call of DLL functions is wrapped into a special wrapper in order to ensure safety. This binding masks the basic code, replaces the stack, supports stdcall / cdecl agreements and monitors exceptions within the functions called.

This volume of works doesn't lead to a significant delay of function calling.

6. The final build

Let's collect all the above DLL functions examples in the 'MQL5DLLSamples.cpp' file, and MQL5 examples in the script 'MQL5DLL Test.mq5'. The final project for Visual Studio 2008 and the script in MQL5 are attached to the article.

//+------------------------------------------------------------------+
//|                                                 MQL5 DLL Samples |
//|                   Copyright 2001-2010, MetaQuotes Software Corp. |
//|                                        http://www.metaquotes.net |
//+------------------------------------------------------------------+
#include "stdafx.h"

//+------------------------------------------------------------------+
//| Passing and receving of simple variables                         |
//+------------------------------------------------------------------+
_DLLAPI int __stdcall fnCalculateSpeed(int &res1,double &res2)
  {
   int    res_int=0;
   double res_double=0.0;
   int    start=GetTickCount();
//--- simple math calculations
   for(int i=0;i<=10000000;i++)
     {
      res_int+=i*i;
      res_int++;
      res_double+=i*i;
      res_double++;
     }
//--- set calculation results
   res1=res_int;
   res2=res_double;
//--- return calculation time
   return(GetTickCount()-start);
  }
//+------------------------------------------------------------------+
//| Filling the array with values                                    |
//+------------------------------------------------------------------+
_DLLAPI void __stdcall fnFillArray(int *arr,const int arr_size)
  {
//--- check input variables
   if(arr==NULL || arr_size<1) return;
//--- fill array with values
   for(int i=0;i<arr_size;i++) arr[i]=i;
  }
//+------------------------------------------------------------------+
//| The substring replacement of the text string                     |
//| the string is passed as direct reference to the string content   |
//+------------------------------------------------------------------+
_DLLAPI void fnReplaceString(wchar_t *text,wchar_t *from,wchar_t *to)
  {
   wchar_t *cp;
//--- parameters checking
   if(text==NULL || from==NULL || to==NULL) return;
   if(wcslen(from)!=wcslen(to))             return;
//--- search for substring
   if((cp=wcsstr(text,from))==NULL)         return;
//--- replace it 
   memcpy(cp,to,wcslen(to)*sizeof(wchar_t));
  }
//+------------------------------------------------------------------+
//| Call for the crush                                               |
//+------------------------------------------------------------------+
_DLLAPI void __stdcall fnCrashTest(int *arr)
  {
//--- wait for receipt of a zero reference to call the exception
   *arr=0;
  }
//+------------------------------------------------------------------+

//+------------------------------------------------------------------+
//|                                                 MQL5DLL Test.mq5 |
//|                        Copyright 2010, MetaQuotes Software Corp. |
//|                                              http://www.mql5.com |
//+------------------------------------------------------------------+
#property copyright "2010, MetaQuotes Software Corp."
#property link      "http://www.mql5.com"
#property version   "1.00"
//---
#import "MQL5DLLSamples.dll"
int  fnCalculateSpeed(int &res1,double &res2);
void fnFillArray(int &arr[],int arr_size);
void fnReplaceString(string text,string from,string to);
void fnCrashTest(int arr);
#import

//+------------------------------------------------------------------+
//| Script program start function                                    |
//+------------------------------------------------------------------+
void OnStart()
  {
//--- calling the function for calculations
   int    speed=0;
   int    res_int=0;
   double res_double=0.0;

   speed=fnCalculateSpeed(res_int,res_double);
   Print("Time ",speed," msec, int: ",res_int," double: ",res_double);
//--- call for the array filling
   int    arr[];
   string result="Array: "; 
   ArrayResize(arr,10);
   
   fnFillArray(arr,ArraySize(arr));
   for(int i=0;i<ArraySize(arr);i++) result=result+IntegerToString(arr[i])+" ";
   Print(result);
//--- modifying the string
   string text="A quick brown fox jumps over the lazy dog"; 
   
   fnReplaceString(text,"fox","cat");
   Print("Replace: ",text);
//--- and finally call a crash
//--- (the execution environment will catch the exception and prevent the client terminal crush)
   fnCrashTest(NULL);
   Print("You won't see this text!");
//---
  }
//+------------------------------------------------------------------+

Thank you for your interest! I am ready to answer any questions.

Translated from Russian by MetaQuotes Software Corp.
Original article: https://www.mql5.com/ru/articles/18

Attached files |
mql5dll_test.mq5 (1.83 KB)
mql5dllsamples.zip (4.62 KB)
Last comments | Go to discussion (22)
Pasi Hakamaki
Pasi Hakamaki | 3 Nov 2013 at 12:17
RyanLeland:

Anyone know how to create a 64 bit DLL or allow MQL5 to load a 32 bit DLL? MQ5 is not loading my test script because my DLL is "not 64-bit". Thanks.

This can be fixed, instructions here: Solution Explorer -> Right Click Solution -> Configuration Manager -> Active solution platform drop down menu -> select x64 -> click Close -> Rebuild Solution

Hope this helps.

Good luck.

jaycode
jaycode | 5 Sep 2014 at 19:28

Hello,

This does not work with DLL produced by Microsoft Visual Studio 2013 Express edition, see attached.

It does not seem to find the library MSVCR120D_APP.DLL and an issue with KERNEL_32 as well. 

Has anyone got similar issue? How can I workaround this, please?

Thank you

mt5_developer
mt5_developer | 18 Nov 2014 at 10:39

Does mql5 support import dll which include callback functions?

 

for example:

There's a dll named tclient.dll, which include function below:

typedef TCLIENT_API void(*call_back)(Tick* p); 

TCLIENT_API int sub_tick(CTX ctx, const char* insId, call_back f);  

 

Then how should I declare and call sub_tick in mql5?

#import "tclient.dll"

//how to declare function "sub_tick" 

#import 

 

void ontick(Tick &ticks[])

{}

int OnInit()

{

//how to call function "sub_tick"? 

gcha2262
gcha2262 | 11 Aug 2015 at 09:37

Hey 

 I was wondering whether you could help me a bit with the Mt5 and Matlab interaction. I've done the tutorials you've suggested. The only problem is that the script is successfully loaded and successfully removed in the logs, but does not display any of the stuff that I want to print. What am i doing wrong?

 Thanks so much for you help 

Filip
Filip | 13 Sep 2015 at 10:55

I just went through this tutorial but using the new VC 14 (2015) ... first I got the messsage in the journal : "cannot load dll" without a reason, but then I figured out, that the solution adjustments built a win32 dll... in the solution explorer, right clight on the solution ,klick on configuratuion manager.

there the platform can changed to x64. after rebuild the new generated dll could be loaded and I was able to call my demo function..


yay.. thanks for this article !


Filip

Step on New Rails: Custom Indicators in MQL5 Step on New Rails: Custom Indicators in MQL5

I will not list all of the new possibilities and features of the new terminal and language. They are numerous, and some novelties are worth the discussion in a separate article. Also there is no code here, written with object-oriented programming, it is a too serous topic to be simply mentioned in a context as additional advantages for developers. In this article we will consider the indicators, their structure, drawing, types and their programming details, as compared to MQL4. I hope that this article will be useful both for beginners and experienced developers, maybe some of them will find something new.

Here Comes the New MetaTrader 5 and MQL5 Here Comes the New MetaTrader 5 and MQL5

This is just a brief review of MetaTrader 5. I can't describe all the system's new features for such a short time period - the testing started on 2009.09.09. This is a symbolical date, and I am sure it will be a lucky number. A few days have passed since I got the beta version of the MetaTrader 5 terminal and MQL5. I haven't managed to try all its features, but I am already impressed.

Using text files for storing input parameters of Expert Advisors, indicators and scripts Using text files for storing input parameters of Expert Advisors, indicators and scripts

The article describes the application of text files for storing dynamic objects, arrays and other variables used as properties of Expert Advisors, indicators and scripts. The files serve as a convenient addition to the functionality of standard tools offered by MQL languages.

How to create an indicator of non-standard charts for MetaTrader Market How to create an indicator of non-standard charts for MetaTrader Market

Through offline charts, programming in MQL4, and reasonable willingness, you can get a variety of chart types: "Point & Figure", "Renko", "Kagi", "Range bars", equivolume charts, etc. In this article, we will show how this can be achieved without using DLL, and therefore such "two-for-one" indicators can be published and purchased from the Market.