GoAhead Embedded JavaScript

Specification


 

 

This document defines the Specification for the GoAhead embedded JavaScript module.

 

GoAhead Confidential

Revision 0.1

Printed: April 1, 1999

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

GoAhead Software, Inc

10900 NE 8th Street, #750

Bellevue, WA 98004

425-453-1900

www.goahead.com

info@goahead.com

 

 

Ó Copyright 1999, GoAhead Software Inc. All rights reserved

 

Technical and product information in this document is subject to change without notice.

 

 

 

 

 

Table OF Contents

 

  1. 1 Introduction *

    1.1 Related documents *

    2 Naming Conventions and Definitions *

    3 Specification *

    3.1 Overview *

    3.2 Platform *

    3.3 Functionality *

    3.3.1 Syntax *

    3.3.2 Variables *

    3.3.3 Data Types *

    3.3.4 Expressions and Operators *

    3.3.5 Statements *

    3.3.6 Regular Expressions *

    3.3.7 JavaScript in HTML *

    3.3.8 Client-side Object Hierarchy *

    3.3.9 Windows and Frames *

    3.3.10 Forms *

    3.3.11 Events *

    3.3.12 Security Restrictions *

    3.3.13 Global Properties *

    3.3.14 Global Functions *

    3.3.15 Objects *

    4 C API *

    4.1 Current C API *

    4.1.1 Instantiate API *

    4.1.2 Extended Capabilities API *

  2. Introduction

    This document is the specification for GoAhead's embedded JavaScript.

    1. Related documents

    GoAhead WebServer 1.0 Requirements

    GoAhead WebServer 1.0 Design

  3. Naming Conventions and Definitions
  4. Specification
    1. Overview
    2. Embedded JavaScript is designed to implement a subset of JavaScript 1.1. The intent of implementing a subset is to control the code size of the script interpreter. The subset will be the functions required by other GoAhead products.

    3. Platform

The embedded JavaScript product is a library for the following platforms / compilers:

    1. Functionality
      1. Syntax

JavaScript 1.1 compliant except

      1. Variables
      2. Each embedded JavaScript procedure provides two variable spaces: global and local. Local Variables are declared using the var key word. From this point on in the current script any reference to the declared variable will access the local instance. An identical global instance will be unmodified. If the first assignment of a variable is without the keyword var, embedded JavaScript uses global space.

        {

        x = 1; // declares a global variable and initiates the value to 1

        }

        {

        var x = 5; // declares a local variable and initiates the value to 5.

        // the global variable x remains 1.

        }

        {

        x = x + 1; // access the global variable and adds 1 to it.

        // the value is now 2.

        }

      3. Data Types

