ActiveX Scripting Engines

ActiveX Scripting Engines


To implement an ActiveX™ Scripting engine, create an OLE COM object that supports the following interfaces.
Interface Description
IActiveScript Provides the basic scripting ability. Implementation of this interface is required.
IActiveScriptParse Provides the ability to add script text, evaluate expressions, and so on. Implementation of this interface is optional; however, if it is not implemented, the script engine must implement one of the IPersist* interfaces in order to load a script.
IPersist* Provides persistence support. Implementation of at least one of the following interfaces is required if IActiveScriptParse is not implemented.
Interface Description
IPersistStorage Provides support for the DATA={url} attribute in the OBJECT tag.
IPersistStreamInit Provides support for the same as IPersistStorage as well as the DATA="string-encoded byte stream" attribute in the OBJECT tag.
IPersistPropertyBag Provides support for the PARAM= attribute in the OBJECT tag.

Note It is possible that the scripting engine will never be called upon to save or restore a script state through IPersist*. Instead, IActiveScriptParse is used by calling IActiveScriptParse::InitNew to create a blank script, then scriptlets are added and connected to events with IActiveScriptParse::AddScriptlet and general code is added with IActiveScriptParse::ParseScriptText. Nonetheless, a scripting engine should fully implement at least one IPersist* interface (preferably IPersistStreamInit), because other host applications may try to make use of them.

arrowg.gifRegistry Standard

arrowg.gifScript Engine States

arrowg.gifScripting Engine Threading

arrowg.gifScripting Engine Reference

Registry Standard

An ActiveX Scripting engine can identify itself using component categories. ActiveX Scripting currently defines two component categories.
Category Description
CATID_ActiveScript Indicates that the class identifiers (CLSIDs) are ActiveX Scripting engines that support, at a minimum, the IActiveScript interface and a persistence mechanism (the IPersistStorage, IPersistStreamInit, or IPersistPropertyBag interface).
CATID_ActiveScriptParse Indicates that the CLSIDs are ActiveX Scripting engines that support, at a minimum, the IActiveScript and IActiveScriptParse interfaces.

Although IActiveScriptParse is not a true persistence mechanism, it does support the IActiveScriptParse::InitNew method that is functionally equivalent to IPersist*::InitNew.

Script Engine States

At any given time, an ActiveX Scripting engine can be in one of several states.
State Description
uninitialized The script has not been initialized or loaded using an IPersist* interface, or does not have an IActiveScriptSite interface set. The scripting engine is generally not usable from this state until the script is loaded.
initialized The script has been initialized with an IPersist* interface and has an IActiveScriptSite interface set, but is not connected to host objects and sinking events. Note that this state simply means that the IPersist*::Load, IPersist*::InitNew, or IActiveScriptParse::InitNew method has been completed, and that the IActiveScript::SetScriptSite method has been called. The engine cannot run code in this mode. The engine queues code that the host passes to it through the IActiveScriptParse::ParseScriptText method, and executes the code after transitioning to the started state.

Because languages can vary widely in semantics, scripting engines are not required to support this state transition. Engines that support the IActiveScript::Clone method must, however, support this state transition. Hosts must prepare for this transition and take the appropriate action: release the current scripting engine, create a new scripting engine, and call IPersist*::Load, IPersist*::InitNew, or IActiveScriptParse::InitNew (and possibly also call IActiveScriptParse::ParseScriptText). Use of this transition should be considered an optimization of the above steps. Note that any information the scripting engine has obtained about the names of Named Items and the type information describing Named Items remains valid.

Because languages vary widely, defining the exact semantics of this transition is difficult. At a minimum, the scripting engine must disconnect from all events, and release all of the SCRIPTINFO_IUNKNOWN pointers obtained by calling the IActiveScriptSite::GetItemInfo method. The engine must re-obtain these pointers after the script is run again. The scripting engine should also reset the script back to an initial state that is appropriate for the language. VBScript, for example, resets all variables and retains any code added dynamically by calling IActiveScriptParse::ParseScriptText with the SCRIPTTEXT_ISPERSISTENT flag set. Other languages may need to retain current values (such as Lisp because there is no code/data separation) or reset to a well-known state (this includes languages with statically initialized variables).

