Active debugging environment for debugging mixed-language scripting code6353923Abstract An active debugging environment for debugging a virtual application that contains program language code from multiple compiled and/or interpreted programming languages. The active debugging environment is language neutral and host neutral, where the host is a standard content centric script host with language engines for each of the multiple compiled and/or interpreted programming languages represented in the virtual application. The active debugging environment user interface can be of any debug tool interface design. The language neutral and host neutral active debugging environment is facilitated by a process debug manager that catalogs and manages application specific components, and a machine debug manager that catalogs and manages the various applications that comprise a virtual application being run by the script host. The process debug manager and the machine debug manager act as an interface between the language engine specific programming language details and the debug user interface. Claims What is claimed: Description COPYRIGHT AUTHORIZATION
Term Definition
Code Context A representation of a particular location in running
code of a language engine, such as a virtual instruction
pointer.
Code object An instance created by a script host that is associated
with a named item, such as the module behind a form
in Visual Basic, or a C++ class associated with a
named item.
Context An abstraction also referred to as document context
that represents a specific range in the source code of a
host document.
Debug Event A run-time flow altering condition, such as a
breakpoint, that is set in a virtual application by a
debugging environment user and managed by the
active debugging environment that controls the
running of the virtual application. Debug events are
defined by the active debugger.
Debugger IDE A replaceable component of the active debugging
environment that supports an Integrated Development
Environment (IDE) debugging User Interface (UI), and
the primary component that communicates with the
host application and one or more of the language
engines.
Expression A context of a resource, such as a stack frame, in
Context which expressions may be evaluated by a language
engine.
Host Application The application or process that hosts one or more
language engines and provides a scriptable set of
objects, also known as an object model.
Language A replaceable component of the active debugging
Engine environment, sometimes referred to as a scripting
engine, that provides parsing, executing, and
debugging abstractions for a particular language,
and implements IactiveScript and/or
IactiveScriptParse.
Machine Debug A key component of the active debugging environment
Manager that maintains a registry of debuggable application
processes.
Named item An object, such as one that supports OLE Automation,
that the host application deems interesting to a script.
Examples include the HTML Document object in a
Web browser or the Selection object in Microsoft
Word.
Object Browsing A structured, language-independent representation of
an object name, type, value, and/or sub-object that is
suitable for implementing a watch window user
interface.
Process Debug A key component of the active debugging environment
Manager that maintains a registry of components for a given
application that include the tree of debuggable
documents, language engines, running threads, and
other application resources.
Script A set of instructions that are run by a language engine.
A script can include, but is not limited to any
executable code, piece of text, a block of pcode, and/or
machine-specific executable byte codes. A script is
loaded into a language engine by a script host by way
of one of the Ipersist* interfaces or the
IactiveScriptParse interface.
Script language An interpreted programming language and the
language semantics used to write a script.
Script host An application or program that owns the
ActiveScripting engine. The scripting host implements
IactiveScriptSite and optionally
IactiveScriptSiteWindow.
Scriptlet A portion of a script that is attached to an object
event through IactiveScriptParse. An aggregate of
scriptlets is a script.
Standard Object Interface Example--FIG. 2 FIG. 2 illustrates a standard object interface example 200 in block diagram form. The standard object interface example 200 includes a local computing device 201 and a remote computing device 202, both of which can be personal computers. The remote computing device 202 includes a remote operating system 240 and a host process 250. The host process 250 includes at least one application object 251 having multiple interfaces including but not limited to interfaces 252-254. Each interface 252-254 is a standard COM interface that each exposes at least one method. The local computing device 201 includes a local operating system 210, a first host process 220 and a second host process 230. The local operating system 210 includes a plurality of application objects 211-212 each having at least one of a plurality of interfaces 214-218. The second host process 230 includes a plurality of application objects including 232-233 each having at least one the plurality of interfaces 234-238. The first host process 220 includes, but is not limited to, a plurality of local and/or remote interface calls 221-226 to respective interfaces in host processes 250, 230, and local operating system 210 as indicated by the directional arrows away from the first host process 220. The interface calls 221-226 occur at various points in a script 228 and two of the calls 222 and 226 result in the downloading of a small section of a foreign program into the script 228 for execution. The downloaded programs may have originated in any compiled or interpreted programming language other than the programming language of script 228. Key to each of the above referenced interface calls is that they are calls to common interfaces that are made in a common manner from any application or process. Scripting Architecture Overview and Operational Example--FIG. 3 A scripting language engine interface provides the capability to add scripting and OLE Automation capabilities to programs such as applications or servers. One example of a scripting language engine interface is embodied in the commercially available product known as ActiveXTM Scripting by Microsoft. ActiveX Scripting enables host computers to call upon disparate language engines from multiple sources and vendors to perform scripting between software components. The implementation of a script itself including the language, syntax, persistent format, execution model, and the like, is left to the script vendor. Care has been taken to allow host computers that rely on ActiveX Scripting to use arbitrary language back-ends where necessary. Scripting components fall into at least two categories that include script hosts and language engines. A script host creates an instance of a language engine and calls on the language engine to run at least one portion of a script. Examples of script hosts can include but are not limited to Internet and Intranet browsers, Internet and Intranet authoring tools, servers, office applications, and computer games. A desirable scripting design isolates and accesses only the interface elements required by an authoring environment so that non-authoring host computers such as browsers and viewers, and the associated language engines can be kept relatively compact. FIG. 3 illustrates an operational active scripting architecture example 300 in flow diagram form. Examples of active scripting interfaces are disclosed in Appendix A. Components of the operational active scripting architecture example 300 include a language engine 301, a host document or application 305, a script 304, and various object interfaces 310-314 for the language engine 301 and host application 305 respectively. The following discussion illustrates the interactions between the language engine 301 and the host application 305. First, a host application 305 begins operations by creating an instance of the application in a workspace of a computing device. A copy of the host application 305 can be obtained from a storage device 306 or other source in any manner well known in the art. Second, the host application 305 creates an instance of the language engine 301 by calling the function CoCreatelnstance and specifying the class identifier (CLSID) of the desired language engine 301. For example, the Hyper Text Markup Language (HTML) browsing component of Internet Explorer receives the language engine's class identifier through the CLSID=attribute of the HTML <OBJECT> tag. The host application 305 can create multiple instances of language engine 301 for use by various applications as needed. The process of initiating a new language engine is well known in the art. Third, after the language engine 301 is created, the host application 305 loads the script 304 itself into the language engine 301 by way of interface/method 310. If the script 304 is persistent, the script 304 is loaded by calling the IPersist*::Load method 310 of the language engine 301 to feed it the script storage, stream, or property bag that is resident on the host application 305. Loading the script 304 exposes the host application's object model to the language engine 301. Alternatively, if the script 304 is not persistent then the host application 305 uses IPersist*::InitNew or IActiveScriptParse::InitNew to create a null script. As a further alternative, a host application 305 that maintains a script 304 as text can use IActiveScriptParse::ParseScriptText to feed the language engine 301 the text of script 304 after independently calling the function InitNew. Fourth, for each top-level named item 303 such as pages and/or forms of a document that are imported into the name space 302 of the language engine 301, the host application 305 calls IActiveScript::AddNamedItem interface/method 311 to create an entry in the name space 302. This step is not necessary if top-level named items 303 are already part of the persistent state of the previously loaded script 304. A host application 305 does not use AddNamedItem to add sublevel named items such as controls on an HTML page. Instead, the language engine 301 indirectly obtains sublevel items from top-level items by using the ITypeInfo and/or IDispatch interface/method 314 of the host application 305. Fifth, the host application 305 causes the language engine 301 to start running the script 304 by passing the SCRIPTSTATE_CONNECTED value to the IActiveScript::SetScriptState interface/method 311. This call typically executes any language engine construction work, including static bindings, hooking up to events, and code execution similar to a scripted "main()" function. Sixth, each time the language engine 301 needs to associate a symbol with a top-level named item 303, the language engine 301 calls the IActiveScriptSite::GetItemInfo interface/method 312. The, the IActiveScriptSite::GetItemInfo interface/method 312 can also return information about the named item in question. Seventh, prior to starting the script 304 itself, the language engine 301 connects to the events of all relevant objects through the IConnectionPoint interface/method 313. For example, the IConnectionPoint::Advise(pHandler) message provides the language engine 301 with a request for notification of any events that occur in the host application 305. The IConnectionPoint::Advise message passes an object pHandler that can be called when an event occurs in the host application 305. Once an event occurs in the host application 305, the host application 305 transmits a message to the language engine 301 pdispHandler::Invoke(dispid) as notice that an event occurred in the host application 305. If the event that occurred matches an event that is being monitored by the language engine 301, the language engine 301 can activate a predetermined response. Finally, as the script 304 runs, the language engine 301 realizes references to methods and properties on named objects through the IDispatch::Invoke interface/method 314 or other standard COM binding mechanisms. Additional implementation specific details of ActiveX Scripting interfaces and methods are disclosed Appendix A. One purpose of ActiveX is to allow a developer to expose internal objects and/or properties of an application as interfaces and methods available to other applications. A method is an action which the object can perform, and a property is an attribute of the object similar to a variable. The ActiveX interfaces include IDispatch which is an interface to manipulate ActiveX objects. This process is used to get a property, set a property, or call a method. The process uses a late binding mechanism that enables a simple non-compiled interpretive language. Type information in ActiveX includes ITypeInfo which is used for describing an object. A collection of these TypeInfos constitutes a type library, which usually exists on a disk in the form of a data file. The data file can be accessed through ITypeLib and is typically created using MKTypLib. In ActiveX scripting, the type information is provided by scripting hosts and objects that are used by the scripting hosts. Active Debugging Environment--FIG. 4 FIG. 4 illustrates an example of an active debugging environment 400 in block diagram form based on the standard object interface example 200 of FIG. 2. In the active debugging environment 400 example, the first host process 220 contains the application 421 that is the debugging target although any application in one of the host processes 220, 230, or 250 can be the debugging target if desired. For example, the host process 250 might include an Internet web page application on an Internet server 202, and the host process 220 might include an Internet browser application under development on an end user's local machine 201. The Internet browser application under development would be the debugging target so that the application developer can watch what is happening as the browser interacts with the remote web page and exercises various features and controls of the web page. Components of the overall active debugging environment 400 include active scripting application components 420, key debugging environment interface components that include the PDM 424 and the MDM 411, and the IDE 410 debug interface. It is important to note that the active scripting application components 420 are standard application components of a product, such as an Internet browser, that are shipped to and used by an end user upon general release of a version of the product. That the standard application components are designed with active debugging environment interfaces in mind is transparent to the end user of the application. Note also that the IDE 410 is an active debugging component that is replaceable by any developer wishing to architect a debugging interface. The PDM 424 and MDM 411 are the fundamental components of the active debugging environment 400 with which the active scripting application components 420 and the IDE 410 must interact to facilitate a functional debugging environment. The IDE 410 is a debug user interface between the debug user and the active debugging environment 400. The typical IDE 410 allows a debug user to engage in real time document and/or application editing, requesting various views of the running application, defining breakpoints and other execution control management features, requesting expression evaluation and watch windows, and browsing stack frames, objects, classes, and application source code. One example of debug interfaces for an IDE 410 are disclosed in Appendix B. The architecture of an IDE 410 can be designed to support features such as CModule, CBreakpoint, CApplicationDebugger, and CurStmt. For example, there can be one CModule instance per document/application being debugged such that the instance is maintained in a doubly-linked list headed by g_pModuleHead. Entries in the list can be displayed to the debug user in a selectable Module menu and any selected list item would result in document text being displayed in the richedit control. From the richedit control, the debug user could define set breakpoints or user other viewing features. If a debug user were to set a breakpoint, one Cbreakpoint instance would be generated and maintained in a doubly-linked list headed by the g_pBpHead field of the associated CModule. Each breakpoint position could be represented to the debug user as a text range of the document. One CApplicationDebugger instance would be generated and maintained by the application that implements the IApplicationDebugger interface so that the CApplicationDebugger could respond to all debug events that occur. Finally, the CurStmt could hold the location of the current statement being executed in addition to referencing the thread associated with the present breakpoint. The Machine Debug Manager (MDM) 411 maintains a list of active virtual applications and is a central interface between the IDE 410 and the active script components 420. Virtual applications are collections of related documents and code in a single debuggable entity such that separate application components in a continuous line of code can share a common process and/or thread. A virtual application is the aggregate of multiple applications in multiple programming languages. One key role of the machine debug manager is to act as a program language registry that provides a mapping between a given application in the virtual application aggregate and the active debugger IDE 410 that is controlling the virtual application during the debug process. The MDM 411 eliminates the traditional debugging model where the debugger for a given programming language only has knowledge of a specific source and object code mapping. Instead, the MDM 411 places the burden of language specific details on the programming language to determine, for example, the mapping of a breakpoint requested by the debug user to a specific instruction in the programming language code within a given application. For an interpreted programming language, a programming language specific decision is passed through the PDM 424 to an appropriate language engine 422423. For a compiled programming language, a programming language specific decision is passed through the PDM 424 to a library of source and object codes associated with an appropriate language engine 422-423. The active scripting application components 420 include a script host 421 and at least one language engine 422-423, and each of the at least one language engine 422-423 operate in close cooperation with the PDM 424. The PDM 424 includes a catalog of components within a given application, and acts as an interface for all in-process activities and synchronizes the debugging activities of the multiple language engines 422423 such as merging stack frames and coordinating breakpoints for example. The PDM 424 also maintains a debugger thread for asynchronous processing and acts as the communication interface for the MDM 411 and the IDE 410. A language engine 422-423 supports a specific language implementation and provides specific language features used by the corresponding program language code in the virtual application. Among the specific language features are the breakpoint, start, stop, and jump debug implementations, expression evaluations, syntax coloring, object browsing, and stack frame enumeration. Each language specific feature is unique to a programming language regardless of the quantity of that programming language that exists in the virtual application. The application or script host 421 provides the environment for the language engines 422-423. Additional tasks of the script host 421 include supporting an object model, providing context for scripts, organizing scripts into virtual applications, maintaining a tree of documents being debugged and their contents, and providing overall document management. An example of a script host is an Internet browser such as Internet Explorer or Spruuids. One important script host concept is that a host does not necessarily require a design that has debugging in mind because it is the programming language that must have been created with debugging in mind. For this reason, the script host 421 does not require specific knowledge of any language specific debugging features. Specific knowledge of language specific debugging features is the task of the individual language engines 422-423 and/or their associated libraries. It is also important to note that depending on the design of a script host 421, the script host 421 can exist in the active debugging environment 400 as a smart host or a dumb host. A dumb host is not aware of all available debug interfaces because all scripts are separate and/or are managed by language engines independently of each other, and no contextual view of source code exists. Nevertheless, a dumb host can support self-contained languages such as Java and can provide a default virtual application for the current process. Alternatively, a smart host is aware of the debug interfaces and can group program code and documents into a single virtual application to provide visual context to embedded languages such as HTML. The smart host takes advantage of and supports integrated debugging support across a mixed model of programming languages and is generally aware of the context and origin of individual scripts. Although, a smart host provides a more robust and efficient debugging environment, debugging can proceed in kind for a dumb host even if with somewhat limited flexibility. Active Debugging Environment Operational Steps--FIGS. 5-7 FIG. 5 illustrates an example overview of active debugging environment operational steps 500 in flow diagram form. The active debugging environment operational steps 500 begin at step 508 and represent a high-level view of steps involved in the setup and operation of an active debugging environment where programming language code from multiple compiled and/or interpreted programming languages are present in the same virtual application debug target. At step 512, the script host 421 generates a virtual application for run time execution. The virtual application can contain program language code from only single programming language, or the virtual application can contain an aggregate of programming language code from multiple compiled and/or interpreted programming languages. Additional details of step 512 are disclosed in the text accompanying FIG. 6. At step 521, an active debugging environment is established that controls the stepwise flow of a run time script. Key to the active debugging environment 400 being programming language neutral and content-centric host neutral is that the programming language debug specifics are embedded in the active scripting application components 420 rather than in the debugging tool itself. Key responsibilities of the active debugging environment 400 is to facilitate programming language neutral and host neutral debugging by interfacing the IDE 410 user interface with the active scripting application components 420 by way of the catalog of applications maintained in the MDM 411 and the catalog of application components in the PDM 424. The MDM 411 and the PDM 424 determine which application and which language engine 422-423 is responsible for a given section of program language code in the virtual application as previously disclosed in the text accompanying FIG. 4. At step 530, with the run time environment established and the active debug environment in place, the previously generated virtual application is executed under the control of the active debugging environment 400. Note that during run time of the virtual application at step 538, that the active debugging environment 400 accommodates the dynamic run-time modification of program code in the script without disrupting script execution flow or the active debugging operations. One reason this dynamic run-time environment is possible even with the existence of compiled programming language segments present, is that each programming language segment added to or removed from the running script is accompanied by the necessary language engine support to assist with the language specific debug details. At step 550, a debug user or application developer interacts with the active debugging environment during the debugging process by way of the IDE 410. Additional details of the debugging process interactions are disclosed in the text accompanying FIG. 7. The active debug operational steps 500 end at step 560 at the time the application developer chooses to stop the debugging process. FIG. 6 illustrates details of the active scripting run-time environment operational steps 600 for a virtual application in flow diagram form. The active scripting run-time environment operational steps 600 begin at step 608 and represent the details of step 512 of FIG. 5. Although the text accompanying FIG. 6 discloses the details of one type of run-time environment for virtual applications, the active debugging environment 400 of the present invention is host neutral and functions equally well with any COM designed active scripting run-time environment. At step 612, an instance of a script host 421 is created in an application 220 to manage run-time execution of a virtual application. Along with the script host 421, at least one programming language engine 422-423 is generated for each programming language used in an application. At step 622, the multiple objects within the application are combined into a single virtual application, also known as script text. At step 630 the single virtual application is loaded into the script host 421 for run-time execution. Processing continues at step 638 by returning to step 512 of FIG. 5. FIG. 7 illustrates details of debugging operational steps 700 in flow diagram form in the context of the active debugging environment 400. The debugging operational steps 700 begin at step 708 and represent the details of step 550 in FIG. 5. At step 712, an active debugging environment 400 is established that includes an IDE 410 as a user interface, a MDM 411 to catalog applications that are present and manage language specific interactions with each target application, and a PDM 424 to catalog application components and manage component specific activities during the debug process. At step 720, the virtual application script and the script host 421 are identified and the virtual application is run under the control of the active debugging environment 400. Starting a virtual application under the control of an active debugging environment means that breakpoints, stepwise code execution, and/or other script flow altering activities can be set at will by a human user to alter the run-time script flow as desired during the debug process. At step 728, one or more event monitoring cases can be set in the active debugging environment 400 by communicating the event criteria to the appropriate active scripting application components 420 by way of the MDM 411 and/or PDM 424, and the IDE 410 user interface. Each event is specific to a given portion of the run-time script text even though the script text programming language details are transparent to the debug user. Further, the number of event monitoring cases defined for a given virtual application can be dynamically altered as different programming language code sections are downloaded to the script host 421 to dynamically become part of the running virtual application. If it is determined at decision step 735 that the run-time script text has not reached an event being monitored, then the run-time script text continues running at step 735. In the mean time, the debug user is free to carry out other activities in the context of the active debugging environment that can include, but are not limited to, viewing other documents, the document tree, source code, or even make changes to the source code as desired. Alternatively, if it is determined at decision step 735 that the run-time script text has reached an event being monitored, then processing continues at step 742. At step 742, a predefined debugging response is activated in response to the occurrence of the monitored event. Predefined responses can include, but are not limited to, displaying a range of script text that contains a breakpoint, displaying variable or other reference contents, and displaying stack pointers,-all within the context supported by the corresponding language engine specific to the immediate programming language statements. All communications between the debug user and the script host 421 are facilitated by the MDM 411 and/or the PDM 424 that process and pass requests to an appropriate language engine 422-423 for a response. If it is determined at decision step 755 by the debug user that the debugging process should continue, then processing continues at step 728 as previously disclosed. Alternative, if it is determined at decision step 755 by the debug user that the debugging process is complete, then the debug communicates to the IDE 410 that debug processing should stop and processing continues at step 762 by returning to step 550 of FIG. 5. Conclusion The present invention is an active debugging environment that is programming language independent and host application independent for use in debugging a mixture of compiled and interpreted programming languages in a given application. The programming language and host application independence is facilitated by Machine Debug Manager and Process Debug Manager interfaces that identify an appropriate language engine and/or application specific components that is responsible for unique programming language details. Appendices are attached to this document that disclose examples of active run-time script engine interfaces and active debugging environment interfaces. Specific active run-time script implementation interfaces are disclosed in Appendix A. Specific active debugging environment implementation interfaces are disclosed in Appendix B. Although specific embodiments are disclosed herein, it is expected that persons skilled in the art can and will make, use, and/or sell alternative active debugging environment systems that are within the scope of the following claims either literally or under the Doctrine of Equivalents. Appendix A: ActiveX Scripting Interfaces and Methods IActiveScript The scripting engine must implement the IActiveScript interface in order to be an ActiveX Scripting engine.
Methods in Vtable Order
Description
IUnknown methods
QueryInterface Returns pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IActiveScript methods
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 Puts the scripting engine into the given 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
methods and properties associated with the
running script itself.
GetCurrentScriptThread Retrieves a scripting-engine-defined identifier
ID for the currently executing thread.
GetScriptThreadID Retrieves a scripting-engine-defined identifier
for the thread associated with the given
Microsoft Win32 .RTM. 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,
unsited scripting engine 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 both. 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 item. Can be a combination of these values:
Meaning
Value
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.
Children (properties of the ob-
ject that are in themselves ob-
jects) can also source events
to the script. This is not
recursive, but it provides a
convenient mechanism for the
common case, for example, of
adding 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. Because by conven-
tion the properties of the item
include the item's children, all
child object properties and
methods (and their children, re-
cursively) will be accessible.
SCRIPTITEM_GLOBALMEMBERS Indicates that the item is a col-
lection of global properties and
methods associated with the
script. Normally, a scripting en-
gine would ignore the object
name (other than for the purpose
of using it as a cookie for
IActiveScriptSite::GetItemInfo,
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 script-
ing engine to deal with name
conflicts (for example,
when two
SCRIPTITEM_GLOBALMEM-
BERS items have methods of the
same name), although an error
should not be returned because
of this situation.
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 as-
sociated. 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.
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.
Returns
S_OK The named item was success-
fully added to the script's name
space.
E_UNEXPECTED The call was not expected (for
example, the scripting engine
has not been loaded or
initialized.
E_POINTER An invalid pointer was specified.
E_INVALIDARG An argument was invalid.
See also IActiveScriptSite::GetItemInfo
IActiveScript::AddTypeLib
HRESULT AddTypeLib (
REFGUID guidTypeLib, //LIBID 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] LIBID of the type library to add. dwMaj [in] Major version number. dwMin [in] Minor version number. dwFlags [in] Option flags. Can be SCRIPTTYPELIB_ISCONTROL, which indicates that the type library describes an ActiveX control used by the host.
Returns
S_OK The specified type library was suc-
cessfully added.
E_UNEXPECTED The call was not expected (for
example, the scripting engine has
not yet been loaded or initialized).
TYPE_E_CANTLOADLIBRARY The specified type library could
not be loaded.
E_INVALIDARG An argument was invalid.
Returns
S_OK The specified type library was suc-
cessfully added.
E_UNEXPECTED The call was not expected (for
example, the scripting engine has
not yet been loaded or initialized).
TYPE_E_CANTLOADLIBRARY The specified type library could
not be loaded.
E_INVALIDARG An argument was invalid.
Clones the current scripting engine (minus any current execution state), returning a loaded, unsited scripting engine in the current thread. The state of this new scripting engine should be identical to the state 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 unsited, cloned scripting engine. The host must create a site and call SetScriptSite on the new scripting engine before it will be in the initialized state and, therefore, usable. The 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 GetItemIinfo. 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 Ipersist*. This method can be called from non-base threads without resulting in a non-base callout to host objects or to IActiveScriptSite.
Returns
S_OK The scripting engine was successfully cloned.
E_NOTIMPL The Clone method is not supported.
E_POINTER An invalid pointer was specified.
E_UNEXPECTED The call was not expected (for example, the script-
ing engine has not yet been loaded or initialized).
See also IActiveScript::SetScriptSite, IActiveScriptSite, IActiveScriptSite::GetItemInfo 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 InterruptScriptThread to cancel a running script thread). This method must be called by the creating host before it calls Release to prevent circular reference problems.
Returns
S_OK The script was successfully cloned.
S_FALSE The method succeeded, but the script was
already closed.
OLESCRIPT_S_PENDING The method was queued successfully, but
the state hasn't changed yet. When the
state changes, the site will be called back
on IActiveScriptSite::OnStateChange.
E_UNEXPECTED The call was not expected (for example,
the scripting engine was already in the
closed state).
See also IActiveScript::InterruptScriptThread, IActiveScriptSite:: OnStateChange
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 InterruptScriptThread. 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 IActiveScriptSite.
Returns
S_OK The identifier was successfully retreived.
E_POINTER An invalid pointer was specified.
See also IActiveScript::InterruptScriptThread, IActiveScriptSite
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 running script itself. 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 IActiveScriptParse, the IDispatch interface returned by this function can dynamically support new methods and properties. Similarly, IDispatch::GetTypeInfo should return a new, unique ITypeInfo 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.
Returns
S_OK The dispatch object for the script was successfully
retreived.
S_FALSE The scripting engine does not support a dispatch
object; the ppdispparameter is set to NULL.
E_UNEXPECTED The call was not expected (for example, the script-
ing engine has not yet been loaded or initialized).
E_POINTER An invalid pointer was specified.
E_INVALIDARG An argument was invalid.
Returns
S_OK The dispatch object for the script was successfully
retreived.
S_FALSE The scripting engine does not support a dispatch
object; the ppdispparameter is set to NULL.
E_UNEXPECTED The call was not expected (for example, the script-
ing engine has not yet been loaded or initialized).
E_POINTER An invalid pointer was specified.
E_INVALIDARG An argument was invalid.
Retrieves the site object associated with the ActiveX Scripting engine. iid [in] Identifier of the requested interface. ppvSite Object [out] Address of the location that receives the interface pointer to the host's site object.
Returns
S_OK The site object was successfully retreived.
S_FALSE No site has been set; ppvSiteObject is set to NULL.
E_POINTER An invalid pointer was specified.
E_INVALIDARG An argument was invalid.
E_NOINTERFACE The specified interface is not supported.
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 IActiveScriptSite. 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.
Returns
S_OK The state information was successfully retrieved.
E_POINTER An invalid pointer was specified.
See also IActiveScriptSite, SCRIPTSTATE
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. This identifier can be used in subsequent calls to script thread execution control methods such as lnterruptScriptThread. 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. This method can be called from non-base threads without resulting in a non-base callout to host objects or to IActiveScriptSite.
Returns
S_OK The identifier was successfully retrieved.
E_POINTER An invalid pointer was specified.
E_UNEXPECTED The call was not expected (for example, the
scripting engine has not yet been loaded or
initialized).
See also IActiveScript::InterruptScriptThread, IActiveScriptSite
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:
Value Meaning
SCRIPTTHREADID_CURRENT The currently executing thread.
SCRIPTTHREADID_BASE The base thread; that is, the thread
in which the scripting engine was
instantiated.
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 IActiveScriptSite.
Returns
S_OK The current state was successfully retrieved.
E_POINTER An invalid pointer was specified.
E_UNEXPECTED The call was not expected (for example, the
scripting engine has not yet been loaded or
initialized).
See also IActiveScriptSite, SCRIPTTHREADSTATE
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 (for example, in an infinite loop). It can be called from non-base threads without resulting in a non-base callout to host objects or to IActiveScriptSite. stid Thread [in] Thread identifier of the thread to interrupt, or one of the following special thread identifier values:
Value Meaning
SCRIPTTHREADID_CURRENT The currently executing thread
SCRIPTTHREADID_BASE The base thread; that is, the thread in
which the scripting engine was
instantiated.
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
SetScriptState with the
SCRIPTSTATE_DISCONNECTED
or
SCRIPTSTATE_ INITIALIZED
flag, the next scripted event
causes script code to run again.
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.
Returns
S_OK The given thread was successfully interrupted.
E_POINTER An invalid pointer was specified.
E_INVALIDARG An argument was invalid.
E_UNEXPECTED The call was not expected (for example, the
scripting engine has not yet been loaded or
initialized).
See also IActiveScript::SetScriptState, IActiveScriptSite
IActiveScript::SetScriptSite
HRESULTS SetScriptSite (
IActiveScriptSite *pScriptSite // address of host script site
);
Informs the scripting engine of the IActiveScriptSite site provided by the host. This method must be called before any other IActiveScript 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; cannot be shared with other scripting engines.
Returns
S_OK The host site was set successfully.
E_POINTER An invalid pointer was spicified.
E_INVALIDARG An argument was invalid.
E_FAIL An unspecified error occurred; the scripting
engine was unable to finish initializing the site.
E_UNEXPECTED The call was not expected (for example, a site was
already set).
See also IActiveScriptSite
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 IActiveScriptSite. [in] Sets the scripting engine to the given state. Can be one of the values defined in the SCRIPTSTATE enumeration: SCRIPTSTATE_INITIALIZED Returns the scripting engine back to the initialized state from the started, connected, or disconnected state. Because languages can vary widely in semantics, scripting engines are not required to support this state transition. Engines that support IActiveScript::Clone 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 Load or InitNew (and possibly also call 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 IActiveScriptSite::GetItemInfo. The engine must refetch 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 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). These languages may or may not retain code added by calling IActiveScriptParse. 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 lPersist*::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 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 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 InterruptScriptThread to cancel a running script thread without waiting for current events, and so on, to finish running. SCRIPTSTATE_STARTED The transition to this mode causes any code that was queued during the initialized state to be executed. From this state, script code can be executed, for example, by calling IActiveScriptParse::ParseScriptText or by calling the IDispatch interface obtained from IActiveScript::GetScriptDispatch. The transition to this state is also the appropriate time to execute routines such as a main()-like script routine, if appropriate for the script language. SCRIPTSTATE_CONNECTED Causes the script to connect to events. 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. SCRIPTSTATE_DISCONNECTED Causes the script to disconnect from event sinks. This can be done either logically (ignoring events received) or physically (calling Unadvise on the appropriate connection points). Returning to the connected state reverses this process. 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 InterruptScriptThread to cancel a running script thread). The script's execution state is maintained. For example, an HTML browser may put the scripting engine into this state when a scripted HTML page is moved into the LRU cache, before the page is actually destroyed.
Returns
S_OK The script successfully entered the given
state.
S_FALSE The method succeeded, but the script was
already in the given state.
OLESCRIPT_S_PENDING The method was queued successfully,
but the state hasn't changed yet. When
the state changes, the site will be
called back through the
IActiveScriptSite::OnStateChange method.
E_FAIL The scripting engine does not support the
transition back to the initializedstate. The
host must discard this scripting engine and
create, initialize, and load a new scripting
engine to achieve the same effect.
E_UNEXPECTED The call was not expected (for example,
the scripting engine has not yet been
loaded or initialized).
See also IActiveScript::Clone, IActiveScript::GetScriptDispatch, IActiveScript::InterruptScriptThread, IActiveScriptParse::ParseScriptText, IActiveScriptSite, IActiveScriptSite::GetItemInfo, IActiveScriptSite::OnStateChange, SCRIPTSTATE 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 IActiveScriptParse. For interpreted scripting languages that have no independent authoring environment, such as Visual Basic Script, 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
Description
IUnknown methods
QueryInterface Returns pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IActiveScriptParse Methods
InitNew Initialzes 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.
Methods in Vtable Order
Description
IUnknown methods
QueryInterface Returns pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IActiveScriptParse Methods
InitNew Initialzes 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.
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 must be restored under the host's control, rather than through IPersist*. The primary examples are HTML scripting languages that allow scriptlets of code embedded in the HTML document to be attached to intrinsic events (for example, 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. pstrEndDelimiter [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. dwFlags [in] Flags associated with the scriptlet. Can be a combination of the following values:
Value Meaning
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_ISPERSISTANT Indicates that the code added during
this call should be saved if the script-
ing 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.
pbstrName [out] The 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] Pointer to a structure containing exception information. This structure should be filled in if DISP_E_EXCEPTION is returned.
Returns
S_OK The scriptlet was success-
fully added to the script-the
pbstrName parameter contains
the scriptlet's name.
OLESCRIPT_E_INVALIDNAME The default name supplied is in-
valid in this scripting language.
OLESCRIPT_E_SYNTAX An unspecified syntax error oc-
curred in the scriptlet.
DISP_E_EXCEPTION An exception occurred in the par-
sing of the scriptlet; the pexcepinfo
parameter contains information
about the exception.
E UNEXPECTED The call was not expected (for
example, the scripting engine
has not yet been loaded or
initialized).
E_NOTIMPL This method is not supported; the
scripting engine does not support
adding event-sinking scriptlets.
E_POINTER An invalid pointer was specified.
E_INVALIDARG An argument was invalid.
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 InitNew and Load, nor is it valid to call InitNew or Load more than once.
Returns
S_OK The scripting engine was successfully initialized.
E_FAIL An error occurred during initialization.
Returns
S_OK The scripting engine was successfully initialized.
E_FAIL An error occurred during initialization.
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 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. pstrEndDelimiter [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. dwFlags [in] Flags associated with the scriptlet. Can be a combination of these values:
Value Meaning
SCRIPTTEXT_ISEXPRESSION If the distinction between a compu-
tational 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
by saved if the scripting engine
is saved (for example, through
a call to IPersis*::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, there-
fore, 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 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 Foo(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.
Returns
S_OK The expression or statement(s) has
been evaluated. The pvarResult
parameter contains the result, if any.
E_POINTER An invalid pointer was specified.
E_INVALIDARG An argument was invalid.
E_UNEXPECTED The call was not expected (for
example, the scripting engine is in
the uninitialized or closed state,
or the SCRIPTTEXT_IS-
EXPRESSION flag was set and
the scripting engine is in the
initialized state).
DISP_E_EXCEPTION An exception occurred in the process-
ing of the scriptlet. the pexcepinfo para-
meter contains information about the
exception.
OLESCRIPT_E_SYNTAX An unspecified syntax error occurred
in the scriptlet.
E_NOTIMPL This method is not supported. The
scripting engine does not support
run-time evaluation of expressions
or statements.
IActiveScriptError An object implementing this interface is passed to IActiveScriptSite::OnScriptError 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
Decription
IUnknown methods
QueryInterface Returns pointers to supported interfaces.
AddRef Increments the reference count.
IActiveScriptError methods
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.
Returns
S_OK The error information was successfully retrieved.
E_FAIL An error occurred.
Returns
S_OK The error information was successfully retrieved.
E_FAIL An error occurred.
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.
Returns
S_OK The line in the source file was successfully retrieved.
E_FAIL An 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.
Returns
S_OK The error location was successfully retrieved.
E_FAIL An error occurred.
IActiveScriptSite The host must create a site for the ActiveX Scripting engine by implementing IActiveScriptSite. Usually, this site will be associated with the container of all the objects that are visible to the script (for example, the ActiveX controls). Typically, this container will correspond to the document or page being viewed. Internet Explorer, for example, would create such a container for each HTML page being displayed. Each ActiveX control (or other automation object) on the page, and the scripting engine itself, would be enumerable within this container.
Methods in Vtable Order
Description
IUnknown methods
Queryinterface Returns pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IActiveScriptSite methods
GetLCID Retrieves the locale identifier that the host
uses for displaying user-interface elements.
GetItemInfo Obtains information about an item that was
added to an engine through a call to the
IActiveScript::AddNamedItem method.
GetDocVersionString Retrieves a host-defined string that uniquely
identifies the current document version from
the host's point of view.
OnScriptTerminate Informs the host that the script has com-
pleted execution.
OnStateChange Informs the host that the scripting engine has
changed states.
OnScriptError Informs the host that an execution error
occurred while the engine was running the
script.
OnEnterScript Informs the host that the scripting engine has
begun executing the script code.
OnLeaveScript Informs the host that the scripting engine has
returned from executing script code.
Methods in Vtable Order
Description
IUnknown methods
Queryinterface Returns pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IActiveScriptSite methods
GetLCID Retrieves the locale identifier that the host
uses for displaying user-interface elements.
GetItemInfo Obtains information about an item that was
added to an engine through a call to the
IActiveScript::AddNamedItem method.
GetDocVersionString Retrieves a host-defined string that uniquely
identifies the current document version from
the host's point of view.
OnScriptTerminate Informs the host that the script has com-
pleted execution.
OnStateChange Informs the host that the scripting engine has
changed states.
OnScriptError Informs the host that an execution error
occurred while the engine was running the
script.
OnEnterScript Informs the host that the scripting engine has
begun executing the script code.
OnLeaveScript Informs the host that the scripting engine has
returned from executing script code.
Retrieves a host-defined string that uniquely identifies the current document version from the host's point of view. If the related document has changed outside the scope of ActiveX Scripting (as in the case of an HTML page being edited with NotePad), the scripting engine can save this along with its persisted state, forcing a recompile the next time the script is loaded. pstrVersionString [out] Address of the host-defined document version string.
Returns
S_OK The document version string was successfully retrieved.
The pstrVersionString parameter contains the string.
E_NOTIMPL This method is not supported. The scripting engine
should assume that the script is in sync with the
document.
Returns
S_OK The document version string was successfully retrieved.
The pstrVersionString parameter contains the string.
E_NOTIMPL This method is not supported. The scripting engine
should assume that the script is in sync with the
document.
Allows the scripting engine to obtain information about an item added with IActiveScript::AddNamedItem. pstrName [in] The name associated with the item, as specified in IActiveScript::AddNamedItem. dwReturnMask [in] A bit mask specifying what information about the item should be returned. The scripting engine should request the minimum needed information because some of the return parameters (for example, ITypeinfo) can take considerable time to load or generate. Can be a combination of the following values:
Value Meaning
SCRIPTINFO_IUNKNOWN Return the IUnknown interface for this
item.
SCRIPTINFO_ITYPEINFO Return the ITypeInfo interface for this
item.
ppunkitem [out] Address of a variable that receives a pointer to the IUnknown interface associated with the given item. The scripting engine can use the QueryInterface method to obtain the IDispatch interface for the item. This parameter receives NULL if dwReturnMask does not include the SCRIPTINFO_IUNKNOWN value. Also, it receives NULL if there is no object associated with the item name; this mechanism is used to create a simple class when the named item was added with the SCRIPTITEM CODEONLY flea set. ppTypeInfo [out] Address of a variable that receives a pointer to the ITypeInfo interface associated with the item. This parameter receives NULL if dwReturnMask does not include the SCRIPTINFO_ITYPEINFO value, or if type information is not available for this item. If type information is not available, the object cannot source events, and name binding must be realized with IDispatch::GetlDsOfNames. Note that this ITypeInfo describes the coclass (TKIND_COCLASS) because the object may support multiple interfaces and event interfaces. If the item supports the IProvideMultipleTypeInfo interface, the ITypeInfo interface corresponds to the ITypeInfo of index zero obtained from IProvideMultipleTypeInfo::GetinfoOfIndex. This method retrieves only the information indicated by the dwReturnMask parameter. This improves performance, for example, in the case where an ITypeInfo interface is not needed for an item.
Returns
S_OK The requested interface pointer was
successfully retrieved. The
ppunkItem or ppTypeInfo
parameter contains the pointer.
E_POINTER An invalid pointer was specified.
E_INVALIDARG An argument was invalid.
TYPE_E_ELEMENTNOTFOUND An item of the specified name
was not found.
See also IActiveScript::AddNamedItem
IActiveScriptSite::GetLCID
HRESULT GetLCID (
LCID *plcid // address of variable for language identifier
);
Retrieves the locale identifier associated with the host's user interface. The scripting engine uses the identifier to ensure that error strings and other user-interface elements surfaced by the engine appear in the appropriate language. If this method returns E_NOTIMPL, the system-defined locale identifier should be used. plcid [out] Address of a variable that receives the locale identifier for user-interface elements displayed by the scripting engine.
Returns
S_OK The locale identifier was successfully retrieved. The
plcid parameter contains the identifier.
E_POINTER An invalid pointer was specified.
E_NOTIMPL This method is not implemented. Use the system-defined
locale.
IActiveScriptSite::OnEnterScript HRESULT OnEnterScript (void); Informs the host that the scripting engine has begun executing the script code. The scripting engine must call this method on every entry or reentry into the scripting engine. For example, if the script calls an object that then fires an event handled by the scripting engine, the scripting engine must call OnEnterScript before executing the event, and must call OnLeaveScript after executing the event but before returning to the object that fired the event. Calls to this method can be nested. Every call to OnEnterScript requires a corresponding call to OnLeaveScript. See also IActiveScriptSite::OnLeaveScript IActiveScriptSite::OnLeaveScript HRESULT IActiveScriptSite::OnLeaveScript (void); Informs the host that the scripting engine has returned from executing script code. The scripting engine must call this method before returning control to a caller that entered the scripting engine. For example, if the script calls an object that then fires an event handled by the scripting engine, the scripting engine must call OnEnterScript before executing the event, and must call OnLeaveScript after executing the event before returning to the object that fired the event. Calls to this method can be nested. Every call to OnEnterScript requires a corresponding call to OnLeaveScript.
Returns
S_OK The method was successful.
See also IActiveScriptSite::OnEnterScript
IActiveScriptSite::OnScriptError
HRESULT IActiveScriptSite::OnScriptError (
IActiveScriptError*pase // address of error interface
);
Informs the host that an execution error occurred while the engine was running the script. pase [in] Address of the error object's IActiveScriptError interface. A host can use this interface to obtain information about the execution error.
Returns
S_OK The scripting engine should continue running the script as
best as possible (perhaps abandoning the processing of this
event).
S_FALSE The scripting engine should continue running the script in
the debugger, if a debugger is available. If a debugger
is not available, this error should be handled in the same
way as E_FAIL.
E_FAIL The scripting engine should abort execution of the script
and return it to the initialized state. In this
case, the pexcepinfo parameter obtained from
IActiveScriptError::GetExceptionInfo
is generally passed to On ScriptTerminate.
See also IActiveScriptError, IActiveScriptError::GetExceptionInfo
IActiveScriptSite::OnScriptTerminate
HRESULT OnScriptTerminate (
VARIANT *pvarResult, // address of script results
EXCEPINFO *pexcepinfo // address of structure with exception
information
);
Informs the host that the script has completed execution. pvarResult [in] Address of a variable that contains the script result, or NULL if the script produced no result. pexcepinfo [in] Address of an EXCEPINFO structure that contains exception information generated when the script terminated, or NULL if no exception was generated. The scripting engine calls this method before the call to OnStateChange(SCRIPTSTATE_INITIALIZED) is completed. The OnScriptTerminate method can be used to return completion status and results to the host. Note that many script languages, which are based on sinking events from the host, have life spans that are defined by the host. In this case, this method may never be called.
Returns
S_OK The method succeeded.
Returns
S_OK The method succeeded.
Informs the host that the scripting engine has changed states. ssScriptState [in] Value that indicates the new script state. See IActiveScript::GetScriptState for a description of the states.
Returns
S_OK The method succeeded.
See also IActiveScript::GetScriptState IActiveScriptSiteWindow This interface is implemented by hosts that support a user interface on the same object as IActiveScriptSite. Hosts that do not support a user interface, such as servers, would not implement the IActiveScriptSiteWindow interface. The scripting engine accesses this interface by calling Queryinterface from IActiveScriptSite.
Methods in Vtable Order
IUnknown methods Description
QueryInterface Returns pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IActiveScriptSiteWindow methods Description
GetWindow Retrieves the window handle that can
act as the owner of a pop-up window
that the scripting engine needs to
| ||||||