Extending your SE:ISDK/C application with compiled libraries

Methods for adding compiled C/C++ object libraries to your application, and how to permit your customers to add additional extensions with SE:RTEx.

The ScriptEase language environment is extended by adding compiled objects and libraries. The primary reason you are using the SE:ISDK/C is to allow the javascript language to interact with your compiled application, and so the most important compiled objects and libraries are those wrapper functions you provide around your own application. But there are additional extension modules, beyond those directly related to your particular application, which can increase the utility and power of any script and can, therefore, increase the utility and power of your application. In this newsletter I will describe the various ways to add those extensions libraries to your application.

The "Standard" Native ECMAScript Objects

The ECMAScript-262 standard defines a set of native objects that are assumed to be part of any conforming ECMAScript implementation; these objects are: Global, Object, Function, Array, String, Boolean, Number, Math, Date, RegExp, and Error. In the SE:ISDK most of these objects are written in the same way as any other extension library discussed here. Because they are part of the standard they are enabled by default with the ISDK/C, but you can compile with them in, or out, just like any of the other extension libraries discussed here. For example, you may be working in a small footprint environment where you think Date and RegExp use more resources than they're worth, so you may choose to disable them (e.g. #define JSE_ECMA_DATE 0, #define JSE_ECMA_REGEXP 0); or you may decide to turn these objects into link libraries, available only to the occasional script that may need to #link to them as needed.

Internal Objects vs Link Libraries

By definition, an "Internal Object" is one that is always available to scripts because it is compiled into your application, and a "Link Library" is one that is not compiled into your application and is only available to scripts via the "#link" syntax.

Although we often talk about Internal Objects and Link Libraries, and the SE manuals divide these two types of libraries into separate chapters, the only real difference between them is whether you choose to compile them into your application or make them only available through the #link syntax. The SE:ISDK/C manual chapter "Integrating Language Objects & Libraries" explains in detail how to enable any particular library, or even subsets of any library. Briefly, you alter jseopt.h to define the libraries to add, define whether the library is internal or link, add the source files to your project, and compile.

How to allow 3rd parties to extend your application with
SE:RTEx: ScriptEase RunTime Extension

SE:RTEx is a subset of the SE:ISDK/C that contains the tools to create a #link library. These #link libraries rely on the existence of a running SE engine, such as the one built into your application. A version of SE:RTEx is freely available to any developer via the SE:RTEx web-page.

There are many scenarios in which you may find SE:RTEx useful:

If you decide to enable #link libraries in your application, simply compile with "#define JSE_LINK 1" in your jseopt.h file. If don't want just any #link file to be available to your application, but only those that you have developed or that have been developed with your own proprietary changes to SE:RTEx, then you can use the jseFileFindFunc() callback function (defined in the jseExternalLinkParameters structure) to examine the link library before it is loaded.

Example1: Adding Socket library internal to simple1 sample

In this example, the SIMPLE1 sample, which shipped with SE:ISDK/C in the seisdk/samples/simple1 directory, will use the "#link <sesock>" command to make a socket library available to the script, and will use that library to retrieve a web page.

The jseopt.h file for simple1 does not explicitly set the JSE_LINK value, and so by default #link is enabled. If you have built the SESOCK link library (see makefiles in extlib/sesock) then the simple1 sample is ready to use it. In other words, simple1 is already set up to use #link libraries. Here's a simple script you could supply to the simple1 executable to retrieve and print the HTML for Nombas' home page:

   #link <sesock>
   var sock = new Socket("www.nombasxxx.com",80);
   if ( sock == null )
      Clib.puts("socket open failed\n");
   else
   {
      var getstr = "GET / HTTP:/1.0\r\n"
                 + "Accept: */*\r\n\r\n";
      sock.write(getstr,getstr.length);
      var value = "";
      while( 1 )
      {
         var buf = "";
         var amount = sock.read(buf,256);
         if( amount < 1 )
            break;
         value += buf;
      }
      sock.close();
      Clib.puts(value);
   }

As seen here, the simple "#link <sesock>" statement has added a powerful new capability to the simple1 sample.

Example2: Adding Socket library internal to simple1 sample

As in example1, the simple1 sample will make the socket library available to scripts, but in this case the socket library will be built in.

Although it's not necessary, you could disable the #link command for this example by adding "#define JSE_LINK 0" to your jseopt.h file or makefiles. Next add this statement to your jseopt.h file to tell it that we want all of the socket functions available: "#define JSE_SOCKET_ALL". Finally, add the C files in the srclib/socket directory and srcmisc/inet.c to your make project, along with any compiler libraries needed to enable sockets (for windows that is wsock32.lib), and compile.

The same script uses in example1 above, but without the #link statement, will now execute with simple1.

Other ways to extend script capabilities

This newsletter has covered only script extensions using C libraries compiled for SE:ISDK/C applications. There are many other related ways to extend your scripts, which I may cover in a future letter. These are

Related information

Have a question about how to use ScriptEase:ISDK? Let Dr. Scripter know at http://support.nombasxxx.com/