Note that the transition to the started state should have the same semantics (that is, it should leave the scripting engine in the same state) as calling IPersist*::Save to save the scripting engine, and then calling IPersist*::Load to load a new scripting engine; these actions should have the same semantics as IActiveScript::Clone. Scripting engines that do not yet support IActiveScript::Clone or IPersist* should carefully consider how the transition to the started state should behave, so that such a transition would not violate the above conditions if IActiveScript::Clone or IPersist* support was later added.

During this transition to the started state, the scripting engine will disconnect from event sinks after the appropriate destructors, and so on, are executed in the script. To avoid having these destructors executed, the host can first move the script into the disconnected state before moving into the started state.

Use IActiveScript::InterruptScriptThread to cancel a running script thread without waiting for current events, and so on, to finish running.

started The transition from the initialized state to the started state causes the engine to execute any code that was queued in the initialized state. The engine can execute code while in the started state, but it is not connected to any events added through the IActiveScript::AddNamedItem method. The engine can execute code by calling the IDispatch interface obtained from the IActiveScript::GetScriptDispatch method, or by calling IActiveScriptParse::ParseScriptText. It is possible that further background initialization (progressive loading) is still ongoing, and that calling the IActiveScript::SetScriptState method with the SCRIPTSTATE_CONNECTED flag set may cause the script to block until initialization is complete.
connected The script is loaded and connected for sinking events from host objects. If this is a transition from the initialized state, the scripting engine should transition through the started state, performing the necessary actions, before entering the connected state and connecting to events.
disconnected The script is loaded and has a run-time state, but is temporarily disconnected from sinking events from host objects. This can be done either logically (ignoring events received) or physically (calling IConnectionPoint::Unadvise on the appropriate connection points). If this is a transition from the initialized state, the scripting engine should transition through the started state, performing the necessary actions, before entering the disconnected state. Event sinks that are in progress are completed before the state changes (use IActiveScript::InterruptScriptThread to cancel a running script thread). This state is distinguished from the initialized state in that the transition to this state does not cause the script to reset, the run-time state of the script is not reset, and a script initialization procedure is not executed.
closed The script has been closed. The scripting engine no longer works and returns errors for most methods.

The following illustration shows the relationships between the various scripting engine states, and shows the methods that cause transitions from one state to another.

The following illustration shows the actions that the scripting engine performs during the various state transitions.

Scripting Engine Threading

Because an ActiveX Scripting engine can be used in many environments, it is important to keep its execution model as flexible as possible. For example, a server-based host may need to preserve a multithreaded design while using ActiveX Scripting in an efficient manner. At the same time, a host that does not use threading, such as a typical application, should not be burdened with threading management. ActiveX Scripting achieves this balance by restricting the ways a free-threaded scripting engine can call back to the host, freeing hosts from this burden.

Scripting engines used on servers are typically implemented as free-threading COM objects. This means that methods on the IActiveScript interface and its associated interfaces can be called from any thread in the process, without marshaling. (Unfortunately, this also means that the scripting engine must be implemented as an in-process server, because OLE does not currently support interprocess marshaling of free-threaded objects.) Synchronization is the responsibility of the scripting engine. For scripting engines that are not internally reentrant, or for language models that are not multithreaded, synchronization could be as simple as serializing access to the scripting engine with a mutex. Of course certain methods, such as IActiveScript::InterruptScriptThread, should not be serialized in this way so that a stuck script can be terminated from another thread.

The fact that IActiveScript is typically free-threaded generally implies that the IActiveScriptSite interface and the host's object model should be free-threaded as well. This would make implementation of the host quite difficult, particularly in the common case where the host is a single-threaded Microsoft Windows®-based application with single-threaded or apartment-model ActiveX Controls in its object model. For this reason, the following constraints are placed on the scripting engine's use of IActiveScriptSite:

Scripting Engine Reference

The following elements are specific to ActiveX Scripting Engines.

Interfaces
IActiveScript
IActiveScriptError
IActiveScriptParse

Enumerations
SCRIPTSTATE
SCRIPTTHREADSTATE

IActiveScript

The IActiveScript interface provides the methods necessary to initialize the scripting engine. The scripting engine must implement the IActiveScript interface.

