ScriptEase:ISDK Newsletter

Jan. 11, 2002

In This Issue


Introducing SE:ISDK Version 5

ISDK/C 4.30e Errata

ISDK/C 4.40d Errata

ISDK/Java 4.30e Errata

Other Newsletters

DevSpace Developer Support

For more information and resources, visit ScriptEase: ISDK DevSpace online.

Download Center

For latest updates and extensions, visit the ISDK Download Center.

"" Introducing SE:ISDK Version 5, the next generation in embedding script development

A brief description of the Version 5 release of the ScriptEase:Integration SDK: the major changes involved, when to use Version 5, and how to get started.

The new year brings with it the most significant improvement in script-language integration since Nombas introduced script development tools nearly a decade ago. Over the past few years we have reexamined how software developers want to integrate with a script language engine. We have reviewed the technical support incidents to learn about bottlenecks and areas of inefficiency. We have talked many developers through their integration issues.

We have redesigned, from the ground up, the ScriptEase API and development tools.

Why mess with a good thing?

SE:ISDK has always been the best way to integrate scripting into any application--SE:ISDK has always been easier to work with, and more powerful and flexible, than any internal or 3rd party alternative. But the basic SE interfaces (API and tools) have not changed in nearly ten years, even as the script language itself has matured, the number of target platforms and users has exploded, and the development platforms have become much more sophisticated.

ScriptEase ISDK Version 5 is the result of our efforts to outdo ourselves.

Version 5 API

The Version 5 API is designed to be both Pure and Easy. Pure because every interaction with the engine involves a single simple concept: the object/member pair. Easy because 1) the API maps directly to the behavior of the language itself, and 2) the API (like the script language itself) is very lenient.

Pure API: Everything is an object/member pair

At its heart, the ECMAScript language is designed to manipulate members of objects. And when ECMAScript is used to interact with C/C++/Java, its fundamental purpose is to manipulate members of objects. With these realizations the API becomes a very pure description for how to read and write members of objects.

In Version 5, nearly every API is just a specification for manipulating an object/member pair. Because this is such a straightforward concept, and because it maps so directly to the underlying language, working with this new API quickly becomes much less complex than with other methods. This object/member paradigm is extended to nearly every interaction with the interpreter engine: this includes getting and setting script object members, of course, but also parameter settings like reading the stack (members of the stack object) or setting engine options (members of the interpreter-engine object). This direct approach allows a developer to get up to speed quickly and to soon become a master of scripting integration.

Easy API: script-like forgiveness

In other language-integration methods, including the previous ScriptEase APIs, the C/C++/Java interface is very rigid, as is expected of a low-level system language. However, the language being implemented (ECMAScript) is inherently very flexible. We have learned, from many, many integration projects, that the rigidity of the API leads to many lines of code and to many hours of development time--if all possibilities are to be foreseen. And, since all possibilities are never foreseen, the rigid API contributes to errors. In summary, the old, rigid APIs lead to code that is bloated and bug-prone.

In contrast, the new Version 5 API is very concise and lenient. The engine converts data internally and even in the case of an error always returns valid data. This allows much simpler code and errors or unexpected situations are automatically handled by the engine in a JavaScript way. In other words, if there is an underlying error the Version 5 engine will propagate an exception at the appropriate time, but your code WILL receive the data type you request, and your code may manipulate that data without fear of crashing. Similar lenience applies to writing data.

For example, suppose you needed to write a wrapper function that was supposed to take the "text" member of whatever object was passed to it, and print that "text" member to the screen. With the traditional API that would look something like this:

  1. if a parameter is not passed, generate an error and return
  2. get the first parameter
  3. if the parameter is not an object, generate an error and return
  4. if the parameter object does not have a "text" member, generate an error and return
  5. if the text member is not a string type, convert it to a string type
  6. if conversion to string fails, generate an error and return
  7. get the string
  8. call library function to print string to the screen

