Including libraries; #import of functions

Functions are imported from compiled MQL5 modules (*.ex5 files) and from Windows dynamic library modules (*.dll files). The module name is specified in the #import directive, followed by descriptions of the imported function prototypes. Such a block must end with another #import directive, moreover, it can be without a name and simply close the block itself, or the name of another library can be specified in the directive, and thus the next import block begins at the same time. A series of import blocks should always end with a directive without a library name.

In its simplest form, the directive looks like this:

The name of the library file can be specified without the extension: then the DLL is assumed by default. Extension ex5 is required.

The name may be preceded by the library location path. By default, if there is no path, the libraries are searched in the folder MQL5/Libraries or in the folder next to the MQL program where the library is connected. Otherwise, different rules are applied to search for libraries depending on whether the type is DLL or EX5. These rules are covered in a separate section.

Here is an example of sequential import blocks from two libraries:

With such directives, imported functions can be called from the source code in the same way as functions defined directly in the MQL program itself. All technical issues with loading libraries and redirecting calls to third-party modules are handled by the MQL program execution environment.

In order for the compiler to correctly issue the call to the imported function and organize the passing of parameters, a complete description is required: with the result type, with all parameters, modifiers, and default values, if they are present in the source.

Since the imported functions are outside of the compiled module, the compiler cannot check the correctness of the passed parameters and return values. Any discrepancy between the format of the expected and received data will result in an error during the execution of the program, and this may manifest itself as a critical program stop, or unexpected behavior.

If the library could not be loaded or the called imported function was not found, the MQL program terminates with a corresponding message in the log. The program will not be able to run until the problem is resolved, for example, by modifying and recompiling, placing the required library in one of the places along the search path, or allowing the use of the DLL (for DLLs only).

When sharing multiple libraries (doesn't matter if it's DLL or EX5), remember that they must have different names, regardless of their location directories. All imported functions get a scope that matches the name of the library file, that is, it is a kind of namespace, implicitly allocated for each included library.

Imported functions can have any names, including those that match the names of built-in functions (although this is not recommended). Moreover, it is possible to simultaneously import functions with the same names from different modules. In such cases, the operation context permissions should be applied to determine which function should be called.

For example:

Let's see a simple example of the script LibRandTest.mq5, which uses functions from the EX5 library created in the previous section.

In the input parameters, you can select the number of elements in the array of numbers, the distribution parameters, as well as the step of the histogram, which we will calculate to make sure that the distribution approximately corresponds to the normal law.

Initialization of the random number generator built into MQL5 (uniform distribution) is performed by the value of the RandomSeed or, if 0 is left here, GetTickCount is picked (new at each start).

To build a histogram, we use MapArray and QuickSortStructT (we have already worked with them in the sections on multicurrency indicators and about array sorting, respectively). The map will accumulate counters of hitting random numbers in the cells of the histogram with a HistogramStep step.

To display a histogram based on the map, you need to be able to sort the map in key-value order. To do this, we had to define a derived class.

Note that the COMMA macro becomes an alternate representation of the comma character ',' and is used when another SORT_STRUCT macro is called. If not for this substitution, the comma inside the Pair<K,V> would be interpreted by the preprocessor as a normal macro parameter separator, as a result of which 4 parameters would be received at the input of SORT_STRUCT instead of the expected 3 — this would cause a compilation error. The preprocessor knows nothing about the MQL5 syntax.

At the beginning of OnStart, after initialization of the generator, we check the receipt of a single random string and an array of strings of different lengths.

Next, we test normally distributed random numbers.

Here is the result when run with default settings (timer randomization - each run will choose a new seed).

In this library, we have only exported and imported functions with built-in types. However, object interfaces with structures, classes, and templates are much more interesting and more in demand from a practical point of view. We will talk about the nuances of their use in libraries in a separate section.

When testing Expert Advisors and indicators in the tester, one should keep in mind an important point related to libraries. Libraries required for the main tested MQL program are determined automatically from the #import directives. However, if a custom indicator is called from the main program, to which some library is connected, then it is necessary to explicitly indicate in the program properties that it indirectly depends on a particular library. This is done with the directive:
 
#property tester_library "path_library_name.extension"