Methods in Vtable Order
SetScriptSite Informs the scripting engine of the IActiveScriptSite site provided by the host.
GetScriptSite Retrieves the site object associated with the ActiveX Scripting engine.
SetScriptState Places the scripting engine into the specified state.
GetScriptState Retrieves the current state of the scripting engine.
Close Causes the scripting engine to abandon any currently loaded script, lose its state, and release any interface pointers it has to other objects, thus entering a closed state.
AddNamedItem Adds the name of a root-level item to the scripting engine's name space.
AddTypeLib Adds a type library to the name space for the script.
GetScriptDispatch Retrieves the IDispatch interface for the running script.
GetCurrentScriptThreadID Retrieves a scripting-engine-defined identifier for the currently executing thread.
GetScriptThreadID Retrieves a scripting-engine-defined identifier for the thread associated with the given Microsoft Win32® thread.
GetScriptThreadState Retrieves the current state of a script thread.
InterruptScriptThread Interrupts the execution of a running script thread.
Clone Clones the current scripting engine (minus any current execution state), returning a loaded scripting engine that has no site in the current thread.

IActiveScript::AddNamedItem
HRESULT AddNamedItem(
    LPCOLESTR pstrName,  // address of item name
    DWORD dwFlags        // item flags
);

Adds the name of a root-level item to the scripting engine's name space. A root-level item is an object with properties and methods, an event source, or all three.

pstrName
[in] Address of a buffer that contains the name of the item as viewed from the script. The name must be unique and persistable.
dwFlags
[in] Flags associated with an item. Can be a combination of these values:
SCRIPTITEM_CODEONLY Indicates that the named item represents a code-only object, and that the host has no IUnknown to be associated with this code-only object. The host only has a name for this object. In object-oriented languages such as C++, this flag would create a class. Not all languages support this flag.
SCRIPTITEM_GLOBALMEMBERS Indicates that the item is a collection of global properties and methods associated with the script. Normally, a scripting engine would ignore the object name (other than for the purpose of using it as a cookie for the IActiveScriptSite::GetItemInfo method, or for resolving explicit scoping) and expose its members as global variables and methods. This allows the host to extend the library (run-time functions and so on) available to the script. It is left to the scripting engine to deal with name conflicts (for example, when two SCRIPTITEM_GLOBALMEMBERS items have methods of the same name), although an error should not be returned because of this situation.
SCRIPTITEM_ISPERSISTENT Indicates that the item should be saved if the scripting engine is saved. Similarly, setting this flag indicates that a transition back to the initialized state should retain the item's name and type information (the scripting engine must, however, release all pointers to interfaces on the actual object).
SCRIPTITEM_ISSOURCE Indicates that the item sources events that the script can sink. Child objects (properties of the object that are in themselves objects) can also source events to the script. This is not recursive, but it provides a convenient mechanism for the common case, for example, of creating a container and all of its member controls.
SCRIPTITEM_ISVISIBLE Indicates that the item's name is available in the name space of the script, allowing access to the properties, methods, and events of the item. By convention the properties of the item include the item's children; therefore, all child object properties and methods (and their children, recursively) will be accessible.
SCRIPTITEM_NOCODE Indicates that the item is simply a name being added to the script's name space, and should not be treated as an item for which code should be associated. For example, without this flag being set, VBScript will create a separate module for the named item, and C++ might create a separate wrapper class for the named item.
IActiveScript::AddTypeLib
HRESULT AddTypeLib(
    REFGUID guidTypeLib,  // CLSID of type library
    DWORD dwMaj,          // major version number
    DWORD dwMin,          // minor version number
    DWORD dwFlags         // option flags
);

Adds a type library to the name space for the script. This is similar to the #include directive in C/C++. It allows a set of predefined items such as class definitions, typedefs, and named constants to be added to the run-time environment available to the script.

guidTypeLib
[in] CLSID of the type library to add.
dwMaj
[in] Major version number.
dwMin
[in] Minor version number.
dwFlags
[in] Option flags. Can be the following:
SCRIPTTYPELIB_ISCONTROL The type library describes an ActiveX control used by the host.
IActiveScript::Clone
HRESULT Clone(
    IActiveScript **ppscript  // receives pointer to IActiveScript
);

Clones the current scripting engine (minus any current execution state), returning a loaded scripting engine that has no site in the current thread. The properties of this new scripting engine will be identical to the properties the original scripting engine would be in if it were transitioned back to the initialized state.

