Like any normal CODESYS library, an external CODESYS library consists of reusable library elements. The difference to normal CODESYS libraries is that some of these library elements implemented inside the run-time system with the help of languages like in C or C++.
Creating an external CODESYS library can therefore be done in exactly the same way as creating a normal CODESYS library. Only those elements that are to be implemented within the runtime system must be flagged in a special dialog.
Such an external library member is usually included as a function in a list of external references and downloaded to the runtime system, where the reference will be resolved to the physical function object.
The functions implemented within the runtime system must have a unique name!
The name of an external library function is resolved in lower case in the runtime system!
This external name is configurable by decorating the IEC function or function block with the attribute „external_name“
{attribute 'external_name':='STO_BlobAlloc'}
FUNCTION BlobAlloc : POINTER TO STO_BLOB (* pBlob *)
VAR_INPUT
szData : CAA.SIZE;
END_VAR
VAR_OUTPUT
eError : ERROR;
END_VAR
In this case the function will not be identified with the function "BlobAlloc" of the runtime system, but with the function name "sto_bloballoc".
As there is only one implementation of a function or function block within the runtime system, only the library version with exactly this implementation may be used in the project! This is typically realized by the placeholder the library (see Placeholder). Therefore the placeholder definition for an external library is typically deposited in the device description.
An external library function is made known to the runtime system as part of a configuration file in *.m4 format. CODESYS provides the possibility to automatically export all externally implemented members of a library to a *.m4 file for the runtime system, so that incompatibilities between the library and the implementation in the runtime system are almost precluded.
In the created interface file (called Itf.m4 file) all externally implemented members of a library are represented by their names (as defined in CODESYS or specified by the attribute „external_name“), their interfaces, the version of the library and the checksum of the interface. Via an m4 compiler this file has to be translated into an ANSI-C interface Header file.
Note
Data types like STRUCT, ENUMS, ... can be are also marked as external implemented. So the attribute „external_name“ is useful for type names too.
Furthermore CODESYS provides the possibility that a C-Source frame for the implementation is generated. Within the runtime system the interface header file (<LibraryName>Itf.h) and the source file (<LibraryName>.c) may then be used as base for implementing a component containing the implementation of the external members of this library. Afterwards this component can be included into the runtime system.
There are few attributes to control the m4 export of an external library member:
m4export:
Force m4-Export independent of the "External Link in runtime" option
m4export_hide:
Hide function, function block, interface, structure or enum from m4-Export
m4export_nosignature:
Don't export a signature for this function or method
m4export_32bit_nosignature:
Don't export a signature for 32-Bit targets
m4export_64bit_nosignature:
Don't export a signature for 64-Bit targets
m4export_enum-as-c:
Export an IEC enum as C enum.
Attention
This worked only for a typed enum in IEC from type DINT!
m4export_enum-no-prefix:
Don't export the name of the enum as a prefix at every enum constant
m4export_stringlen-as-value:
Export a string len in IEC with its value:
MY_STRING_LEN : INT := 100;
mystring : STRING(MY_STRING_LEN);
⟹
char mystring[101];
m4export_stringlen-as-is:
Export a string len in IEC with its value:
MY_STRING_LEN : INT := 100;
mystring : STRING(MY_STRING_LEN);
⟹
char mystring[MY_STRING_LEN];
m4export_arraylen-as-value:
Export an array in IEC with its value:
MY_ARRAY_LEN : INT := 100;
mystring : ARRAY [0..MY_ARRAY_LEN];
⟹
codesyschar mystring[101];
m4export_arraylen-as-is:
Export an array in IEC with its value:
MY_ARRAY_LEN : INT := 100;
mystring : ARRAY [0..MY_ARRAY_LEN];
⟹
char mystring[MY_ARRAY_LEN];
Note
When setting external implementation property in a non constant GVL the warning C0187 is displayed by the compiler. Furthermore the M4-Export ignores non-constant GVL variables, meaning no #define is generated for its variables.
