Primary Dual Interface for USB Verification Script Engine | Protocol Solutions User Documentation

IVScriptEngine interface

The IVScriptEngine interface is the primary dual interface for the UsbVScriptEngine object. It implements the common functionality for the Teledyne LeCroy PSG verification script engine (VSE). The main advantage of the IVScriptEngine interface is that it allows clients to implement the _IVScriptEngineEvents callback interface to receive notifications when a verification script is running.

IID: 67FC41C6-0FEE-4b95-8EE0-A5724661FE98

IVScriptEngine::VscriptName

C++

[propget] HRESULT VScriptName([out, retval] BSTR *pVal);
	[propput] HRESULT VScriptName([in] BSTR newVal);

Property putting and getting current verification script name.

Parameters
*pVal	Address of variable in which to store current verification script name
newVal	Name of the verification script to initialize script verification engine

Remarks

The name of the verification script is the name of the verification script file (*.vse).

Example: C++

C++

       // In this example, use wrapper functions provided by #import directive.

	IUsbTrace* usb_trace;

	. . . 

	IUsbVerificationScript* usb_vscript = NULL;

usb_trace->QueryInterface( IID_ IUsbVerificationScript, (void**)&usb_vscript ) )

	assert( usb_vscript != NULL );

IVScriptEngine* usb_vsengine = NULL;

usb_vsengine = usb_vscript -> GetVScriptEngine(ScriptName);

usb_vsengine -> put_VScriptName(Test_1);

assert( usb_vsengine -> GetVScriptName() == Test_1 );

VS_RESULT result = usb_vsengine ->RunVScript();

if( result == PASSED )

{

     ::MessageBox( NULL, "Test 1 passed !!!", "UsbAnalyzer client", MB_OK );

        }

	. . .

IVScriptEngine::Tag

C++

[propget] HRESULT Tag([out, retval] int* pVal);
	[propput] HRESULT Tag([in] int newVal);

Property assigning and getting a tag to the VSE object. This tag is used in event notifications, allowing a client event handler to determine which VSE object sent the event.

Parameters
*pVal	Address of variable in which to store current VSE tag.
newVal	New tag for VSE.

Example: C++

C++

       // In this example, use wrapper functions provided by the #import directive.

	IUsbTrace* usb_trace;

	. . . 

	IUsbVerificationScript* usb_vscript = NULL;

usb_trace->QueryInterface( IID_ IUsbVerificationScript, (void**)&usb_vscript ) )

	assert( usb_vscript != NULL );

IVScriptEngine* usb_vsengine = NULL;

usb_vsengine = usb_vscript -> GetVScriptEngine(ScriptName);

usb_vsengine ->put_Tag( 0xDDAADDAA );

assert( usb_vsengine -> GetTag() == 0xDDAADDAA );

VS_RESULT result = usb_vsengine ->RunVScript();

if( result == PASSED )

{

    ::MessageBox( NULL, "Test 1 passed !!!", "UsbAnalyzer client", MB_OK );

        }

	. . .

IVScriptEngine::RunVScript

C++

HRESULT RunVScript([out, retval] int* pResult);

Runs verification script.

Parameters
pResult	Address of variable in which to store the result of verification. See IUsbVerificationScript::RunVScript method for details.

Remarks

This method makes a synchronous call and does not return until the script stops running.

Example: C++

See C++ example for VScriptName.

IVScriptEngine::RunVScriptEx

C++

HRESULT RunVScriptEx([in] BSTR script_name, 
                     [out, retval] int* pResult);

Changes the current verification script name and runs verification script.

Parameters
script_name	Name of the verification script to initialize script verification engine.
PResult	Address of variable in which to store the result of verification. See IUsbVerificationScript::RunVScript for details.

Remarks

This method makes a synchronous call and does not return until the script stops running.

Example: C++

C++

       // In this example, use wrapper functions provided by #import directive.

	IUwbTrace* usb_trace;

	. . . 

	IUsbVerificationScript* usb_vscript = NULL;

usb_trace->QueryInterface( IID_ IUsbVerificationScript, (void**)&usb_vscript ) )

	assert( usb_vscript != NULL );

IVScriptEngine* usb_vsengine = NULL;

usb_vsengine = usb_vscript -> GetVScriptEngine(ScriptName);

VS_RESULT result = usb_vsengine ->RunVScript();

if( result == PASSED )

{

::MessageBox( NULL, "Test 1 passed !!!", "UsbAnalyzer client", MB_OK );

}

result = usb_vsengine ->RunVScriptEx(Test_2);

if( result == PASSED )

{

::MessageBox( NULL, "Test 2 passed !!!", "UsbAnalyzer client", MB_OK );

}

result = usb_vsengine ->RunVScriptEx(Test_3);

if( result == PASSED )

{

::MessageBox( NULL, "Test 3 passed !!!", "UsbAnalyzer client", MB_OK );

}

	. . .

IVScriptEngine::LaunchVScript

C++

HRESULT LaunchVScript();

Launches verification script.

Return Values
S_FALSE	If VS Engine was not successfully launched (either it is already running or the verification script was not found).

Remarks

This method makes an asynchronous call and immediately returns after the script starts running.

When the verification script stops running, the VSE object sends a special event notification “OnVScriptFinished” to the client event handler. You can also terminate script running using the method “Stop”.

Example: C++

C++

       // In this example, use wrapper functions provided by #import directive.

	IUsbTrace* usb_trace;

	. . . 

	IUsbVerificationScript* usb_vscript = NULL;