ppscript
[out] Address of a variable that receives a pointer to the IActiveScript interface of the cloned scripting engine. The host must create a site and call the IActiveScript::SetScriptSite method on the new scripting engine before it will be in the initialized state and, therefore, usable.

The IActiveScript::Clone method is an optimization of IPersist*::Save, CoCreateInstance, and IPersist*::Load, so the state of the new scripting engine should be the same as if the state of the original scripting engine were saved and loaded into a new scripting engine. Named items are duplicated in the cloned scripting engine, but specific object pointers for each item are forgotten and are obtained with the IActiveScriptSite::GetItemInfo method. This allows an identical object model with per-thread entry points (an apartment model) to be used.

This method is used for multithreaded server hosts that can run multiple instances of the same script. The scripting engine may return E_NOTIMPL, in which case the host can achieve the same result by duplicating the persistent state and creating a new instance of the scripting engine with an IPersist* interface.

This method can be called from non-base threads without resulting in a non-base callout to host objects or to the IActiveScriptSite interface.

IActiveScript::Close
HRESULT Close(void);

Causes the scripting engine to abandon any currently loaded script, lose its state, and release any interface pointers it has to other objects, thus entering a closed state. Event sinks, immediately executed script text, and macro invocations that are already in progress are completed before the state changes (use IActiveScript::InterruptScriptThread to cancel a running script thread). This method must be called by the creating host before the interface is released to prevent circular reference problems.

IActiveScript::GetCurrentScriptThreadID
HRESULT GetCurrentScriptThreadID(
    SCRIPTTHREADID *pstidThread  // receives scripting thread identifier
);

Retrieves a scripting-engine-defined identifier for the currently executing thread. The identifier can be used in subsequent calls to script thread execution-control methods such as the IActiveScript::InterruptScriptThread method.

pstidThread
[out] Address of a variable that receives the script thread identifier associated with the current thread. The interpretation of this identifier is left to the scripting engine, but it can be just a copy of the Windows thread identifier. If the Win32 thread terminates, this identifier becomes unassigned and can subsequently be assigned to another thread.

This method can be called from non-base threads without resulting in a non-base callout to host objects or to the IActiveScriptSite interface.

IActiveScript::GetScriptDispatch
HRESULT GetScriptDispatch(
    LPCOLESTR pstrItemName  // address of item name
    IDispatch **ppdisp      // receives IDispatch pointer
);

Retrieves the IDispatch interface for the methods and properties associated with the currently running script.

pstrItemName
[in] Address of a buffer that contains the name of the item for which the caller needs the associated dispatch object. If this parameter is NULL, the dispatch object contains as its members all of the global methods and properties defined by the script. Through the IDispatch interface and the associated ITypeInfo interface, the host can invoke script methods or view and modify script variables.
ppdisp
[out] Address of a variable that receives a pointer to the object associated with the script's global methods and properties. If the scripting engine does not support such an object, NULL is returned.

Because methods and properties can be added by calling the IActiveScriptParse interface, the IDispatch interface returned by this method can dynamically support new methods and properties. Similarly, the IDispatch::GetTypeInfo method should return a new, unique ITypeInfo interface when methods and properties are added. Note, however, that language engines must not change the IDispatch interface in a way that is incompatible with any previous ITypeInfo interface returned. That implies, for example, that DISPIDs will never be reused.

IActiveScript::GetScriptSite
HRESULT GetScriptSite(
    REFIID iid,           // interface identifier
    void **ppvSiteObject  // address of host site interface
);

Retrieves the site object associated with the ActiveX Scripting engine.

iid
[in] Identifier of the requested interface.
ppvSiteObject
[out] Address of the location that receives the interface pointer to the host's site object.
IActiveScript::GetScriptState
HRESULT GetScriptState(
    SCRIPTSTATE *pss  // address of structure for state information
);

Retrieves the current state of the scripting engine. This method can be called from non-base threads without resulting in a non-base callout to host objects or to the IActiveScriptSite interface.

pss
[out] Address of a variable that receives a value defined in the SCRIPTSTATE enumeration. The value indicates the current state of the scripting engine associated with the calling thread.
IActiveScript::GetScriptThreadID
HRESULT GetScriptThreadID(
    DWORD dwWin32ThreadID,       // Win32 thread identifier
    SCRIPTTHREADID *pstidThread  // receives scripting thread identifier
);

