The seContextParams Structure
The seContextParams structure contains a number of members which you must initialize. Most of them can be NULL to indicate no interest in that member. However, the sePrintErrorFunc member is a required member. Each member is listed in the order it appears in the structure along with a description of it. For members that are callback functions, the function’s prototype is given. The member of the seContextParams structure must be filled in with a pointer to a function that matches that prototype.
For many of these functions, you can find a sample implementation in the src\app directory of the ScriptEase distribution which you may use or modify.
SE_CALLBACK( void )
sePrintErrorFunc(secontext context, seconstcharptr text);
This function is called by the core to print an error to the user. This happens when a script generates an error that is not trapped by a try/catch handler. The error needs to be displayed to the user. This is the function that is called by ScriptEase to do so. This parameter is not optional, you must include an sePrintErrorFunc in your parameters.
SE_CALLBACK( void )
seAtErrorFunc(secontext context, struct seAtErrorInfo *info);
This optional callback is invoked whenever a script generates an error, at the point of error. This will occur for any error, even if the error is trapped via a try/catch handler. Note that some scripts will throw errors as a valid part of their program such as to indicate an error return from a function which will be trapped higher up in the script. This is why normally you do not care about an error until it comes back to you via the sePrintErrorFunc, indicating it never is trapped. Getting an immediate notification is primarily useful in implementing a debugger for which the user may want to stop anytime an error is generated even if it will be handled, in order to step through the handling code.
The seAtErrorFunc is passed an informational structure about the error. Here is the definition:
struct seAtErrorStruct
{
sebool trapped;
};
Currently, the structure has only a single member. The boolean trapped is TRUE if the error will be trapped and FALSE if the sePrintErrorFunc will be called on it.
The actual value of the error is set up in the SE_RETURN object which is described fully in "SE_RETURN EXPLAINED". For an error, the value is an Error object as described by the ECMAScript specification. Since working with variables and return values is not described until later chapters, you should revisit this description once you have read those chapters.
SE_CALLBACK( void )
seContinueFunc(secontext se);
This optional function is called by the ScriptEase interpreter after every statement while evaluating scripts. It is useful to perform periodic work, such as checking Windows messages in a Windows ScriptEase application. It is also useful in implementing a debugger to regain control after each statement is executed.
When evaluating scripts using seEval (described in "Using seEval"), you can pass the SE_INFREQUENT_CONT flag to have the continue function called much less frequently than once per statement. If all you need to do is an occasional Windows Message processing, calling this function after every statement wastes a lot of processing which is when this flag is most useful.
You use the standard ScriptEase wrapper return rules to control execution using this function. You can return an error in the normal way which will abort script execution but can be trapped like any other error. Alternately, you can use set the object,member pair SE_RETURN,SE_EXIT to TRUE in order to force the program to abort completely. Returning a non error value does nothing, it is ignored. Either you generate an error in order to abort script execution, or you return nothing and the script continues as normal.
SE_CALLBACK( sebool )
seFindFileFunc(secontext se, seconstcharptr fileName,
secharptr fileResults,
sememcount fileResultSize,
sebool lookForExtlib);
This optional function is used by ScriptEase when looking for source files. The filenames being looked for are the filenames passed to the #include and #link directives. The parameter lookForExtlib tells you which kind if being looked for: TRUE for a #link extlib, FALSE for a #include include file.
If you do not implement this function, then files are looked for directly, meaning that the filename given must appear exactly as specified in the current directory. By implementing this function, you can handle looking for these files with various extensions in various directories. You are passed fileName, the file to be looked for. This is the text that appears in the directive exactly as the user entered it. You fill in the fileResults buffer (the parameter fileResultSize tells you how big the buffer is) with the translated filename and return TRUE to indicate the file is found. If you return FALSE, you specify the file as not found. See the seGetSourceFunc below for more file-related behavior.
SE_CALLBACK( sebool )
seGetSourceFunc(secontext se, struct seSourceInfo *info,
uint mode);
This optional callback is used to read script files. If you do not provide the callback, files are read using the normal C I/O functions; fopen, fgets, fclose. By defining this function and the seFindFileFunc above, you can completely virtualize your files. Although you can handle the virtualizing of files in this function alone, error reporting is based on the filename returned from seFindFileFunc so implementing it is recommended for the user's ease. In addition, you will need to implement seFindFileFunc to locate extlibs, which once located are loaded by a system call.
The mode parameter tells you what the call is intended to do. It can be one of these values:
seSourceOpen open a new file
seSourceGetLine get the next line from the file
seSourceClose close the file
The info parameter points to a structure that you fill in accomplish these calls. Note that each file will be given its own seSourceInfo structure to work with. In each case, the seSourceOpen routine is called. Returning FALSE results in an 'unable to open file' error in the script. Next the seSourceGetLine is called repeatedly to get the individual lines of the source until you return FALSE to indicate no more lines. Finally, seSourceClose is called to close down the file.
The seSourceInfo structure is as follows:
struct seSourceInfo
{
secharptr lineText;
const seconstcharptr filename;
uint lineNum;
void * userdata;
};
filename is preset by ScriptEase and should not be modified. It is the result of the seFindFileFunc. lineText is where the application should return the successive lines of the file including the newline character on each line. It is a pointer to a buffer that the application will allocate and presumably free in the seSourceClose processing. lineNum is the line number of the file which the application should update as it returns lines. Finally, the userdata is where the application keeps whatever information it needs to process the file. A simple implementation would use a FILE * for userdata, but a more complex one might need to point to a structure keeping necessary data.
SE_CALLBACK( sebool )
seGetResourceFunc(secontext se, sint id,
secharptr buf,
sememcount buflen);
ScriptEase uses a number of text string resources, which it has internal string values for. You can use this optional callback function to override those values. This is useful for internalization, to translate the text strings into whatever language is appropriate. The id parameter indicates which resource ScriptEase is trying to access. You fill in the buf with the text you'd like to give the resource. The buflen tells you how much space buf points to.
The list of identifier numbers and the English strings corresponding to them can be found in src\core\rsrccore.h and src\lib\common\rsrclib.h.
SE_CALLBACK( void )
sePrepareContextFunc(secontext se);
After seCreateContext has finished preparing a new context, it invokes this function. You can do any final setup on your context here, such as adding your application specific wrapper tables (see "Wrapper functions"). If you do the final preparation here instead of in your code after calling seCreateContext then all calls to seCreateContext will do that same preparation. This is useful if you are using utility libraries that create new contexts with seCreateContext. It ensures those contexts are properly set up for your application. Nombas has no utility routines that use seCreateContext. However, some may be created in the future.
uword32 seOptions;
The options parameter is a flags parameter, you can use any combination of the following |'ed together:
SE_DEFAULT
Default behavior
SE_OPT_REQUIREVAR
All variables must be declared using the var keyword. If this flag is not used, the normal JavaScript behavior is in effect. When you write to an undeclared variable, the variable is automatically created as a global variable. Reading from an undeclared variable always results in an error.
SE_OPT_DEFAULTLOCAL
Variables used without declaring them with the var keyword are declared automatically as global variables as described above under SE_OPT_REQUIREVAR. This flag makes them declared as local variables instead. JavaScript standard behavior is to create the variables as global variables.
SE_OPT_WARNBADMATH
If any math operation involves NaN, an error will be flagged. Normally, JavaScript allows NaN to be used in an operation and defines specific results.
SE_OPT_EXTRAPARAMS
Wrapper functions indicate the maximum number of parameters they can take, and extras will cause an error. This flag causes all library functions to take any number of parameters, ignoring excess parameters. It is normally useful to leave out this option, as extra parameters usually signal an incorrect usage of these functions.
SE_OPT_TOBOOLOBJECTS
JavaScript states that any object converted to a Boolean results in TRUE. If this flag is on, objects are first converted to a primitive then to a boolean. For instance, without this flag the object new Boolean(False) or new Number(0) will convert to TRUE, but with the flag they become FALSE.
SE_OPT_DEBUGGER
A debugger is in use, so ignore SE_INFREQUENT_CONT for all seEval calls.
SE_OPT_NO_LIBRARIES
Creates the context but does not initialize the libraries into it. Useful when sharing libraries via the global _prototype.
SE_OPT_REQ_SEMICOLON
Disables the EcmaScript rules of automatic semicolon insertion, as described in section 7.9 of the EcmaScript Language Specification. With this flag set errors will be generated on any statement that is not terminated with a semicolon.
Here is the example from above extended to create a single context:
SE_CALLBACK( void )
my_error_printer(secontext se,seconstcharptr text)
{
printf_sechar(UNISTR("Error encountered: %s\n"),text);
}
void
main(int argc,char **argv)
{
secontext se;
struct seContextParams params;
seInitialize();
memset(params,0,sizeof(params));
/* The print error function is the one required function.
*/
params.sePrintErrorFunc = my_error_printer;
se = seCreateContext(¶ms,MY_JSE_USER_KEY);
/* your application, including scripting using 'se'
* as the scripting context.
*/
seDestroyContext(se);
seTerminate();
}