| |
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).
|