Retrieves a scripting-engine-defined identifier for the thread associated with the given Win32 thread.

dwWin32ThreadID
[in] Thread identifier of a running Win32 thread in the current process. Use the GetCurrentScriptThreadID function to retrieve the thread identifier of the currently executing thread.
pstidThread
[out] Address of a variable that receives the script thread identifier associated with the given Win32 thread. The interpretation of this identifier is left to the scripting engine, but it can be just a copy of the Windows thread identifier. Note that if the Win32 thread terminates, this identifier becomes unassigned and may subsequently be assigned to another thread.

The retrieved identifier can be used in subsequent calls to script thread execution control methods such as the IActiveScript::InterruptScriptThread method.

This method can be called from non-base threads without resulting in a non-base callout to host objects or to the IActiveScriptSite interface.

IActiveScript::GetScriptThreadState
HRESULT GetScriptThreadState(
    SCRIPTTHREADID stidThread,    // identifier of script thread
    SCRIPTTHREADSTATE *pstsState  // receives state flag
);

Retrieves the current state of a script thread.

stidThread
[in] Identifier of the thread for which the state is desired, or one of the following special thread identifiers:
SCRIPTTHREADID_BASE The base thread; that is, the thread in which the scripting engine was instantiated.
SCRIPTTHREADID_CURRENT The currently executing thread.
pstsState
[out] Address of a variable that receives the state of the indicated thread. The state is indicated by one of the named constant values defined by the SCRIPTTHREADSTATE enumeration. If this parameter does not identify the current thread, the state may change at any time.

This method can be called from non-base threads without resulting in a non-base callout to host objects or to the IActiveScriptSite interface.

IActiveScript::InterruptScriptThread
HRESULT InterruptScriptThread(
    SCRIPTTHREADID   stidThread,  // identifier of thread
    const EXCEPINFO *pexcepinfo,  // receives error information
    DWORD dwFlags
);

Interrupts the execution of a running script thread (an event sink, an immediate execution, or a macro invocation). This method can be used to terminate a script that is stuck (in an infinite loop, for example). It can be called from non-base threads without resulting in a non-base callout to host objects or to the IActiveScriptSite method.

stidThread
[in] Identifier of the thread to interrupt, or one of the following special thread identifier values:
SCRIPTTHREADID_ALL All threads. The interrupt is applied to all script methods currently in progress. Note that unless the caller has requested that the script be disconnected, by calling the IActiveScript::SetScriptState method with the SCRIPTSTATE_DISCONNECTED or SCRIPTSTATE_INITIALIZED flag set, the next scripted event causes script code to run again.
SCRIPTTHREADID_BASE The base thread; that is, the thread in which the scripting engine was instantiated.
SCRIPTTHREADID_CURRENT The currently executing thread.
pexcepinfo
[in] Address of an EXCEPINFO structure that receives error information associated with the error condition.
dwFlags
[in] Option flags associated with the interruption. Can be one of these values:
SCRIPTINTERRUPT_DEBUG
If supported, enter the scripting engine's debugger at the current script execution point.
SCRIPTINTERRUPT_RAISEEXCEPTION
If supported by the scripting engine's language, let the script handle the exception. Otherwise, the script method is aborted and the error code is returned to the caller; that is, the event source or macro invoker.
IActiveScript::SetScriptSite
HRESULT SetScriptSite(
    IActiveScriptSite *pScriptSite  // address of host script site
);

Informs the scripting engine of the IActiveScriptSite interface site provided by the host. This method must be called before any other IActiveScript interface methods can be used.

pScriptSite
[in] Address of the host-supplied script site to be associated with this instance of the scripting engine. The site must be uniquely assigned to this scripting engine instance; it cannot be shared with other scripting engines.
IActiveScript::SetScriptState
HRESULT SetScriptState(
    SCRIPTSTATE ss  // identifier of new state
);

Puts the scripting engine into the given state. This method can be called from non-base threads without resulting in a non-base callout to host objects or to the IActiveScriptSite interface.

ss
[in] Sets the scripting engine to the given state. Can be one of the values defined in the SCRIPTSTATE enumeration.

For more information about scripting engine states, see Script Engine States.

