Project

General

Profile

Definition of the links between Scol language and DLL functions » History » Version 2

ModularMix, 10/14/2011 04:52 PM

1 1 ModularMix
h1. Definition of the links between Scol language and DLL functions
2 1 ModularMix
3 2 ModularMix
This article shows the possibility to add new functions to Scol language using the integration of plugins written in C language.
4 1 ModularMix
5 2 ModularMix
h2. Creation of a simple function "HelloWorld"
6 1 ModularMix
7 2 ModularMix
We will create our first C function which we will be able to call from Scol language.
8 2 ModularMix
This function will allow to display a log message ("Hello World") in the Scol console.
9 2 ModularMix
The first thing to do right here is to write the C function. It's important to take a look at the function signature, because it takes a *machine* object as a parameter and returns an integer.
10 1 ModularMix
11 2 ModularMix
It's also important to notice *MMechostr* function from the Scol API. This method takes as parameters the log level (*MSKFOO*, *MSKRUNTIME*, *MSKWARNING*, *MSKTRACE* or *MSKDEBUG*) and the message to log.
12 2 ModularMix
13 2 ModularMix
Finally, we have to notice *MMset* function which purpose is to set a value for the first element of Scol stack (in our case, an integer which value is 0), this one corresponding to *the return value of the Scol function*, accordingly to the expected Scol prototype (*fun [ ] I*, a function without any parameter and returning an integer).
14 2 ModularMix
<pre>
15 1 ModularMix
 /*! @ingroup group1
16 1 ModularMix
  * \brief _HelloWorld : Log a "Hello World" message in the console
17 1 ModularMix
  *
18 1 ModularMix
  * <b>Prototype:</b> fun [] I
19 1 ModularMix
  *
20 1 ModularMix
  * \return I : 0 in all cases.
21 1 ModularMix
  **/
22 1 ModularMix
 int _HelloWorld(mmachine m)
23 1 ModularMix
 {
24 1 ModularMix
     // Show the message
25 1 ModularMix
     MMechostr(MSKRUNTIME, "Hello World!");
26 1 ModularMix
 
27 1 ModularMix
     // Scol return value.
28 1 ModularMix
     MMset(m,0,0);
29 1 ModularMix
 
30 1 ModularMix
     return 0;
31 1 ModularMix
 }
32 2 ModularMix
</pre>
33 2 ModularMix
34 2 ModularMix
h2. Binding between C and Scol
35 2 ModularMix
36 2 ModularMix
To be able to call the function *HelloWorld* directly from Scol language, we have to register it. The function from the Scol API enabling it is *PKhardpak*.
37 2 ModularMix
<pre>
38 2 ModularMix
 /*!
39 2 ModularMix
  * \brief Load the template functions
40 2 ModularMix
  *
41 2 ModularMix
  * \param mmachine : scol machine structure
42 2 ModularMix
  *
43 2 ModularMix
  * \return int : 0 if succes, error code otherwise
44 2 ModularMix
  **/
45 2 ModularMix
 int LoadTemplate(mmachine m)
46 2 ModularMix
 {
47 2 ModularMix
     int k;
48 2 ModularMix
  
49 2 ModularMix
     // Load package
50 2 ModularMix
     k = PKhardpak(m, "TemplateEngine", NbTplPKG, TplName, TplFunc, TplNArg, TplType);
51 2 ModularMix
     return k;
52 2 ModularMix
 }
53 2 ModularMix
</pre>
54 2 ModularMix
55 2 ModularMix
The parameters of the function are the following :
56 2 ModularMix
* *NbTplPKG* : the number of functions we have to export to Scol (the different arrays described below must have as many values as this number)
57 2 ModularMix
* *TplName* : an array containing the name of the functions as they will be called in a Scol source code
58 2 ModularMix
* *TplFunc* : an array of pointers to C functions, corresponding to the bindings of Scol functions to their equivalent in C language
59 2 ModularMix
* *TplNArg* : an array of integers representing the number of arguments expected for each function
60 2 ModularMix
* *TplType* :  an array of strings containing the Scol prototypes for each function
61 2 ModularMix
62 2 ModularMix
*WARNING* : If several functions are being exported, we have to make sure that for all the arrays, the functions are in the same order.
63 2 ModularMix
64 2 ModularMix
Now, we can inject the following source code just before calling *PKhardpak*. A good habit is to use the same name for the Scol function and for the C function because is simplifies the edition of the documentation and the revision of the source code.
65 2 ModularMix
<pre>
66 2 ModularMix
 //! Nb of Scol functions or types
