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

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_PTR 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
);

Parameters

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:

Return 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_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 is to 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.

Expand imageReturn Value

Expand imageSee Also