JavaScript 1.1 compliant except

      1. Expressions and Operators
      2.  

        precedence

        associativity

        operator

        operation

         

        15

         

        .

        access an object property

             

        []

        access an array element

        yes

           

        ()

        invoke a function

        yes

        14

         

        ++

        unary pre- or post-increment

        yes

           

        --

        unary pre- or post-increment

        yes

           

        -

        unary minus (negation)

             

        ~

        numeric bitwise complement

        yes

           

        !

        unary boolean complement

             

        delete

        undefine a property

             

        new

        create a new object

             

        typeof

        return type of operand

             

        void

        return undefined value

        yes

        13

         

        *,/,%

        multiplication, division, modulo

        yes

        12

         

        +,-

        addition, subtraction

        yes

           

        +

        string concatenation

         

        11

         

        <<

        integer shift left

             

        >>

        shift right, sign extension

             

        >>>

        shift right, zero extension

        yes

        10

         

        <,<=

        less than, less than or equal

        yes

           

        >,>=

        greater than, greater than or eq

        yes

        9

         

        ==,!=

        test for equality or inequality

             

        ===,!==

        test for identity or non-identity

         

        8

         

        &

        integer bitwise AND

         

        7

         

        ^

        integer bitwise XOR

         

        6

         

        |

        integer bitwise OR

        yes

        5

         

        &&

        logical AND

        yes

        4

         

        ||

        logical OR

         

        3

         

        ?:

        conditional

        yes

        2

         

        =

        assignment

             

        *=,+=,-=,…

        assignment with operation

         

        1

         

        ,

        multiple evaluation

         

      3. Statements
      4.    

        yes

        expression

        yes

        compound

        yes

        empty

         

        labeled

         

        break

         

        case

         

        continue

         

        default

         

        do/while

         

        do

         

        export

        yes

        for

         

        for/in

         

        function

        yes

        if/else

         

        import

        yes

        return

         

        switch

        yes

        var

         

        while

         

        with

         

         

      5. Regular Expressions
      6. Not supported

      7. JavaScript in HTML
      8. Outside the scope of this specification. Browser specific.

      9. Client-side Object Hierarchy
      10. No objects supported.

      11. Windows and Frames
      12. Not supported

      13. Forms
      14. Not supported

      15. Events
      16. Not supported

      17. Security Restrictions
      18. Access to resources is limited to Global Function

      19. Global Properties
      20. Non supported

      21. Global Functions
      22. Embedded JavaScript comes with several Global Functions. In addition to the standard functions, other Global Functions can be added to an engine by using ejSetGlobalFunction(). See the C API for more detail. All parameters passed in a Global Function are quoted strings.

        1. dbRead
        2. Synopsis

          Performs a read of the EMF database.

          Prototype

          dbRead(table, column);

          dbRead(table, column, row);

          dbRead(primary, table, column, row);

          dbRead(primary, table, column, row, period);

           

          Parameters

          primary

          Identifies the desired database. Primary is the default value.

          table

          Identifies the desired table.

          column

          Identifies the desired column.

          row

          Identifies the desired row. Row 0 is the default value.

          period

          Defines acceptable time lapse since last update. 0 is the default value.

          Description

          Performs a database read from the EMF database. The function is overloaded to provide 4 derivatives based on the parameters.

          Return Value

          Return value of requested entry.

          Example

          dbRead("detectors","name");

          See Also

           

           

        3. dbWrite
        4. Synopsis

          Performs a write into the EMF database.

          Prototype

          dbWrite(table, column, data);

          dbWrite(table, column, row, data);

          dbWrite(primary, table, column, row, data);

          dbWrite(primary, table, column, row, period, data);

           

          Parameters

          primary

          Identifies the desired database. Primary is the default value.

          table

          Identifies the desired table.

          column

          Identifies the desired column.

          row

          Identifies the desired row. 0 is the default value.

          period

           

          data

          String data to be placed in entry.

          Description

          Performs a database write to the EMF database. The function is overloaded to provide 4 derivatives based on the parameters.

          Return Value

          none.

          Example

          dbWrite("detectors","name","rule","I=1;");

          See Also

           

        5. dbReadKeyed
        6. Synopsis

           

          Prototype

          dbReadKeyed(table, column, keyValue);

          dbReadKeyed(primary, table, column, keyValue);

          dbReadKeyed(primary, table, column, keyValue, period);

           

          Parameters

          primary

          Identifies the desired database. Primary is the default value.

          table

          Identifies the desired table.

          column

          Identifies the desired column.

          period

          Defines acceptable time lapse since last update. 0 is the default value.

          Description

          Performs a database read from the EMF database. The function is overloaded to provide 3 derivatives based on the parameters.

          Return Value

          -1 if a failure occurs.

          Example

           

          See Also

           

           

        7. dbGetTableNrow
        8. Synopsis

          Returns the number of rows in the table.

          Prototype

          dbGetTableNrow(table);

          dbGetTableNrow(primary, table);

           

          Parameters

          primary

          Identifies the desired database. Primary is the default value.

          table

          Identifies the desired table.

          Description

          Returns the number of rows in the desired table. The function is overloaded to provide 2 derivatives based on the parameters.

          Return Value

          Returns the number of rows in the table.

          Example

          dbGetTableNrow("detectors");

          See Also

           

           

        9. trace

        Synopsis

        Inserts a text string into the trace log.

        Prototype

        trace(string);

        Parameters

        string

        string to insert into trace log.

        Description

        Inserts a text string into the trace log.

        Return Value

        none.

        Example

        trace("in loop");

        See Also

         

         

      23. Objects

Not supported

 

  1. C API
    1. Current C API
This section defines the current API for embedded JavaScript. This is the API available to any C application that wants to use the embedded JavaScript interpreter. The API available for embedded JavaScript is defined in the previous section. The API is organized in three groups.
      1. Instantiate API

These functions must be used to instantiate and use an embedded JavaScript object. Essentially there are three steps:

    1. ejOpenEngine() to instantiate the object.
    2. ejEval() to interpret a script.
    3. ejCloseEngine() to delete and free the resources of the object.

 

        1. ejCloseEngine
        2. Synopsis

          Close an embedded JavaScript interpreter session.

          Prototype

          #include "ej.h"

           

          void ejClose(int eid);

          Parameters

          eid

          embedded JavaScript interpreter handle

          Description

          ejClose closes an embedded JavaScript interpreter that has been opened via ejOpen.

          Return Value

          None.

          Example

          ejCloseEngine(eid);

          See Also

          JavaScript, Active Server Pages, ejOpenEngine, ejEval

        3. ejEval
        4. Synopsis

          Evaluates an embedded JavaScript function

          Prototype

          #include "ej.h"

           

          int ejEval(int eid, char_t *script, char_t **errorMessage);

          Parameters

          eid

          embedded JavaScript interpreter handle

          script

          embedded JavaScript to evaluate

          errorMessage

          Error message

          Description

          The ejEval procedure evaluates an embedded JavaScript function. If the script fails, a text message describing the error is returned in errorMessage. This message is dynamically allocated and must be freed using bfree.

          Return Value

          Returns 0 if successful. Returns -1 on errors.

          Example

          char_t *emsg;

          ejEval(eid, "write('Hello World');", &emsg);

          See Also

          JavaScript, Active Server Pages, ejOpenEngine, ejGetVarEngine

        5. ejOpenEngine