67 2 ModularMix
 #define NbTplPKG	1
68 2 ModularMix
 
69 2 ModularMix
 /*!
70 2 ModularMix
  * Scol function names
71 2 ModularMix
  **/
72 2 ModularMix
 char* TplName[NbTplPKG] =
73 2 ModularMix
 {
74 2 ModularMix
     "_HelloWorld"
75 2 ModularMix
 };
76 2 ModularMix
 
77 2 ModularMix
 /*!
78 2 ModularMix
  * Pointers to C functions that manipulate the VM for each scol function previously defined
79 2 ModularMix
  **/
80 2 ModularMix
 int (*TplFunc[NbTplPKG])(mmachine m)=
81 2 ModularMix
 {
82 2 ModularMix
     _HelloWorld
83 2 ModularMix
 };
84 2 ModularMix
 
85 2 ModularMix
 /*!
86 2 ModularMix
  * Nb of arguments of each scol function
87 2 ModularMix
  **/
88 2 ModularMix
 int TplNArg[NbTplPKG]=
89 2 ModularMix
 {
90 2 ModularMix
     0
91 2 ModularMix
 };
92 2 ModularMix
 
93 2 ModularMix
 /*!
94 2 ModularMix
  * Prototypes of the scol functions
95 2 ModularMix
  **/
96 2 ModularMix
 char* TplType[NbTplPKG]=
97 2 ModularMix
 {
98 2 ModularMix
     "fun [] I"          // _HelloWorld
99 2 ModularMix
 };
100 2 ModularMix
</pre>
101 2 ModularMix
102 2 ModularMix
103 2 ModularMix
To finish the binding of the C function, all we need to do is to call the function named *LoadTemplate* when the plugin is being initialized, that is to say in *SCOLloadTemplate* function. The content of this one should now be the following :
104 2 ModularMix
<pre>
105 2 ModularMix
 /*! 
106 2 ModularMix
  * \brief Starting point of the DLL
107 2 ModularMix
  **/
108 2 ModularMix
 extern "C" __declspec (dllexport) 
109 2 ModularMix
 int SCOLloadTemplate(mmachine m, cbmachine w)
110 2 ModularMix
 {
111 2 ModularMix
    SCOLinitplugin(w);
112 2 ModularMix
    // Get Scol window handle (for message callback)
113 2 ModularMix
    HScol = (HWND)SCgetExtra("hscol");
114 2 ModularMix
 
115 2 ModularMix
    // Display debug message
116 2 ModularMix
    MMechostr(MSKDEBUG,"Loading Template DLL ...\n");	
117 2 ModularMix
    return LoadTemplate(m);
118 2 ModularMix
 }
119 2 ModularMix
</pre>
120 2 ModularMix
121 2 ModularMix
After that, it's now possible to compile the project and move the DLL file into the *plugins* directory of the Scol Voyager installation folder, which is usually *C:\Program Files (x86)\Scol Voyager*.
122 2 ModularMix
123 2 ModularMix
h2. Use of the new function in Scol language
124 2 ModularMix
125 2 ModularMix
We will now create a new Scol source code, in which we will call our function previously created.
126 2 ModularMix
Let's create a new file called *template.pkg* in the Scol Voyager user partition, which is usually located in *My Documents\Scol Voyager\Partition_LocalUsr*. The file will only contain a main function  calling our *HelloWorld* method :
127 2 ModularMix
<pre>
128 2 ModularMix
 /*! \brief Sample main function that log a "Hello World" message.
129 2 ModularMix
  *
130 2 ModularMix
  *  <b>Prototype:</b> fun [] I
131 2 ModularMix
  *
132 2 ModularMix
  *  \return I : 0
133 2 ModularMix
  **/
134 2 ModularMix
 fun main()=
135 2 ModularMix
   _HelloWorld;;
136 2 ModularMix
</pre>
137 2 ModularMix
138 2 ModularMix
Let's create another file in our user partition, named *HelloWorld.scol*. This program will load the package *template.pkg* that we have just created, and run its *main* function :
139 2 ModularMix
<pre>
140 2 ModularMix
 _load "template.pkg"
141 2 ModularMix
 main
142 2 ModularMix
</pre>
143 2 ModularMix
144 2 ModularMix
Now, we can run the program *HelloWorld.scol* and notice that the log message we've defined in the C function is displayed in Scol console.