Nombas > SE:ISDK DevSpace > Tips > Getting Started The Windows Way


Getting Started The Windows Way
Using ScriptEase ISDK on the Windows Platform

Step 1 - Understanding what you have received

The package you received consists of 3 basic parts. They are the various ScriptEase:ISDK Interpreter Engines, the ScriptEase Standard Function Library source code, and miscellaneous source files required to support the interpreter engine. ScriptEase:ISDK Interpreter Engines are the static and dynamic linked libraries in the libs directory. The ScriptEase:ISDK Interpreter Engine contains the complete interpreter (i.e. parser, interpreter, operator and flow-control commands), but does not include any function libraries. You will find one or more interpreter engines in your installation tree. All of the engines interpret identically, the different versions are for different compilers and operating systems. You are ready to begin the integration process. Step 2 gets you started.

Step 2 - Choose your user interface

Identify where within your application you want scripts to be run. The possibilities are endless, so use your imagination. Some options include; pull down menus, a command prompt, from within the application (as the logic for a game character for instance), from push buttons, or remotely over the Internet or your intranet. Deciding now, how and where scripts will be invoked will help you decide where to add initialization and calling code in the following steps.

Step 3 - Adding the Interpreter engine to your application

This is where you will add the ScriptEase Interpreter Engine library file to your application. The exact steps will vary with the compiler you are using. Basically you need to decide which of the interpreter engines are best suited to your application and add the corresponding library file to your IDE project or makefile. Your compiler choice and whether or not your target operating system supports dlls will probably dictate your library file choice. For instance use the library file, sew32l.lib (located in the LIBS\WIN32\LIB\MSVC40 directory) if you are using Visual C++ on the Windows '95 platform and want to use a static library. Refer to one of the several sample applications we provide as a guide. The compiled ScriptEase libraries contain most of the core ScriptEase interpreter and you will need to set up your project or makefile to link with a ScriptEase library. There are also several directories of headers you need to make available to the compiler. The include directories are: \seisdk\inccmm;\seisdk\inclib;\seisdk\srcmisc;\seisdk\srcapp; (These files are provided as source code for the rare occasion when someone needs to produce different behavior, by modifying the source. In most cases, you will not need to modify these files.) You will need to provide a cmmopt.h file in your project directory. The cmmopt.h file is designed to allow you to configure the SE:ISDK to fit the particulars of your platform and specify the options you choose to use. The cmmopt.h is designed to be the fundamental file for specifying which operating system is being targeted, which other include files will be required, and which elements of the standard library will be included. In most cases it will be sufficient to copy a cmmopt.h from one of the sample applications that closely resembles your application. Refer to the manual for details on the various options that can be specified in a cmmopt.h Always define CMMTOOLKIT_APP to be true. The sample applications that shipped with the ScriptEase:ISDK specify this #define on the compiler's command line. Most compilers use the format: /DCMMTOOLKIT_APP. There are 2 more defines that are required for successful compilation. These depend on the operating system targeted and your choice of interpreter engine. The first define takes the form __CMM_XXXXX__ where XXXXX is the platform you are targeting. Refer to chapter 1 of the manual for a list of these defines. The second define will be either __CMM_LIB__ if you choose to use the static library version of the interpreter engine or _CMM_DLLLOAD__ if you choose the dll version. If you can compile and link your application you're ready to move on to step 4.

Step 4 - Adding startup and cleanup code to your application

In this step, you add the code to your application to initialize the ScriptEase engine. The ScriptEase:ISDK manual has full documentation on doing this. Also reference the ScriptEase:ISDK Simple Samples as a guide. Simple0 is the best example for this step. It is about as minimal as the integration can be. Look for calls to CmmInitializeEngine, CmmInitializeExternalLink, CmmTerminateExternalLink and CmmTerminateEngine. These are the minimum calls required to integrate the ScriptEase:ISDK.To be sure the interpreter has been integrated correctly, add a call to interpret a test script. The script can be simply "a=1" as in:

CmmInterpret( cmmcontext, NULL,"a=1;", NULL, CmmAllNew,CMM_INTERPRET_CALL_MAIN, NULL, &ReturnCode);

Just cut-and-paste this function between where you call CmmInitializeExternalLink and CmmTerminateExternalLink. If you can compile, link and run this test code, then the interpreter is properly included in your application and functioning correctly. You can now move to step 5.After completeing this "getting started" chapter, you will want to return to this step to examine the various options (i.e. polling, error-handling and file searching) available in the CmmInitializedExternalLink and CmmInterpret functions.

Step 5 - Adding the ScriptEase Standard Function Library

Decide what portions of the ScriptEase Standard Function Library (printf, gets, fopen,
strcat, ...) you want to have available in your scripts. This tends to be a choice between all of the available functions or none of the functions. The library functions should not be confused with the basic ScriptEase operators. For, while, if, else, include, and all the sic simple0 sample by including the entire ScriptEase Standard Function Library. Notice that this sample uses the function InitializeInternalLibraries to simplify adding the large number of functions that the ScriptEase Standard Function Library includes. You will most likely want to provide you own custom functions whether or not you choose to use the ScriptEase Standard Function Library. This is covered in step 5.

Step 6 - Customizing the functionality to the ScriptEase Interpreter

This is where you are customizing the ScriptEase:ISDK to meet your needs. A financial application vendor might add functions to model data based on an array of input values, a game developer might make functions available to move game elements or make logical decisions, and a scientific application developer might make functions available to test the state of an instrument. You need to provide these wrapper routines for the functions you intend to make ava ilable from ScriptEase. Wrapper functions provide the transition between the C/C++ data in your application, and the data available to scripts. Nombas also supplies the ScriptEase Standard Function Library in source code. You are free to use this source code in your application or use it as a guide to writing your own wrapper functions. There is extensive documentation in the ScriptEase:ISDK manual for writing your own wrapper functions. Now to get the interpreter to recognize all of your new functions, see step 6.

Step 7 - Making your new functions available to the library

Now that you've coded your new wrapper functions, you need to make them available to the ScriptEase Interpreter. To do this make a call to CmmAddLibrary after CmmInitializeExtenalLink and before CmmInterpret. Refer to the Simple0 sample for an example of a CmmFunctionTable, and CmmAddLibrary call. The ScriptEase:ISDK manual covers this step in great detail as well.

Step 8 - Testing your new functions

Test your implementation by providing various valid scripts to interpret launch methos you selected in step 2. You will then want to test invalid scripts and your your error handling methods (See CmmInitia;izeExternalLink in step 3).



Home | Scripting | Products | Purchase | Download | Support | Company

Copyright ©2001, Nombas, Inc. All Rights Reserved.
Questions? Visit