See also IActiveScript::Clone, IActiveScript::GetScriptDispatch, IActiveScript::InterruptScriptThread, IActiveScriptParse::ParseScriptText, IActiveScriptSite::GetItemInfo

IActiveScriptError

An object implementing this interface is passed to the IActiveScriptSite::OnScriptError method whenever the scripting engine encounters an unhandled error. The host then calls methods on this object to obtain information about the error that occurred.

Methods in Vtable Order
GetExceptionInfo Retrieves information about an error.
GetSourcePosition Retrieves the location in the source code where an error occurred.
GetSourceLineText Retrieves the line in the source file where an error occurred.

IActiveScriptError::GetExceptionInfo
HRESULT GetExceptionInfo(
    EXCEPINFO *pexcepinfo  // structure for exception information
);

Retrieves information about an error that occurred while the scripting engine was running a script.

pexcepinfo
[out] Address of an EXCEPINFO structure that receives error information.
IActiveScriptError::GetSourceLineText
HRESULT GetSourceLineText(
    BSTR *pbstrSourceLine  // address of buffer for source line
);

Retrieves the line in the source file where an error occurred while a scripting engine was running a script.

pbstrSourceLine
[out] Address of a buffer that receives the line of source code in which the error occurred.
IActiveScriptError::GetSourcePosition
HRESULT GetSourcePosition(
    DWORD *pdwSourceContext,  // context cookie
    ULONG *pulLineNumber,     // line number of error
    LONG *pichCharPosition    // character position of error
);

Retrieves the location in the source code where an error occurred while the scripting engine was running a script.

pdwSourceContext
[out] Address of a variable that receives a cookie that identifies the context. The interpretation of this parameter depends on the host application.
pulLineNumber
[out] Address of a variable that receives the line number in the source file where the error occurred.
pichCharPosition
[out] Address of a variable that receives the character position in the line where the error occurred.

IActiveScriptParse

If the ActiveX Scripting engine allows raw text code scriptlets to be added to the script or allows expression text to be evaluated at run time, it implements the IActiveScriptParse interface. For interpreted scripting languages that have no independent authoring environment, such as VBScript, this provides an alternate mechanism (other than IPersist*) to get script code into the scripting engine, and to attach script fragments to various object events.

Methods in Vtable Order
InitNew Initializes the scripting engine.
AddScriptlet Adds a code scriptlet to the script.
ParseScriptText Parses the given code scriptlet, adding declarations into the name space and evaluating code as appropriate.

IActiveScriptParse::AddScriptlet
HRESULT AddScriptlet(
    LPCOLESTR pstrDefaultName,   // address of default name of scriptlet
    LPCOLESTR pstrCode,          // address of scriptlet text
    LPCOLESTR pstrItemName,      // address of item name
    LPCOLESTR pstrSubItemName,   // address of subitem name
    LPCOLESTR pstrEventName,     // address of event name
    LPCOLESTR pstrDelimiter,     // address of end-of-scriptlet delimiter
    DWORD dwSourceContextCookie, // application-defined value for debugging
    ULONG ulStartingLineNumber,  // starting line of the script
    DWORD dwFlags,               // scriptlet flags
    BSTR *pbstrName,             // address of actual name of scriptlet
    EXCEPINFO *pexcepinfo        // address of exception information
);

Adds a code scriptlet to the script. This method is used in environments where the persistent state of the script is intertwined with the host document and the host is responsible for restoring the script, rather than through an IPersist* interface. The primary examples are HTML scripting languages that allow scriptlets of code embedded in the HTML document to be attached to intrinsic events (for instance, ONCLICK="button1.text='Exit'").