If any of the verifications or conversions were skipped, the program may crash. With the new Version V API, the required steps are:

  1. get, as an object, member 0 of the arguments object
  2. get, as a string, the "text" member of that object
  3. call library function to print string to the screen

The working and fully safe C code to perform this in Version 5 could be:

 SE_CALLBACK(void) WriteTextMember(secontext se,int argc)
    seobject parm0 = seGetObject(se,SE_ARGS,SE_INDEX(0));
    seconstcharptr str = seGetString(se,parm0,SE_MEM("text"),NULL);

With Version 5, you WILL get an object as requested, and you WILL get a string as requested. If there is any error along the way then exceptions will be prepared for when you return to the script--your code can test if there was an error, but that is not required.

Version 5 Productivity Tools

Version 5 includes these new and improved productivity tools (which may be previewed in these screen shots). All of these tools run on Win32 platforms, and so are immediately useful for those systems for which most development takes place on a Win32 machine (Win32, WinCE, PalmOS, Blackberry, VxWorks, Java). Visual Studio users will become more productive through the direct integration of these productivity tools with the Visual Studio environment. For other systems, such as Linux, Unix, and Macintosh, these tools are useful for getting started or when using a Win32 platform for co-development.


The toolbox is a visual home base for accessing documentation, samples, support, and the other Version 5 Productivity tools.

Selib Assistant

Selib Assistant makes it very easy to integrate the ISDK into your application. This tool allows for visual manipulation of the very many (hundreds of) compile-time options, and then assists in building and adding these libraries to your development project.


The Workshop is a powerful IDE for scripters. It is fully scriptable, fully customizable, and integrates directly with the compiler, debugger, and help system. (Note: some customization and integration parts of Workshop are not complete).


A state-of-the art debugger, customizable for your environment, for local and remote script debugging. (Note: the the Version 5 debugger is not shipping yet--4.00 debugger is included with this package.)

All-new manual

The manual has been completely rewritten to introduce the API and tools in a sensible order, starting with step-by-step instructions for integration. The descriptions are more helpful and complete. (This manual, and frequent updates to the manual, is available online)

Out-of-box experience

The new API, Productivity Tools, manual, and even new Installer make for an out-of-box experience that will help any user get immediately into the nuts and bolts of understanding and using ScriptEase.

When should I switch to Version 5?

Version 5 is much improved over 4.x, and Version 5 is faster, smaller, and so on; but you may not want to switch over right away. The Version 5 API is quite different from 4.x, and so moving to Version 5 is not just a matter of switching in a new engine.

We recommend waiting until there is a break in your own product-release cycle, so you will have the comfort of a couple of weeks of time to change code and the extra time to go through your own QA phase. Switching to Version 5 will also be a good time to consider your scripting implementation and see if there are some new capabilities or performance enhancements that your product can take advantage of.

Also, Version 5 is not yet available on as many platforms as is version 4.x, and we don't have it compiling and testing in as many configurations. Finishing tests and releases with these additional compilers, operating systems, and platforms will take time.

Finally, although we have tested this engine with a larger suite than was used with any previous release, it is version 5.00a. Not all of the components are complete, there are still NYIs in the manual, and as we finish ports to various platforms we are sure to find small adjustments that must be made. Those changes will be reported in the errata pages and on this newsletter, along with the inevitable announcement of 5.00b.

If you have any questions about when or if your should switch to Version V (we will continue to support 4.x), then contact us.

How do I get SE:ISDK Version 5?

Evaluation versions for a few systems are now available on the ISDK download page; more versions will be available shortly. For licensed releases contact Tech Support

Have a question about how to use ScriptEase:ISDK? Let Dr. Scripter know at


   ISDK/C 4.30e


   ISDK/C 4.40d


   ISDK/Java 4.30e

ScriptEase: ISDK is a product of Nombas, Inc. Visit us at ../index.htm