Synopsis

Open an embedded JavaScript interpreter session.

Prototype

#include "ej.h"

 

int ejOpenEngine(sym_fd_t variables, sym_fd_t functions);

Parameters

variables

Symbol table for variables

functions

Symbol table for functions

Description

To use embedded JavaScript, you must first open an interpreter session with ejOpenEngine. Embedded JavaScript interpreters usually have their own variable and global function name space. To share variable or function name space, pass a symbol table into ejOpen in the variable or function parameters. If either of these parameters are set to NULL, the symbol table will be created automatically.

Use ejCloseEngine to close the interpreter when finished.

Return Value

Handle for the embedded JavaScript interpreter. –1 indicates an error and the enginer was not opened.

Example

if (ejOpenEngine(NULL, NULL)< 0) {

/* Cant open interpreter */

return -1;

}

See Also

JavaScript, Active Server Pages, ejCloseEngine, ejEval

      1. Extended Capabilities API

Embedded JavaScript provides some functionality that is unique to embedded JavaScript and not support in the same way in JavaScript 1.1.

 

        1. ejGetVar
        2. Synopsis

          Get the value of an embedded JavaScript variable

          Prototype

          #include "ej.h"

           

          int ejGetVar(int eid, char_t *variable, char_t **value);

          Parameters

          eid

          embedded JavaScript interpreter handle

          variable

          Name of embedded JavaScript variable

          value

          pointer to variable that value will be placed

          Description

          The ejGetVar procedure returns the current value of the embedded JavaScript variable to the location pointed by char_t **value.

          Return Value

          Returns 0 if successful, else returns –1 to indicate an error.

          Example

          ejGetVar(eid, "y",&value);

          See Also

          JavaScript, Active Server Pages, ejSetVar, ejEval

           

        3. ejSetGlobalFunction
        4. Synopsis

          Define an embedded JavaScript global function.

          Prototype

          #include "ej.h"

           

          int ejSetGlobalFunction(int eid, char_t *name,

          int (*fn)(int eid, void *handle, int argc, char_t **argv));

          Parameters

          eid

          embedded JavaScript interpreter handle

          name

          Name of the function to define

          fn

          C function to invoke (see section4.3.2.4)

          Description

          The ejSetGlobalFunction procedure defines an embedded JavaScript function. When the function named by name is called, the function defined by fn is called.

          When fn is called, the embedded JavaScript parameters are passed in via argc and argv as a list of pointers to arguments. Use ejArgs to parse the arguments array.

          Use ejGetGlobalFunction() to determine if the function already exist.

          Return Value

          Returns 0 if successful. Returns -1 on errors.

          Example

          char_t *emsg;

           

          int fn(int eid, void *handle, int argc, char_t **argv);

          if ( ejGetGlobalFunction(eid, "myfunc", myfunc) == NULL ) {

          ejSetGlobalFunction(int eid, "myfunc", myfunc);

          }

          See Also

          JavaScript, Active Server Pages, ejOpenEngine, ejSetVar

        5. ejGetGlobalFunction
        6. Synopsis

          Returns .

          Prototype

          #include "ej.h"

           

          int ejSetGlobalFunction(int eid, char_t *name,

          int (*fn)(int eid, void *handle, int argc, char_t **argv));

          Parameters

          eid

          Embedded JavaScript interpreter handle

          name

          function name in embedded JavaScript space

          fn

          C function pointer to C implementation

          Description

          Maps a C function to an embedded JavaScript Global Function. The C function fn will be executed when the embedded JavaScript Global Function name is called in a script. ejGetGlobalFunction() should be used before ejSetGlobalFunction() to test if the function already exist.

          Return Value

          -1 if a failure occurs.

          Example

          ejSetGlobalFunction(eid, T("dbReadKeyed"), ejEmfDbReadKeyed);

          See Also

          ejGetGlobalFunction

        7. ejSetGlobalVar
        8. Synopsis

          Set the value of an embedded JavaScript variable

          Prototype

          #include "ej.h"

           

          void ejSetGlobalVar(int eid, char_t *variable, char_t *value);

          Parameters

          eid

          embedded JavaScript interpreter handle

          variable

          Name of the embedded JavaScript variable

          value

          Value to set

          Description

          The ejSetGlobalVar procedure defines the current value of the embedded JavaScript variable. All embedded JavaScript variables are stored as strings.

          Return Value

          None

          Example

          ejSetGlobalVar(eid, "name", "John Smith");

          See Also

          JavaScript, Active Server Pages, ejGetVar, ejEval

           

        9. Declaring C Function For Use In Script

ejSetGlobalFunction provides a mechanism such that C functions can be called from the script. The C function must follow the format of

int (*fn)( int eid, void *handle, int argc, char_t **argv )

When embedded JavaScript encounters a function call fn, it will make a call to the C function with the parameters identified above.

Parameters

eid

embedded JavaScript interpreter handle

handle

 

argc

number of arguments in argv

argv

array of arguments used by function