pstrDefaultName
[in] Address of a default name to associate with the scriptlet. If the scriptlet does not contain naming information (as in the ONCLICK example above), this name will be used to identify the scriptlet. If this parameter is NULL, the scripting engine manufactures a unique name, if necessary.
pstrCode
[in] Address of the scriptlet text to add. The interpretation of this string depends on the scripting language.
pstrItemName
[in] Address of a buffer that contains the item name associated with this scriptlet. This parameter, in addition to pstrSubItemName, identifies the object for which the scriptlet is an event handler.
pstrSubItemName
[in] Address of a buffer that contains the name of a subobject of the named item with which this scriptlet is associated; this name must be found in the named item's type information. This parameter is NULL if the scriptlet is to be associated with the named item instead of a subitem. This parameter, in addition to pstrItemName, identifies the specific object for which the scriptlet is an event handler.
pstrEventName
[in] Address of a buffer that contains the name of the event for which the scriptlet is an event handler.
pstrDelimiter
[in] Address of the end-of-scriptlet delimiter. When the pstrCode parameter is parsed from a stream of text, the host typically uses a delimiter, such as two single quotation marks ("), to detect the end of the scriptlet. This parameter specifies the delimiter that the host used, allowing the scripting engine to provide some conditional primitive preprocessing (for example, replacing a single quotation mark ['] with two single quotation marks for use as a delimiter). Exactly how (and if) the scripting engine makes use of this information depends on the scripting engine. Set this parameter to NULL if the host did not use a delimiter to mark the end of the scriptlet.
dwSourceContextCookie
[in] Application-defined value that is used for debugging purposes.
ulStartingLineNumber
[in] Zero-based value that specifies which line the parsing will begin at.
dwFlags
[in] Flags associated with the scriptlet. Can be a combination of the following values:
SCRIPTTEXT_ISVISIBLE Indicates that the script text should be visible (and, therefore, callable by name) as a global method in the name space of the script.
SCRIPTTEXT_ISPERSISTENT Indicates that the code added during this call should be saved if the scripting engine is saved (for example, through a call to IPersist*::Save), or if the scripting engine is reset by way of a transition back to the initialized state. For more information about this state, see Script Engine States.
pbstrName
[out] Actual name used to identify the scriptlet. This will be, in order of preference: a name explicitly specified in the scriptlet text, the default name provided in pstrDefaultName, or a unique name synthesized by the scripting engine.
pexcepinfo
[out] Address of a structure containing exception information. This structure should be filled in if DISP_E_EXCEPTION is returned.
IActiveScriptParse::InitNew
HRESULT InitNew(void);

Initializes the scripting engine.

Before the scripting engine can be used, one of the following methods must be called: IPersist*::Load, IPersist*::InitNew, or IActiveScriptParse::InitNew. The semantics of this method are identical to IPersistStreamInit::InitNew, in that this method tells the scripting engine to initialize itself. Note that it is not valid to call both IPersist*::InitNew or IActiveScriptParse::InitNew and IPersist*::Load, nor is it valid to call IPersist*::InitNew, IActiveScriptParse::InitNew, or IPersist*::Load more than once.

IActiveScriptParse::ParseScriptText
HRESULT ParseScriptText(
    LPCOLESTR pstrCode,          // address of scriptlet text
    LPCOLESTR pstrItemName,      // address of item name
    IUnknown *punkContext,       // address of debugging context
    LPCOLESTR pstrDelimiter,     // address of end-of-scriptlet delimiter
    DWORD dwSourceContextCookie, // application-defined value for debugging
    ULONG ulStartingLineNumber,  // starting line of the script
    DWORD dwFlags,               // scriptlet flags
    VARIANT *pvarResult,         // address of buffer for results
    EXCEPINFO *pexcepinfo        // address of buffer for error data
);

Parses the given code scriptlet, adding declarations into the name space and evaluating code as appropriate.

pstrCode
[in] Address of the scriptlet text to evaluate. The interpretation of this string depends on the scripting language.
pstrItemName
[in] Address of the item name that gives the context in which the scriptlet is to be evaluated. If this parameter is NULL, the code is evaluated in the scripting engine's global context.
punkContext
[in] Address of the context object. This object is reserved for use in a debugging environment, where such a context may be provided by the debugger to represent an active run-time context. If this parameter is NULL, the engine uses pstrItemName to identify the context.
pstrDelimiter
[in] Address of the end-of-scriptlet delimiter. When pstrCode is parsed from a stream of text, the host typically uses a delimiter, such as two single quotation marks ("), to detect the end of the scriptlet. This parameter specifies the delimiter that the host used, allowing the scripting engine to provide some conditional primitive preprocessing (for example, replacing a single quotation mark ['] with two single quotation marks for use as a delimiter). Exactly how (and if) the scripting engine makes use of this information depends on the scripting engine. Set this parameter to NULL if the host did not use a delimiter to mark the end of the scriptlet.
dwSourceContextCookie
[in] Application-defined value that is used for debugging purposes.
ulStartingLineNumber
[in] Zero-based value that specifies which line the parsing will begin at.
dwFlags
[in] Flags associated with the scriptlet. Can be a combination of these values:
SCRIPTTEXT_ISEXPRESSION If the distinction between a computational expression and a statement is important but syntactically ambiguous in the script language, this flag specifies that the scriptlet is to be interpreted as an expression, rather than as a statement or list of statements. By default, statements are assumed unless the correct choice can be determined from the syntax of the scriptlet text.
SCRIPTTEXT_ISPERSISTENT Indicates that the code added during this call should be saved if the scripting engine is saved (for example, through a call to IPersist*::Save), or if the scripting engine is reset by way of a transition back to the initialized state.
SCRIPTTEXT_ISVISIBLE Indicates that the script text should be visible (and, therefore, callable by name) as a global method in the name space of the script.
pvarResult
[out] Address of a buffer that receives the results of scriptlet processing, or NULL if the caller expects no result (that is, the SCRIPTTEXT_ISEXPRESSION value is not set).
pexcepinfo
[out] Address of a structure that receives exception information. This structure is filled if IActiveScriptParse::ParseScriptText returns DISP_E_EXCEPTION.

If the scripting engine is in the initialized state, no code will actually be evaluated during this call; rather, such code is queued and executed when the scripting engine is transitioned into (or through) the started state. Because execution is not allowed in the initialized state, it is an error to call this method with the SCRIPTTEXT_ISEXPRESSION flag when in the initialized state.

The scriptlet can be an expression, a list of statements, or anything allowed by the script language. For example, this method is used in the evaluation of the HTML <SCRIPT> tag, which allows statements to be executed as the HTML page is being constructed, rather than just compiling them into the script state.

The code passed to this method must be a valid, complete portion of code. For example, in VBScript it is illegal to call this method once with Sub Function(x) and then a second time with End Sub. The parser must not wait for the second call to complete the subroutine, but rather must generate a parse error because a subroutine declaration was started but not completed.

For more information about script states, see Script Engine States.

Enumerations

This section describes the enumerations used by ActiveX Scripting engines.

SCRIPTSTATE
typedef enum tagSCRIPTSTATE {
    SCRIPTSTATE_UNINITIALIZED = 0,
    SCRIPTSTATE_INITIALIZED   = 5,
    SCRIPTSTATE_STARTED       = 1,
    SCRIPTSTATE_CONNECTED     = 2,
    SCRIPTSTATE_DISCONNECTED  = 3,
    SCRIPTSTATE_CLOSED        = 4
} SCRIPTSTATE;

Contains named constant values that specify the state of a scripting engine. This enumeration is used by the IActiveScript::GetScriptState, IActiveScript::SetScriptState, and IActiveScriptSite::OnStateChange methods.

SCRIPTSTATE_UNINITIALIZED
Script has just been created, but has not yet been initialized using an IPersist* interface and IActiveScript::SetScriptSite.
SCRIPTSTATE_INITIALIZED
Script has been initialized, but is not running (connecting to other objects or sinking events) or executing any code. Code can be queried for execution by calling the IActiveScriptParse::ParseScriptText method.
SCRIPTSTATE_STARTED
Script can execute code, but is not yet sinking the events of objects added by the IActiveScript::AddNamedItem method.
SCRIPTSTATE_CONNECTED
Script is loaded and connected for sinking events.
SCRIPTSTATE_DISCONNECTED
Script is loaded and has a run-time execution state, but is temporarily disconnected from sinking events.
SCRIPTSTATE_CLOSED
Script has been closed. The scripting engine no longer works and returns errors for most methods.
SCRIPTTHREADSTATE
typedef enum tagSCRIPTTHREADSTATE {
    SCRIPTTHREADSTATE_NOTINSCRIPT  = 0,
    SCRIPTTHREADSTATE_RUNNING      = 1
} SCRIPTTHREADSTATE;

Contains named constant values that specify the state of a thread in a scripting engine. This enumeration is used by the IActiveScript::GetScriptThreadState method.

SCRIPTTHREADSTATE_NOTINSCRIPT
Specified thread is not currently servicing a scripted event, processing immediately executed script text, or running a script macro.
SCRIPTTHREADSTATE_RUNNING
Specified thread is actively servicing a scripted event, processing immediately executed script text, or running a script macro.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.