usb_trace->QueryInterface( IID_ IUsbVerificationScript, (void**)&usb_vscript ) )

	assert( usb_vscript != NULL );

IVScriptEngine* usb_vsengine = NULL;

usb_vsengine = usb_vscript -> GetVScriptEngine(ScriptName);

assert( usb_vsengine != NULL );

VS_RESULT result = usb_vsengine ->LaunchVScript();

// You can go further without waiting for the result from the VSE object.

// If you are interested in the result, implement the client event handler for 

// OnVScriptFinished() notification.

	. . .

IVScriptEngine::Stop

C++

HRESULT Stop();

Stops verification script previously launched by the IVScriptEngine::LaunchVScript method.

Example: C++

C++

       // In this example, use wrapper functions provided by the #import directive.

	IUsbTrace* usb_trace;

	. . . 

	IUsbVerificationScript* usb_vscript = NULL;

usb_trace->QueryInterface( IID_ IUsbVerificationScript, (void**)&usb_vscript ) )

	assert( usb_vscript != NULL );

IVScriptEngine* usb_vsengine = NULL;

usb_vsengine = usb_vscript -> GetVScriptEngine(ScriptName);

VS_RESULT result = usb_vsengine ->LaunchVScript();

	. . . 

	if( NotEnoughResourcesToProcessVS )

		usb_vsengine ->Stop();

	. . .

IVScriptEngine::GetScriptVar

C++

HRESULT GetScriptVar ( [in] BSTR var_name, 
                       [out, retval] VARIANT* var_value )

Returns the value of some verification script variable before/after executing the script. The resulting value may contain an integer, a string, or an array of VARIANTs (if the requested script variable is a list object, see the CSL Manual for more details about list objects).

Parameters
var_name	String providing the name of the global variable or constant used in the running verification script.
var_value	Address of a VARIANT variable in which result will be stored.

Return values
E_PENDING	If this method is called when script running is in progress.

Remarks

If there is no such global variable or constant with the name 'var_name', the resulting value contains an empty VARIANT.

Example: C++

C++

       // In this example, use wrapper functions provided by the #import directive.

	IUsbTrace* usb_trace;

	. . . 

	IUsbVerificationScript* usb_vscript = NULL;

usb_trace->QueryInterface( IID_ IUsbVerificationScript, (void**)&usb_vscript ) )

	assert( usb_vscript != NULL );

IVScriptEngine* usb_vsengine = NULL;

usb_vsengine = usb_vscript -> GetVScriptEngine(ScriptName);

VS_RESULT result = usb_vsengine ->RunVScript();

	. . . 

	VARIANT my_var; 

	VariantInit( &my_var );

	

	usb_vsengine->GetScriptVar( _bstr_t("MyVar"), &my_var );

	if( my_var.vt == VT_BSTR ) ProcessString( my_var.bstrVal );

	. . .

Example: WSH

Visual Basic

        . . .

	Set Trace    = Analyzer.OpenFile( TraceName )    ' Open the trace.

Set VSEngine = Trace.GetVScriptEngine(ScriptName) ' Get VS Engine object.

	Result = VSEngine.RunVScript

	

	MyIntVar = VSEngine.GetScriptVar( "MyIntVar" ) ' Suppose MyVar contains an integer

	MyStrVar = VSEngine.GetScriptVar( "MyStrVar" ) ' Suppose MyVar contains a string.

	MsgBox " MyIntVar = " & CStr(MyIntVar) & ", MyStrVar = " & MyStrVar

IVScriptEngine::SetScriptVar

C++

HRESULT SetScriptVar ( [in] BSTR var_name, 
                       [in] VARIANT var_value )

Allows you to set the value of some verification script variable before executing the script. Only integers, strings, or arrays of VARIANTs are allowed. Arrays of VARIANTs are converted into list values inside of scripts (see the CSL Manual for more details about list objects).

Parameters
var_name	String providing the name of the global variable used in the running verification script.
var_value	VARIANT value containing new variable value.

Return values
E_PENDING	If this method is called when script running is in progress.

Remarks

This function allows you to set internal script variables before/after script run, so you can make run-time customizations from COM/Automation client applications.

If there is no such global variable with the name 'var_name', a new variable with that name is created.

Example: C++

C++

       // In this example, use wrapper functions provided by #import directive.

	IUsbTrace* usb_trace;

	. . . 

	IUsbVerificationScript* usb_vscript = NULL;

usb_trace->QueryInterface( IID_ IUsbVerificationScript, (void**)&usb_vscript ) )

	assert( usb_vscript != NULL );

IVScriptEngine* usb_vsengine = NULL;

usb_vsengine = usb_vscript -> GetVScriptEngine(ScriptName);

VARIANT my_var; 

VariantInit( &my_var );

my_var.vt = VT_I4; // Integer

my_var.lVal = 100; 

// Set internal script variable 'MyVar' to 100.

usb_vsengine->SetScriptVar( _bstr_t("MyVar"), my_var ); 

VS_RESULT result = usb_vsengine ->RunVScript(); 

	. . .

Example: WSH

Visual Basic

        . . .

	Set Trace    = Analyzer.OpenFile( TraceName )    ' Open the trace.

Set VSEngine = Trace.GetVScriptEngine(ScriptName) ' Get VS Engine object.

	VSEngine.SetScriptVar( "MyIntVar" , 100 )

	VSEngine.SetScriptVar( "MyStrVar" , "Hello !!!" )

	Result = VSEngine.RunVScript