Teledyne SAS-SATA User Manual

Download

Protocol Solutions Group

3385 Scott Blvd. Santa Clara, CA 95054 Tel: +1/408.727.6600 Fax: +1/408.727.6622

Automation API

for

LeCroy SAS/SATA Tracer/Trainer

Reference Manual

Manual Version 1.11

For SAS/SATA Tracer/Trainer Software Version 2.60/4.60

May 2010

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

Document Disclaimer

The information contained in this document has been carefully checked and is believed to be reliable. However, no responsibility can be assumed for inaccuracies that may not have been detected.

LeCroy reserves the right to revise the information presented in this document without notice or penalty.

Trademarks and Servicemarks

LeCroy, CATC, SASTracer, SATracer, SASTrainer, SATrainer Automation are trademarks of LeCroy Corporation.

Microsoft and Windows are registered trademarks of Microsoft Inc.

All other trademarks are property of their respective companies.

Copyright

This document may be printed and reproduced without additional permission, but all copies should contain this copyright notice.

Version

This is version 1.11 of the SASTracer/SATracer Automation API Reference Manual. This manual applies to SASTracer/SATracer software version 2.60/4.60 and higher.

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

1 Introduction...........................................................................5

1.1 System Requirements................................................................5

1.2 Support Resources ....................................................................5

1.3 Setting Up Automation for Local Use.........................................5

1.4 Setting Up Automation for Remote Use.....................................5

2 SASTracer/SATracer Object Model .......................................6

3 SASAnalyzer Object............................................................... 8

3.1 ISASAnalyzer Interface..............................................................9

3.1.1 ISASAnalyzer::GetVersion.............................................................................................10

3.1.2 ISASAnalyzer::OpenFile ................................................................................................11

3.1.3 ISASAnalyzer::StartGeneration......................................................................................12

3.1.4 ISASAnalyzer::StopGeneration......................................................................................15

3.1.5 ISASAnalyzer::StartRecording.......................................................................................16

3.1.6 ISASAnalyzer::StopRecording.......................................................................................18

3.1.7 ISASAnalyzer::MakeRecording......................................................................................19

3.1.8 ISASAnalyzer::LoadDisplayOptions...............................................................................20

3.1.9 ISASAnalyzer::GetRecordingOptions............................................................................21

3.1.10 ISASAnalyzer::ResumeGeneration...............................................................................22

3.1.11 ISASAnalyzer::Attach....................................................................................................23

3.1.12 ISASAnalyzer::Detach...................................................................................................24

4 SASTrace Object ................................................................25

4.1 ITrace Interface........................................................................26

4.1.1 ITrace::GetName............................................................................................................27

4.1.2 ITrace::ApplyDisplayOptions..........................................................................................28

4.1.3 ITrace::Save...................................................................................................................29

4.1.4 ITrace::ExportToText .....................................................................................................30

4.1.5 ITrace::Close..................................................................................................................32

4.1.6 ITrace::ReportFileInfo ....................................................................................................33

4.1.7 ITrace::ReportErrorSummary.........................................................................................34

4.1.8 ITrace::GetPacket..........................................................................................................37

4.1.9 ITrace::GetPacketsCount...............................................................................................40

4.1.10 ITrace::GetTriggerPacketNum......................................................................................41

4.1.11 ITrace::AnalyzerErrors ..................................................................................................42

4.2 ISASTrace Interface.................................................................43

4.2.1 ISASTrace::GetBusPacket.............................................................................................43

4.3 ISASVerificationScript Interface...............................................44

4.3.1 ISASVerificationScript::RunVerificationScript................................................................45

4.3.2 ISASVerificationScript:: GetVScriptEngine....................................................................47

iii

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

5 SASRecOptions Object......................................................48

5.1 IRecOptions Interface ..............................................................49

5.1.1 IRecOptions::Load .........................................................................................................50

5.1.2 IRecOptions::Save.........................................................................................................51

5.1.3 IRecOptions::SetRecMode.............................................................................................52

5.1.4 IRecOptions::SetBufferSize ...........................................................................................53

5.1.5 IRecOptions::SetPostTriggerPercentage.......................................................................54

5.1.6 IRecOptions::SetTriggerBeep........................................................................................55

5.1.7 IRecOptions::SetSaveExternalSignals...........................................................................56

5.1.8 IRecOptions::SetTraceFileName ...................................................................................57

5.1.9 IRecOptions::Reset........................................................................................................58

5.2 ISASRecOptions Interface.......................................................59

6 SASPacket Object ..............................................................60

6.1 IPacket Interface......................................................................61

6.1.1 IPacket::GetTimestamp..................................................................................................61

6.2 ISASPacket Interface...............................................................62

6.2.1 IPacket::GetPacketData.................................................................................................62

6.2.2 IPacket::GetDirection.....................................................................................................65

6.2.3 IPacket::GetErrors..........................................................................................................66

7 SASTraceErrors Object .....................................................67

7.1 ISASAnalyzerErrors Dispinterface...........................................67

7.1.1 ISASAnalyzerErrors::get_Item.......................................................................................68

7.1.2 ISASAnalyzerErrors::get_Count ....................................................................................69

8 SASVScriptEngine Object .................................................71

8.1 IVScriptEngine Interface ..........................................................71

8.1.1 IVScriptEngine::VScriptName........................................................................................72

8.1.2 IVScriptEngine::Tag.......................................................................................................73

8.1.3 IVScriptEngine::RunVScript...........................................................................................74

8.1.4 IVScriptEngine::RunVScriptEx.......................................................................................75

8.1.5 IVScriptEngine::LaunchVScript......................................................................................76

8.1.6 IVScriptEngine::Stop......................................................................................................77

8.1.7 IVScriptEngine::GetScriptVar.........................................................................................78

8.1.8 IVScriptEngine::SetScriptVar.........................................................................................80

9 SASVScriptEngine Object Events ....................................82

9.1 _IVScriptEngineEvents Interface .............................................82

9.1.1 IVScriptEngineEvents::OnVScriptReportUpdated .........................................................85

9.1.2 IVScriptEngineEvents::OnVScriptFinished....................................................................86

9.1.3 IVScriptEngineEvents::OnNotifyCount...........................................................................87

10 SASAnalyzer Object Events..............................................89

10.1 _ISASAnalyzerEvents Dispinterface .....................................89

10.1.1 _ISASAnalyzerEvents::OnTraceCreated......................................................................90

10.1.2 _ISASAnalyzerEvents::OnStatusReport.......................................................................91

1 Introduction

LeCroy’s SASTracer/SATracer software provides a rich, functional COM/Automation API to the most important functionalities of the LeCroy SASTracer/SATracer Protocol Analyzer and LeCroy SASTrainer/SATrainer Exerciser. This makes it a great tool for implementation of automated programs for complicated testing, development and debugging. The "dual" nature of the interfaces provided makes it easy to use the SASTracer/SATracer COM API in different Integrated Development Environments (IDE) supporting the COM architecture.

Special support for typeless script languages (such as VB and JavaScript), while overri ding some restrictions imposed by script engines (remote access, dynamic object creation, and handling events), allows you to write client applications quickly and easily. You do not need significant programming skills. or installation of expensive and powerful programming language systems. All these features, along with the ability to set up all necessary DCOM permissions during the installation process, make the LeCroy SASTracer/SATracer an attractive tool for automating and speeding many engineering processes.

1.1 System Requirements

The Automation API was introduced with the following release: SASTracer/SATracer software 2.60/4.60.

This document covers the functionality available in SASTracer/SATracer 2.60/4.60.

1.2 Support Resources

As new functionalities are added to the API, not all of them are supported by older versions of the analyzer's software. For newer releases of analyzer software, please refer to the LeCroy web site: www.lecroy.com

1.3 Setting Up Automation for Local Use

To run Automation on the SASTracer/SATracer's Host Controller (the PC attached to the SASTracer/SATracer), you do not need to perform any special configuration. You can simply execute the scripts or programs that you have created and they will run the analyzer. In order to use the SASTracer/SATracer COM API, during the installation process the application should be registered as a COM server in a system registry.

1.4 Setting Up Automation for Remote Use

To access SASTracer/SATracer remotely over a network, install the SASTracer/SATracer application on both server and client systems and accept the Enabling Remote Access option during installation. You can also perform a manual DCOM configuration.

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

2 SASTracer/SATracer Object Model

LeCroy’s SASTracer/SATracer API programmatically exposes its functionality through objects. You work with an object by using its properties and methods. Objects are named according to the portion of an application they represent, and they are ordered in a hierarchy.

A single object occupies the topmost tier of LeCroy SASTracer/SATracer object hierarchy: SASAnalyzer.

The following object model diagram shows how the objects in an object model fit together:

Only the SASAnalyzer object is creatable at the top level (for instance, via the CoCreateInstance call from a C/C++ client). Instantiation of an object of other classes requires API calls.

The Class ID and App ID for the SASAnalyzer object are the following.

Class ID: SASAnalyzer 12A4B62B-107A-42AE-9C56-08C5EC3C26E2

AppID: SASAnalyzer Lecroy.SASAnalyzer

All interfaces are dual interfaces that allow simple use from typeless languages (like VBScript), as well as from C/C++.

All objects implement the ISupportErrorInfo interface for easy error handling from the client.

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

Objects Interfaces Description

SASAnalyzer ISASAnalyzer

_ISASAnalyzerEvents

SASTrace ITrace

ISASTrace* ISASVerificationScript*

SASRecOptions IRecOptions

ISASRecOptions

SASPacket IPacket

ISASPacket*

SASTraceErrors ISASAnalyzerErrors*

* Primary interfaces The examples of C++ code given in this document assume using the “import” technique of

creating COM clients. That means the corresponding include is used:

#import "SASAutomation.tlb" no_namespace named_guids

Appropriate wrapper classes are created in .tli and .tlh files by the compiler. Examples of WSH, VBScript, and C++ client applications are provided.

Represents the SASTracer application.

Represents recorded trace.

Represents recording options. Represents single packet of the recorded

trace. Represents the collection of errors that

occurred in the recorded trace.

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

3 SASAnalyzer Object

The SASAnalyzer object is the top-level object of the SASTracer API. The SASAnalyzer object allows you to control recording and traffic generation, open trace files, and access recording and generation options. The SASAnalyzer object supports the following interfaces:

Interfaces Description

ISASAnalyzer

_ISASAnalyzerEvents

The ISASAnalyzer interface is the primary interface for the SASAnalyzer object.

The Class ID and App ID for the SASAnalyzer object are the following:

Class ID SASAnalyzer 12A4B62B-107A-42AE-9C56-08C5EC3C26E2

App ID SASAnalyzer Lecroy.SASAnalyzer

Example

WSH:

Set Analyzer = WScript.CreateObject( “Lecroy.SASAnalyzer” )

C++:

ISASAnalyzer* poSASAnalyzer;

// create SASAnalyzer object if ( FAILED( CoCreateInstance(

CLSID_SASAnalyzer, NULL, CLSCTX_SERVER, IID_ISASAnalyzer, (LPVOID *)&poSASAnalyzer ) )

return;

Facilitates recording and traffic generation, opens trace files, and retrieves recording options. Adds advanced generator functionality and retrieves generation options. Events from SASAnalyzer object.

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

3.1 ISASAnalyzer Interface

The ISASAnalyzer interface is a dual interface for the SASAnalyzer object. ISASAnalyzer implements the following methods:

GetVersion OpenFile StartGeneration StopGeneration StartRecording StopRecording MakeRecording LoadDisplayOptions GetRecordingsOption ResumeGeneration Attach Detach

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

3.1.1 ISASAnalyzer::GetVersion

HRESULT GetVersion (

Retrieves the current version of the specified subsystem.

Parameters

version_type Subsystem whose version is requested

analyzer_version Version of the subsystem queried

Return value

ANALYZERCOMERROR_INVALIDVERSIONTYPE –

Remarks

Example

WSH:

Set Analyzer = WScript.CreateObject("Lecroy.SASAnalyzer") SwVersion = Analyzer.GetVersion(0) MsgBox "Software" & SwVersion

C++:

HRESULT hr; ISASAnalyzer* poSASAnalyzer;

// create SASAnalyzer object

if ( FAILED( CoCreateInstance ( CLSID_SASAnalyzer, NULL, CLSCTX_SERVER, IID_ISASAnalyzer, (LPVOID *)&poSASAnalyzer ) ) return;

WORD sw_version;

try

{

}

catch (_com_error& er)

{

}

TCHAR buffer[20];

_stprintf( buffer, _T("Software version:%X.%X"), HIBYTE(sw_version),

LOBYTE(sw_version) );

[in] EAnalyzerVersionType version_type, [out, retval] WORD* analyzer_version );

EAnalyzerVersionType enumerator has the following values:

ANALYZERVERSION_SOFTWARE ( 0 ) –

software

Specified version type is invalid.

sw_version = poAnalyzer->GetVersion( ANALYZERVERSION_SOFTWARE );

if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK ); return 1;

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

3.1.2 ISASAnalyzer::OpenFile

HRESULT OpenFile (

Opens trace file and creates the SASTrace object.

Parameters

file_name String providing the full pathname to the trace file trace Address of a pointer to the SASTrace object interface

Return values

ANALYZERCOMERROR_UNABLEOPENFILE – unable to open file

Remarks

SASTrace object is created via this method call, if call was successful.

Example

WSH:

CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.CreateObject("Lecroy.SASAnalyzer ") Set Trace = Analyzer.OpenFile (CurrentDir & "Input\errors.sat")

C++:

HRESULT hr; ISASAnalyzer* poSASAnalyzer;

// create SASAnalyzer object

if ( FAILED( CoCreateInstance( CLSID_SASAnalyzer, NULL, CLSCTX_SERVER, IID_ISASAnalyzer, (LPVOID *)&poSASAnalyzer ) ) return;

// Open trace file.

IDispatch* trace;

try

{

}

catch (_com_error& er)

{

}

// query for VTBL interface

ISASTrace* SAS_trace; hr = trace->QueryInterface( IID_ISASTrace, (LPVOID *)&SAS_trace );

trace->Release();

if( FAILED(hr) )

return;

[in] BSTR file_name, [out, retval] IDispatch** trace );

trace = poSASAnalyzer->OpenFile( m_szRecFileName );

if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK ); return 1;

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

3.1.3 ISASAnalyzer::StartGeneration

HRESULT StartGeneration (

Starts traffic generation from the file.

Parameters

gen_file_name String providing the full pathname to the generation file.

reserved1 Reserved for future use reserved2 Reserved for future use portConfig DeviceConfiguartionTypeEnum enumeration specifies functionality of

[in] BSTR gen_file_name,

[in] long reserved1

[in] long reserved2

[in] DeviceConfiguartionTypeEnum portConfig);

ports for connected board:

DEVICE_CONFIG_A_A_A_A = 1 DEVICE_CONFIG_T_T_T_T = 2 DEVICE_CONFIG_HE_HE_HE_HE = 3 DEVICE_CONFIG_DE_DE_DE_DE = 4 DEVICE_CONFIG_A_A_HE_HE = 5 DEVICE_CONFIG_A_A_DE_DE = 6 DEVICE_CONFIG_HE_HE_A_A = 7 DEVICE_CONFIG_DE_DE_A_A = 8 DEVICE_CONFIG_AHE_AHE_0_0 = 9 DEVICE_CONFIG_ADE_ADE_0_0 = 10 DEVICE_CONFIG_J_0_A_A = 11 DEVICE_CONFIG_0_J_A_A = 12 DEVICE_CONFIG_AHE_0_AHE_0 = 13 DEVICE_CONFIG_ADE_0_ADE_0 = 14 DEVICE_CONFIG_AHE_0_0_0 = 15 DEVICE_CONFIG_ADE_0_0_0 = 16 DEVICE_CONFIG_AHE_0_A_A = 17 DEVICE_CONFIG_ADE_0_A_A = 18 DEVICE_CONFIG_A_0_0_0 = 19 DEVICE_CONFIG_A_A_0_0 = 20 DEVICE_CONFIG_0_0_HE_HE = 21 DEVICE_CONFIG_HE_HE_0_0 = 22 DEVICE_CONFIG_0_0_DE_DE = 23 DEVICE_CONFIG_DE_DE_0_0 = 24 DEVICE_CONFIG_0_0_AJA_0 = 25 DEVICE_CONFIG_0_0_0_AJA = 26 DEVICE_CONFIG_0_0_JA_0 = 27 DEVICE_CONFIG_0_0_0_JA = 28 DEVICE_CONFIG_J_0_HE_HE = 29 DEVICE_CONFIG_0_J_HE_HE = 30 DEVICE_CONFIG_HE_HE_J_0 = 31 DEVICE_CONFIG_HE_HE_0_J = 32 DEVICE_CONFIG_J_0_AHE_0 = 33 DEVICE_CONFIG_J_0_DE_DE = 34 DEVICE_CONFIG_0_J_DE_DE = 35 DEVICE_CONFIG_DE_DE_J_0 = 36

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

DEVICE_CONFIG_DE_DE_0_J = 37 DEVICE_CONFIG_J_0_ADE_0 = 38 DEVICE_CONFIG_AHE_0_J_0 = 39 DEVICE_CONFIG_ADE_0_J_0 = 40 DEVICE_CONFIG_HE_0_0_0 = 41 DEVICE_CONFIG_DE_0_0_0 = 42 DEVICE_CONFIG_HE_0_J_0 = 43 DEVICE_CONFIG_DE_0_J_0 = 44 DEVICE_CONFIG_J_J_A_A = 45 DEVICE_CONFIG_AJA_0_0_0 = 46 DEVICE_CONFIG_0_AJA_0_0 = 47 DEVICE_CONFIG_JA_0_0_0 = 48 DEVICE_CONFIG_0_JA_0_0 = 49 DEVICE_CONFIG_A_A_J_0 = 50 DEVICE_CONFIG_A_A_0_J = 51 DEVICE_CONFIG_J_J_J_J = 52 DEVICE_CONFIG_A_A_J_J = 53 DEVICE_CONFIG_JA_JA_0_0 = 54 DEVICE_CONFIG_0_0_JA_JA = 55 DEVICE_CONFIG_J_J_HE_HE = 56 DEVICE_CONFIG_HE_HE_J_J = 57 DEVICE_CONFIG_J_J_DE_DE = 58 DEVICE_CONFIG_DE_DE_J_J = 59 DEVICE_CONFIG_AHE_0_J_J = 60 DEVICE_CONFIG_J_J_AHE_0 = 61 DEVICE_CONFIG_ADE_0_J_J = 62 DEVICE_CONFIG_J_J_ADE_0 = 63 DEVICE_CONFIG_J_0_0_0 = 64 DEVICE_CONFIG_0_J_0_0 = 65 DEVICE_CONFIG_0_0_J_0 = 66 DEVICE_CONFIG_0_0_0_J = 67 DEVICE_CONFIG_J_J_0_0 = 68 DEVICE_CONFIG_0_0_J_J = 69 DEVICE_CONFIG_T_0_T_0 = 70 DEVICE_CONFIG_0_T_0_T = 71 DEVICE_CONFIG_AT_0_0_0 = 72 DEVICE_CONFIG_0_AT_0_0 = 73 DEVICE_CONFIG_0_0_AT_0 = 74 DEVICE_CONFIG_0_0_0_AT = 75 DEVICE_CONFIG_T_0_A_A = 76 DEVICE_CONFIG_0_T_A_A = 77 DEVICE_CONFIG_A_A_T_0 = 78 DEVICE_CONFIG_A_A_0_T = 79 DEVICE_CONFIG_TJ_0_0_0 = 80 DEVICE_CONFIG_0_TJ_0_0 = 81 DEVICE_CONFIG_0_0_TJ_0 = 82 DEVICE_CONFIG_0_0_0_TJ = 83 DEVICE_CONFIG_0_0_AHE_AHE = 84 DEVICE_CONFIG_0_0_0_0 = 85

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

Return values

ANALYZERCOMERROR_UNABLEOPENFILE – ANALYZERCOMERROR_UNABLESTARTGENERATION – unable to start generation (invalid state, etc.)

unable to open file

Remarks Example

WSH:

CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\”)) Set Analyzer = WScript.CreateObject( “Lecroy.SASAnalyzer” ) ret = Analyzer.StartGeneration( CurrentDir & "Input\connect.ssg", 0, 0 )

C++:

HRESULT hr; ISASAnalyzer* poSASAnalyzer; TCHAR m_szGenFileName [_MAX_PATH];

// Create SASAnalyzer object. if ( FAILED( CoCreateInstance(

return;

. . .

try {

} catch (_com_error& er) {

}

CLSID_SASAnalyzer,

NULL, CLSCTX_SERVER,

IID_ISASAnalyzer,

(LPVOID *)&poSASAnalyzer ) )

poAnalyzer->StartGeneration( m_szGenFileName, 0, 0 );

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK );

return 1;

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

3.1.4 ISASAnalyzer::StopGeneration

HRESULT StopGeneration ( );

Stops any generation in progress.

Parameters

Return values

ANALYZERCOMERROR_UNABLESTARTGENERATION –

Remarks

Example

C++:

ISASAnalyzer* poAnalyzer;

. . .

try

{

poAnalyzer->StopGeneration(); } catch (_com_error& er) {

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK );

return 1; }

unable to stop generation (invalid state, etc.)

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

3.1.5 ISASAnalyzer::StartRecording

HRESULT StartRecording (

Starts recording with specified recording options.

Parameters

ro_file_name String providing the full pathname to the recording options file;

Return values

ANALYZERCOMERROR_UNABLESTARTRECORDING -

Remarks

After recording starts, this function will return. The Analyzer continues recording until it is finished or until the StopRecording method call is performed. During recording, events are sent to the event sink (see _ISASAnalyzerEvents

The recording options file is the file with extension .rec created by the SASTracer application. You can create this file when you select “Setup –> Recording Options…” from the SASTracer application menu, change the recording options in the “Recording Options” dialog, and select the “Save…” button.

Example

VBScript:

<OBJECT

</OBJECT>

<!--

Sub BtnStartRecording_OnClick

On Error Resume Next Analyzer.StartRecording TextRecOptions.value If Err.Number <> 0 Then MsgBox Err.Number & ":" & Err.Description End If

-->

</SCRIPT>

[in] BSTR ro_file_name );

If the parameter is omitted, then recording starts with default recording options.

unable to start recording

interface).

RUNAT=Server ID = Analyzer CLASSID = " clsid: 297CD804-08F5-4A4F-B3BA-779B2654B27C "

End Sub

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

C++:

ISASAnalyzer* sas_analyzer; BSTR ro_file_name;

. . .

try {

} catch (_com_error& er) {

return 1; }

sas_analyzer->StartRecording( ro_file_name )

if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK );

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

3.1.6 ISASAnalyzer::StopRecording

HRESULT StopRecording (

Stops recording started by the ISASAnalyzer::StartRecording

Parameters

abort_upload TRUE, if the caller wants to abort the upload. No tra ce file is created.

Return values

ANALYZERCOMERROR_UNABLESTOPRECORDING -

Remarks

Stops recording started by the StartRecording method. The event is issued when

recording is actually stopped (by the ISASAnalyzer

call was FALSE.

Example (for SASTracer)

VBScript:

<OBJECT

</OBJECT>

<!--

Sub BtnStopRecording_OnClick

On Error Resume Next Analyzer.StopRecording True If Err.Number <> 0 Then MsgBox Err.Number & ":" & Err.Description End If End Sub

-->

</SCRIPT>

C++:

ISASAnalyzer* sas_analyzer;

. . .

try

{

}

catch (_com_error& er)

{

}

[in] BOOL abort_upload );

method.

FALSE, if the caller want to upload the recorded trace.

error stopping recording

interface), if the parameter of method

RUNAT=Server ID = Analyzer CLASSID = "clsid: 0B179BB7-DC61-11d4-9B71-000102566088"

sas_analyzer->StopRecording( FALSE )

if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK ); return 1;

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

3.1.7 ISASAnalyzer::MakeRecording

HRESULT MakeRecording (

Makes recording with the specified recording options file.

Parameters

ro_file_name String providing the full pathname to a recording options file;

trace Address of a pointer to the SASTrace object interface

Return values

ANALYZERCOMERROR_UNABLESTARTRECORDING -

Remarks

This method acts like the StartRecording method but will not return until recording is completed. The SASTrace object is created via this method call, if the call was successful.

Example

WSH:

CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.CreateObject("Lecroy.SASAnalyzer") Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec")

C++:

IDispatch* trace; ISASAnalyzer* sas_analyzer; BSTR ro_file_name; HRESULT hr;

. . . try {

} catch (_com_error& er) {

}

// query for VTBL interface

ISASTrace* sas_trace;

hr = trace->QueryInterface( IID_ISASTrace, (LPVOID *)&sas_trace );

trace->Release();

[in] BSTR ro_file_name, [out, retval] IDispatch** trace );

If the parameter is omitted, recording starts with default recording options.

unable to start recording

trace = sas_analyzer->MakeRecording( ro_file_name )

if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK ); return 1;

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

3.1.8 ISASAnalyzer::LoadDisplayOptions

HRESULT LoadDisplayOptions (

Loads display options that will apply to a trace opened or recorded later.

Parameters

do_file_name String providing the full pathname to display options file

do_layers Specifies the mask layer of packet view, which can be a

combination of these values:

Return values

ANALYZERCOMERROR_UNABLELOADDO

Remarks

Use this method if you want to filter traffic of some type. The display options loaded by

this method call apply only on trace files opened or recorded after this call.

The display options file is the file with extension .opt created by the SASTrainer

application.

Example

See ITrace::ApplyDisplayOptions.

[in] BSTR do_file_name [in] short do_layers );

LAYER_LINK LAYER_IDLE LAYER_TRANSPORT LAYER_ATA_COMMAND LAYER_SCSI_COMMAND LAYER_SMP_COMMAND LAYER_TASK_COMMAND LAYER_DATA_REPORT LAYER_QUEUE_COMMAND LAYER_OOB_SEQUENCE

- unable to load the display options file

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

3.1.9 ISASAnalyzer::GetRecordingOptions

HRESULT GetRecordingOptions (

Retrieves the interface for access to the recording options.

Parameters

recording_options Address of a pointer to the SASRecOptions object interface

Return values

Remarks

The SASRecOptions object is created via this method call, if the call was successful.

Example

WSH:

Set Analyzer = WScript.CreateObject("Lecroy.SASAnalyzer") Set RecOptions = Analyzer.GetRecordingOptions

C++:

HRESULT hr; ISASAnalyzer* poSASAnalyzer;

// Create SASAnalyzer object.

if ( FAILED( CoCreateInstance( CLSID_SASAnalyzer, NULL, CLSCTX_SERVER, IID_ISASAnalyzer, (LPVOID *)&poSASAnalyzer ) ) return;

// Open trace file.

IDispatch* rec_opt;

try

{

}

catch (_com_error& er)

{

}

// query for VTBL interface

ISASRecOptions* ib_rec_opt; hr = rec_opt->QueryInterface( IID_ISASRecOptions, (LPVOID *)&ib_rec_opt );

rec_opt->Release();

if( FAILED(hr) )

return;

[out, retval] IDispatch** recording_options );

rec_opt = poSASAnalyzer->GetRecordingOptions();

if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK ); return 1;

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

3.1.10 ISASAnalyzer::ResumeGeneration

HRESULT ResumeGeneration ( )

Resumes generation if it was previously paused.

Return values Remarks Example

C++:

ISASAnalyzer* poAnalyzer;

. . .

try {

} catch (_com_error& er) {

}

poAnalyzer->ResumeGeneration();

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK );

return 1;

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

3.1.11 ISASAnalyzer::Attach

HRESULT Attach ( ) [in] BYTE yDefaultPort, [in] BSTR bstrDeviceId, [in] BSTR bstrSystemPath,

Attaches the SASAnalyzer object to the board and lets it work with connected boards.

Parameters

yDefaultPort An enumeration indicates a TCP or USB connection. bstrDeviceId A BSTR object specifies the Board ID as a string. bstrSystemPath Specifies the path of the system folder in which the software has been

installed. pnErrorCode A pointer to an integer which contains an error code about the situation

Return values

Remarks

This function is used to connect to a board. This function will not connect to the specified board if any other objects have been already connected to the same board.

[out, retval] int* pnErrorCode)

in which one or more error(s) has occurred.

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

3.1.12 ISASAnalyzer::Detach

HRESULT Detach ( [out, retval] int* pnErrorCode)

Detaches the object from the board.

Parameters

pnErrorCode A pointer to an integer which contains an error code about the situation in which one or more error(s) has occurred.

Return values

Remarks

This method detaches the object from the board.

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

4 SASTrace Object

The SASTrace object represents the recorded trace file. The SASTrace object allows users to:

o Get trace information. o Access trace packets. o Access trace errors. o Save/export the trace or a portion of the trace.

The SASTrace object can be created by:

o Using the ISASAnalyzer::OpenFile o Using the ISASAnalyzer::MakeRecording o Handling the _ISASAnalyzerEvents::OnTraceCreated

The SASTrace object supports the following interfaces:

Interfaces Description

Itrace

ISASTrace

ISASVerificationScript

The ISASTrace interface is a primary interface for the SASTrace object.

Implements trace packets and trace errors access, different report types, export, and saving.

Extends ITrace interface: Adds functionality for accessing the SASTracePacket object. Exposes functionality for running verification scripts.

method

event

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

4.1 ITrace Interface

The ITrace interface is a dual interface for the SASTrace object. It implements the following methods:

GetName ApplyDisplayOptions Save ExportToText Close ReportFileInfo ReportErrorSummary GetPacket GetPacketsCount GetTriggerPacketNum AnalyzerErrors

Note: All methods of the ITrace interface are also available in ISASTrace

interface.

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

4.1.1 ITrace::GetName

HRESULT GetName (

Retrieves the trace name.

Parameters

trace_name Name of the trace

Return values

Remarks

This name can be used for presentation purposes.

Do not forget to free the string returned by this method call. Example

WSH:

Set Analyzer = WScript.CreateObject("Lecroy.SASAnalyzer ")

CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))

Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec")

MsgBox “Trace name “ & Trace.GetName

C++:

ISASTrace* sas_trace;

. . .

_bstr_t bstr_trace_name;

try {

}

catch (_com_error& er)

{

}

TCHAR str_trace_name[256]; _tcscpy( str_trace_name, (TCHAR*)( bstr_trace_name) ); SysFreeString( bstr_trace_name );

::MessageBox( NULL, str_trace_name, _T("Trace name"), MB_OK );

[out, retval] BSTR* trace_name );

bstr_trace_name = sas_trace->GetName();

if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK); else ::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK); return 1;

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

4.1.2 ITrace::ApplyDisplayOptions

HRESULT ApplyDisplayOptions (

Applies the specified display options to the trace.

Parameters

do_file_name String providing the full pathname to the display options file

Return values

ANALYZERCOMERROR_UNABLELOADDO -

Remarks

Use this method if you want to filter traffic of some type in the recorded or opened trace. The display options file is the file with extension .opt created by the SASTrainer

application.

Note: This does not work on Multisegment traces.

Example

WSH:

Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer") CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec") Trace.ApplyDisplayOptions CurrentDir & "Input\test_do.opt" Trace.Save CurrentDir & "Output\saved_file.sat"

C++:

ISASTrace* sas_trace;

TCHAR file_name[_MAX_PATH];

. . .

try

{

}

catch (_com_error& er) {

}

[in] BSTR do_file_name );

unable to load the display options file

sas_trace->ApplyDisplayOptions( file_name );

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK );

return 1;

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

4.1.3 ITrace::Save

HRESULT Save (

Saves trace into a file while allowing you to specify a range of packets.

Parameters

file_name

packet_from Beginning packet number when you are saving a range of packets,

packet_to Ending packet number when you are saving a range of packets,

Return values

ANALYZERCOMERROR_UNABLESAVE – unable to save the trace file

ANALYZERCOMERROR_INVALIDPACKETNUMBER - bad packet range

Remarks

Use this method if you want to save a recorded or opened trace into a file. If the display options apply to this trace (see ITrace::ApplyDisplayOptions

ISASAnalyzer::LoadDisplayOptions

If the packet range specified is invalid (for example, packet_to is more than the last packet number in the trace, or packet_from is less than the first packet number in the trace, or packet_from is more than packet_to) then the packet range will be adjusted automatically.

Example

WSH:

Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer")

CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))

Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec")

Trace.ApplyDisplayOptions CurrentDir & "Input\test_do.opt"

Trace.Save CurrentDir & "Output\saved_file.sat"

C++:

ISASTrace* sas_trace;

TCHAR file_name[_MAX_PATH];

LONG packet_from;

LONG packet_to;

. . .

try {

}

catch (_com_error& er)

{

}

[in] BSTR file_name, [in, defaultvalue(-1)] long packet_from, [in, defaultvalue(-1)] long packet_to );

String providing the full pathname to the file where the trace is saved

Value –1 means that the first packet of the saved trace is the first packet of this trace.

Value –1 means that the last packet of the saved trace is the last packet of this trace.

), then hidden packets would not be saved.

sas_trace->Save( file_name, packet_from, packet_to );

if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTRacer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK ); return 1;

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

4.1.4 ITrace::ExportToText

HRESULT ExportToText (

Exports the trace into a text file while allowing you to specify a range of packets.

Parameters

file_name String providing the full file pathname for the exported trace packet_from

packet_to

Return value

ANALYZERCOMERROR_UNABLESAVE –

Remarks

Use this method if you want to export a recorded or opened trace into a text file. If the display options apply to this trace (see ITrace::ApplyDisplayOptions

ISASAnalyzer::LoadDisplayOptions

If the packet range specified is invalid (for example packet_to is more than the last packet number in the trace, or packet_from is less than the first packet number in the trace, or packet_from is more than packet_to) then the packet range will be adjusted automatically.

[in] BSTR file_name,

[in, defaultvalue(-1)] long packet_from,

[in, defaultvalue(-1)] long packet_to );

Beginning packet number when you are exporting a range of packets,

Value –1 means that the first packet of the exported trace is the first packet of this trace.

Ending packet number when you are exporting a range of packets,

Value –1 means that the last packet of the exported trace is the last packet of this trace.

unable to export trace file

), then hidden packets would not be exported.

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

Here is a snippet of an exported text file:

File c:\analyzersw\traces\sas\allsata.sas. From Frame #1 to Frame #20. Frame# _______|_______________________________________________________________________T2 Frame(1) 1.5(G) SATA RCV Time Stamp(29.196 501 432) _______|_______________________________________________________________________T2 Frame(2) 1.5(G) SATA XMT SATA_SOF FIS Type(DMA Activate) Port(0x0) _______| Data(4 bytes) CRC(0x8FA86FC5) SATA_EOF Time Stamp(29.196 513 752) _______|_______________________________________________________________________I2 Frame(3) 1.5(G) SATA RCV Time Stamp(29.196 514 177) _______|_______________________________________________________________________I2 Frame(4) 1.5(G) SATA XMT SATA_SOF FIS Type(Data) Port(0x0) _______| Data(8196 bytes) CRC(0x7BFAA709) SATA_EOF Time Stamp(29.196 518 682) _______|_______________________________________________________________________T2 Frame(5) 1.5(G) SATA RCV Time Stamp(29.196 518 952) _______|_______________________________________________________________________T2 Frame(6) 1.5(G) SATA XMT SATA_SOF FIS Type(DMA Activate) Port(0x0) _______| Data(4 bytes) CRC(0x8FA86FC5) SATA_EOF Time Stamp(29.196 632 872) _______|_______________________________________________________________________I2 Frame(7) 1.5(G) SATA RCV Time Stamp(29.196 633 167) _______|_______________________________________________________________________I2 Frame(8) 1.5(G) SATA XMT SATA_SOF FIS Type(Data) Port(0x0) _______| Data(8196 bytes) CRC(0x7919EFB6) SATA_EOF Time Stamp(29.196 634 687) _______|_______________________________________________________________________T2 Frame(9) 1.5(G) SATA RCV Time Stamp(29.196 634 950) _______|_______________________________________________________________________T2 Frame(10) 1.5(G) SATA XMT SATA_SOF FIS Type(DMA Activate) Port(0x0) _______| Data(4 bytes) CRC(0x8FA86FC5) SATA_EOF Time Stamp(29.196 748 927) _______|_______________________________________________________________________I2 Frame(11) 1.5(G) SATA RCV Time Stamp(29.196 749 220) _______|_______________________________________________________________________I2 Frame(12) 1.5(G) SATA XMT SATA_SOF FIS Type(Data) Port(0x0) _______| Data(8196 bytes) CRC(0x38CA16DA) SATA_EOF Time Stamp(29.196 750 740) _______|_______________________________________________________________________T2 Frame(14) 1.5(G) SATA XMT SATA_SOF FIS Type(DMA Activate) Port(0x0) _______| Data(4 bytes) CRC(0x8FA86FC5) SATA_EOF Time Stamp(29.196 864 980) _______|_______________________________________________________________________I2 Frame(15) 1.5(G) SATA RCV Time Stamp(29.196 865 272) _______|_______________________________________________________________________I2

Example

WSH:

Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer")

CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))

Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec")

Trace.ApplyDisplayOptions CurrentDir & "Input\test_do.opt"

Trace.ExportToText CurrentDir & "Output\text_export.txt"

C++:

ISASTrace* sas_trace;

TCHAR file_name[_MAX_PATH];

LONG packet_from;

LONG packet_to; . . .

try {

}

catch (_com_error& er)

{

}

sas_trace->ExportToText( file_name, packet_from, packet_to );

if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK ); return 1;

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

4.1.5 ITrace::Close

HRESULT Close ( );

Closes the trace.

Parameters

Return values

Remarks

Closes the current trace but does not release the interface pointer. Call the IUnknown::Release method right after this method call. No ITrace method call will succeed

after calling the ITrace::Close Note: Currently there is no need to call ITrace::Close directly, since IUnknown::Release will

close the

trace.

Example

method.

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

4.1.6 ITrace::ReportFileInfo

HRESULT ReportFileInfo (

Saves trace information into a specified text file

Parameters

file_name String providing the full pathname to file where the trace information

Return values

ANALYZERCOMERROR_UNABLESAVE -

Remarks

Creates a new trace information file if the file specified in the file_name parameter does not exist.

Example

WSH:

Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer")

CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))

Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec")

Trace.ReportFileInfo CurrentDir & "Output\file_info.txt"

C++:

ISASTrace* sas_trace;

TCHAR file_name[_MAX_PATH];

. . .

try {

}

catch (_com_error& er)

{

}

[in] BSTR file_name )

report is stored

unable to create trace information report

sas_trace->ReportFileInfo( file_name );

if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK ); return 1;

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

4.1.7 ITrace::ReportErrorSummary

HRESULT ReportErrorSummary (

[in] BSTR file_name );

Saves trace error summary information into the specified text file.

Parameters

file_name String providing the full pathname to a file where the error summary report is stored

Return values

ANALYZERCOMERROR_UNABLESAVE -

unable to create trace information report

Remarks

Creates a new error summary file if the file specified in the file_name parameter does not exist.

Stores error summary in the specified file. Note: This method does not work on Multisegment traces.

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

Here is an example of data stored using this method call:

Error report for allsata.sas recording file. _______|_______________________________________________________________________ Packet Error: Idle Error on channel I1 (0): _______|_______________________________________________________________________ Packet Error: Idle Error on channel T1 (0): _______|_______________________________________________________________________ Packet Error: Bad CRC on channel I1 (0): _______|_______________________________________________________________________ Packet Error: Bad CRC on channel T1 (0): _______|_______________________________________________________________________ Packet Error: Disparity Error on channel I1 (0): _______|_______________________________________________________________________ Packet Error: Disparity Error on channel T1 (0): _______|_______________________________________________________________________ Packet Error: Bad Code on channel I1 (0): _______|_______________________________________________________________________ Packet Error: Bad Code on channel T1 (0): _______|_______________________________________________________________________ Packet Error: Alignment Error on channel I1 (0): _______|_______________________________________________________________________ Packet Error: Alignment Error on channel T1 (0): _______|_______________________________________________________________________ Packet Error: Delimiter Error on channel I1 (0): _______|_______________________________________________________________________ Packet Error: Delimiter Error on channel T1 (0): _______|_______________________________________________________________________ Packet Error: Invalid SSP Frame Type on channel I1 (0): _______|_______________________________________________________________________ Packet Error: Invalid SSP Frame Type on channel T1 (0): _______|_______________________________________________________________________ Packet Error: Invalid SMP Frame Type on channel I1 (0): _______|_______________________________________________________________________ Packet Error: Invalid SMP Frame Type on channel T1 (0): _______|_______________________________________________________________________ Transaction Error: Timed Out SSP on channel I1 (0): _______|_______________________________________________________________________ Transaction Error: Timed Out SSP on channel T1 (0): _______|_______________________________________________________________________ SCSI Error: Incomplete Command on channel I1 (0): _______|_______________________________________________________________________ SCSI Error: Incomplete Command on channel T1 (0): _______|_______________________________________________________________________ MGMT Error: Incomplete Command on channel I1 (0): _______|_______________________________________________________________________ MGMT Error: Incomplete Command on channel T1 (0): _______|_______________________________________________________________________

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

Example

WSH:

Set Analyzer = WScript.CreateObject("LeCroy.SASnalyzer") CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec") Trace.ReportErrorSummary CurrentDir & "Output\error_summary.txt"

C++:

ISASTrace* sas_trace;

TCHAR file_name[_MAX_PATH];

. . .

try

{

} catch (_com_error& er) {

}

sata_trace->ReportErrorSummary( file_name );

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK );

return 1;

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

4.1.8 ITrace::GetPacket

HRESULT GetPacket (

[in] long packet_number, [in, out] VARIANT* packet, [out, retval] long* number_of_bits );

Retrieves a raw packet representation in the PACKETFORMAT_BYTES format (see IPacket Interface

for details).

Parameters

packet_number Zero based number of packet to retrieve

Raw packet representation

packet

number_of_bits

Number of bits in the raw packet representation

Return values

ANALYZERCOMERROR_INVALIDPACKETNUMBER -

specified packet number is invalid

Remarks

The packet parameter has VT_ARRAY | VT_VARIANT actual automation type. Each element of this array has the

VT_UI1 automation type.

Example

VBScript:

<OBJECT

</OBJECT>

<!--

Function DecToBin(Param, NeedLen)

End Function

ID = Analyzer CLASSID = "clsid: 297CD804-08F5-4A4F-B3BA-779B2654B27C" >

While Param > 0

Param = Param/2 If Param - Int(Param) > 0 Then

Res = CStr(1) + Res

Else

Res = CStr(0) + Res End If Param = Int(Param)

Wend DecToBin = Replace( Space(NeedLen - Len(Res)), " ", "0") & Res

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

Sub BtnGetPacket_OnClick

On Error Resume Next Dim Packet NumberOfBits = CurrentTrace.GetPacket (TextPacketNumber.value, Packet) If Err.Number <> 0 Then

MsgBox "GetPacket:" & Err.Number & ":" & Err.Description

Else

For Each PacketByte In Packet

Next PacketStr = Left( PacketStr, NumberOfBits )

End If

End Sub

--> </SCRIPT>

PacketStr = PacketStr & DecToBin(PacketByte, 8) & " " NBytes = NBytes + 1

StatusText.innerText = "Packet ( " & NumberOfBits & " bits ): " & PacketStr

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

C++:

ISASTrace* sas_trace; LONG packet_number;

. . .

VARIANT packet; VariantInit( &packet ); long number_of_bits; try { number_of_bits = sata_trace->GetPacket( packet_number, &packet ); } catch (_com_error& er) { if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(),_T("SASTracer client"), MB_OK ); return 1; }

if ( packet.vt == ( VT_ARRAY | VT_VARIANT) ) { SAFEARRAY* packet_safearray = packet.parray; TCHAR packet_message[256]; TCHAR elem[64];

for ( long i=0; i<(long)packet_safearray->rgsabound[0].cElements; i++) { VARIANT var; HRESULT hr = SafeArrayGetElement(packet_safearray, &i, &var); if (FAILED(hr)) { ::MessageBox( NULL, _T("Error accessing array"), _T("SASTracer client"), MB_OK ); return 1; } if ( var.vt != ( VT_UI1) ) { ::MessageBox( NULL, _T("Array of bytes expected"), _T("SASTracer client"), MB_OK ); return 1; }

_stprintf( elem, _T("%02X "), V_UI1(&var) ); _tcscat( packet_message, elem ); } _stprintf( elem, _T("%d bits"), number_of_bits ); _tcscat( packet_message, elem );

::MessageBox( NULL, packet_message, _T("Raw packet bits"), MB_OK ); } else { ::MessageBox( NULL, _T("Invalid argument"), _T("SASTracer client"), MB_OK ); }

_stprintf( packet_message, _T("packet #%ld: "), packet_number );

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

4.1.9 ITrace::GetPacketsCount

HRESULT GetPacketsCount (

Retrieves the total number of packets in the trace

Parameters

number_of_packets Total number of packets in the trace

Return values Remarks Example

WSH:

C++:

ISASTrace* sas_trace;

. . .

long number_of_packets; long trigg_packet_num; try {

}

catch (_com_error& er)

{

}

TCHAR str_trace_name[256]; _tcscpy( str_trace_name, (TCHAR*)( bstr_trace_name) ); SysFreeString( bstr_trace_name );

TCHAR trace_info[256]; _stprintf( trace_info, _T("Trace:'%s', total packets:%ld, trigger packet:%ld"),

::SetWindowText( m_hwndStatus, trace_info );

[out, retval] long* number_of_packets );

bstr_trace_name = sas_trace->GetName(); number_of_packets = sas_trace->GetPacketsCount(); trigg_packet_num = sas_trace->GetTriggerPacketNum();

if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(),_T("SASTracer client"), MB_OK ); return 1;

str_trace_name, number_of_packets, trigg_packet_num );

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

4.1.10 ITrace::GetTriggerPacketNum

HRESULT GetTriggerPacketNum (

Retrieves the trigger packet number.

Parameters

packet_number Zero based number of the packet where the trigger occurre d

Return values

Remarks

Example

WSH:

CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer") Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec") TriggerPacket = Trace.GetTriggerPacketNum Trace.Save CurrentDir & "Output\trigger_portion.sat", CInt(ErrorPacket)-5, CInt(ErrorPacket)+5 Trace.ExportToText CurrentDir & "Output\trigger_portion.txt", CInt(ErrorPacket)-5, CInt(ErrorPacket)+5

C++:

See example for ITrace::GetPacketsCount.

[out, retval] long* packet_number );

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

4.1.11 ITrace::AnalyzerErrors

HRESULT AnalyzerErrors (

Retrieves trace file errors. Returns an interface pointer to the SASTraceErrors object

Parameters

error_type Type of error collection you want to retrieve;

analyzer_errors Address of a pointer to the SASTraceErrors object interface

Return values

ANALYZERCOMERROR_INVALIDERROR -

Remarks

The SASTraceErrors object is created by this method call, if the call was successful.

Example

WSH:

C++:

ISASTrace* sas_trace;

. . .

ISASAnalyzerErrors* analyser_errors; try {

} catch (_com_error& er) {

}

analyser_errors->Release();

[in] long error_type, [out, retval] ISASAnalyzerErrors** analyzer_errors );

The following values are valid: 0 - OOB Sequence Error 1 - Symbol violation 2 - Disparity Error 3 - Alignment Error 4 - Signaling Latency Error 5 - Invalid State Transition unexpected primitive 6 - Invalid State Transition Primitive Response Time-out 7 - FIS Type Error 8 - FIS Length Error 9 - FIS Direction Error 10 - CRC Error

invalid error type specified

analyser_errors = sas_trace->AnalyzerErrors(error_type).Detach();

if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(),_T("SASTracer client"), MB_OK ); return 1;

. . .

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

4.2 ISASTrace Interface

The ISASTrace interface is a primary dual interface for the SASTrace object. This interface is derived from the ITrace interface. The ISASTrace interface implements all methods from the ITrace interface plus the

following: GetBusPacket

4.2.1 ISASTrace::GetBusPacket

HRESULT GetBusPacket (

Retrieves the interface for a packet within a trace.

Parameters

packet_number Zero based number of packet to retrieve packet Address of a pointer to the SASPacket

Return values

Remarks

The SASPacket object is created by this method call, if the call was successful.

Example

WSH:

C++:

ISASTrace* sas_trace;

. . .

IDispatch* packet; try {

).Detach(); } catch ( _com_error& er)

ISASPacket* custom_packet; HRESULT hr = packet->QueryInterface( IID_ISASPacket, (void**)&custom_packet );

[in] long packet_number, [out, retval] IDispatch** packet )

object interface

packet = sas_trace->GetBusPacket( GetDlgItemInt(IDC_PACKET_NUMBER)

{ if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(),_T("SASTracer client"), MB_OK ); return 1; }

packet->Release();

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

4.3 ISASVerificationScript Interface

The ISASVerificationScript interface is an interface for the SASTrace object. It exposes the trace functionality for running verification scripts. This interface is not dual—which means that scripting languages cannot use it directly, though all of its methods described below are exposed to script languages through the primary automation interface of the SASTrace object.

Remarks

Verification scripts are scripts written in a special manner using the CATC Script Language (CSL). These scripts can be “run” over a recorded trace to “verify” the trace for some verification conditions or to extract more advanced information from the trace. Such scripts utilize a special feature of the SASTracer application, its Verification Script Engine.

Please refer to the SASTracer Manual, SASTracer Verification Script Engine Manual, and SASTracer File Based Decoding Manual for more details.

Attention

The functions of this interface may be legally called either for regular traces or multi-segmented traces. The VSE will open segments of the multi-segmented trace during script execution when it is needed.

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

4.3.1 ISASVerificationScript::RunVerificationScript

HRESULT RunVerificationScript (

Runs a verification script over the recorded trace.

Parameters

verification_script result Address of a variable in which to keep the verification result

Return values

S_OK – if the verification script executed successfully.

Remarks

The name of the verification script is the name of the verification script file (*.pevs). If only the name of the script, without file extension, is specified, SASTracer’s server searches for the named script among the scripts loaded from the \Scripts\VFScripts folder under the SASTracer installation folder. If the full path to the script is specified, then the server attempts to load the script from the specified path prior to running it.

Example For a verification script file named test.pevs, the test name is “test”. Please refer to the

SASTracer Verification Script Engine Manual for more details.

[in] BSTR verification_script, [out, retval] VSResult *result )

Name of the verification script to run

VS_RESULT is an enumeration type that can have five meanings:

SCRIPT_RUNNING (-2) - verification script is running SCRIPT_NOT_FOUND (-1) - verification script with the specified name not found FAILED ( 0) - verification failed PASSED ( 1) - verification passed DONE ( 2) - verification is done, do not care about result

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

Example

C++:

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

ISASTrace* trace;

. . .

ISASVerificationScript* vscript = NULL;

if ( SUCCEEDED ( trace->QueryInterface( IID_ISASVerificationScript, (void**)&vscript ) ) {

}

else {

}

. . .

WSH:

Set Analyzer = WScript.CreateObject("LeCroy.SASTracer") Set Trace = Analyzer.OpenFile( "C:\Some trace files\some_trace.sas" )

Dim Result Result = Trace.RunVerificationScript( "Test1" )

If Result = 1 Then

Else

End If

MsgBox( "Done" )

try {

VS_RESULT result = vscript ->RunVerificationScript("Test1"); if( result == PASSED ) { ::MessageBox( NULL, "Test verification 1 is passed !!!", "SASTracer client", MB_OK );

} } catch (_com_error& er) {

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), "SASTracer client", MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), "SASTracer client", MB_OK );

return 1; }

::MessageBox( NULL, "Unable to get ISASVerificationScript interface !!!", _T("SASTracer client"), MB_OK ); return 1 ;

Msgbox "PASSED"

Msgbox "FAILED"

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

4.3.2 ISASVerificationScript:: GetVScriptEngine

HRESULT GetVScriptEngine (

Retrieves the verification script engine object.

Parameters

script_name vs_engine Address of a pointer to the SASVScriptEngine object interface

Return values

S_OK – if the verification script engine object was successfully retrieved.

Remarks

The name of the verification script is the name of the verification script file (*.pevs). See remark to ISASVerificationScript:: RunVerificationScript

Example

C++:

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

ISASTrace* sas_trace;

. . .

ISASVerificationScript* sas_vscript = NULL;

sas_trace->QueryInterface( IID_ISASVerificationScript, (void**)&sas_vscript ) ) assert( sas_vscript != NULL ); IVScriptEngine* sas_vsengine = NULL; sas_vsengine = sas_vscript -> GetVScriptEngine("Test_1"); assert( sas_vsengine != NULL ); VS_RESULT result = sas_vsengine ->RunVScript();

if( result == PASSED ) {

::MessageBox( NULL, "Test verification 1 is passed !!!", "SASTracer client", MB_OK );

}

. . .

WSH:

Set Analyzer = WScript.CreateObject("LeCroy.SASTracer") Set Trace = Analyzer.OpenFile( "C:\Some trace files\some_trace.sas" ) Dim Result Set VSEngine = Trace.GetVScriptEngine( "Test1" ) Result = VSEngine.RunVScript

If Result = 1 Then

Msgbox "PASSED"

Else

Msgbox "FAILED"

End If

MsgBox( "Done" )

[in] BSTR script_name,

[out, retval] IVScriptEngine** vs_engine )

Name of the verification script to initialize the verification script engine

for details.

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

5 SASRecOptions Object

The SASRecOptions object represents the options for the SASTracer hardware and is used to specify the recording parameters.

The SASRecOptions object allows you to:

o Load/save the recording options from/to the file. o Set up recording mode and recording buffer size. o Set up custom recording parameters, such as ChannelSettings,

DataTruncate, MultiSegment mode, and SpoolMode.

The SASRecOptions object can be created by using the

ISASAnalyzer::GetRec

The SASRecOptions object supports the following interfaces:

Interfaces Description

IRecOptions

ISASRecOptions

The ISASRecOptions interface is a primary interface for the SASRecOptions object.

ordingOptions method.

Allows you to load/save recording options from/to the file, reset recording options, set up recording mode, recording buffer size, trigger position, and the trace file name.

Identical to IRecOptions interface

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

5.1 IRecOptions Interface

The IRecOptions interface is a dual interface for the SASRecOptions object. IRecOptions implements the following methods:

Load Save SetRecMode SetBufferSize SetPostTriggerPercentage SetTriggerBeep SetSaveExternalSignals SetTraceFileName Reset

Note: All methods of the IRecOptions interface are also available in the ISASRecOptions

Interface.

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

5.1.1 IRecOptions::Load

HRESULT Load (

Loads recording options from the specified file.

Parameters

ro_file_name String that provides the full pathname to the recording options file

Return values

ANALYZERCOMERROR_UNABLEOPENFILE

Remarks

Example

WSH:

CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer") Set RecOptions = Analyzer.GetRecordingOptions RecOptions.Load( CurrentDir & "Input\rec_options.rec" )

C++:

[in] BSTR ro_file_name );

– unable to open file

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

5.1.2 IRecOptions::Save

HRESULT Save (

Saves recording options into the specified file.

Parameters

ro_file_name String that provides the full pathname to the recording options file

Return values

ANALYZERCOMERROR_UNABLEOPENFILE –

Remarks

If the specified file does not exist, it will be created. If it exists, it will be overwritten.

Example

WSH:

CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer") Set RecOptions = Analyzer.GetRecordingOptions ' do the changes of recording options here RecOptions.Save( CurrentDir & "Input\rec_options.rec" )

C++:

[in] BSTR ro_file_name );

unable to open file

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

5.1.3 IRecOptions::SetRecMode

HRESULT SetRecMode (

Sets the recording mode.

Parameters

rec_mode Enumerated value providing the mode to set;

Return values

E_INVALIDARG –

Remarks

The default setting of recording options is "snapshot" recording mode.

Example

WSH:

Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer") Set RecOptions = Analyzer.GetRecordingOptions RecOptions.SetRecMode 2 ' Event trigger

C++:

[in] ERecModes rec_mode );

ErecModes enumerator has the following values:

RMODE_SNAPSHOT ( 0 )

RMODE_MANUAL ( 1 )

RMODE_USE_TRG ( 2 )

invalid recording mode was specified

snapshot recording mode manual trigger event trigger

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

5.1.4 IRecOptions::SetBufferSize

HRESULT SetBufferSize (

Sets the size of the recording buffer.

Parameters

buffer_size Size of the recording buffer in bytes

Return values

E_INVALIDARG –

Remarks

The default setting is 16 MB for Conventional Recording mode and 120 GB or 12.5 hours for Spooled Recording Mode.

Example

WSH:

Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer") Set RecOptions = Analyzer.GetRecordingOptions RecOptions.SetBufferSize 2*1024*1024 ' 2 MB

C++:

[in] long buffer_size );

invalid buffer size was specified

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

5.1.5 IRecOptions::SetPostTriggerPercentage

HRESULT SetPostTriggerPercentage (

Sets the post-trigger buffer size.

Parameters

posttrigger_percentage Size of the post-trigger buffer in percent of the whole recording buffer (see IRecOptions::SetBufferSize

Return values

E_INVALIDARG –

Remarks

This method call has no effect if recording mode is set to (see IRecOptions::SetRecMode

The default setting is 50%.

Example

WSH:

Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer") Set RecOptions = Analyzer.GetRecordingOptions RecOptions.SetPostTriggerPercentage 60 ' 60%

C++:

[in] short posttrigger_percentage );

invalid percentage was specified

RMODE_SNAPSHOT

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

5.1.6 IRecOptions::SetTriggerBeep

HRESULT SetTriggerBeep (

Sets a flag to make a sound when a trigger occurs.

Parameters

beep TRUE – Beep when trigger occurs.

Return values

Remarks

The default state of the beeper is FALSE.

Example

WSH:

Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer") Set RecOptions = Analyzer.GetRecordingOptions RecOptions.SetTriggerBeep TRUE

C++:

[in] BOOL beep );

FALSE – Do not beep when trigger occurs.

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

5.1.7 IRecOptions::SetSaveExternalSignals

HRESULT SetSaveExternalSignals (

Sets a flag to save external signals.

Parameters

save TRUE – Save external signals.

Return values

Remarks

By default, external signals are not saved.

Example

WSH:

Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer") Set RecOptions = Analyzer.GetRecordingOptions RecOptions.SetSaveExternalSignals TRUE

C++:

[in] BOOL save );

FALSE – Do not save external signals.

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

5.1.8 IRecOptions::SetTraceFileName

HRESULT SetTraceFileName (

Sets the file path to where the trace will be stored after recording.

Parameters

file_name String that provides the full file pathname to where the recording

Return values Remarks

If the specified file does not exist, it will be created. If it exists, it will be overwritten.

Example

WSH:

CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer") Set RecOptions = Analyzer.GetRecordingOptions ' do the changes of recording options here RecOptions.Save( CurrentDir & "Input\trace.sat" )

C++:

[in] BSTR file_name );

will be stored

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

5.1.9 IRecOptions::Reset

HRESULT Reset ( )

Resets the recording options to the initial state.

Parameters

Return values

Remarks

For default values of recording options, see the remarks sections of all IRecOptions

ISASRecOptions

Example

WSH:

Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer") Set RecOptions = Analyzer.GetRecordingOptions RecOptions.SetRecMode 2 ' Event trigger RecOptions.SetBufferSize 1024*1024 ' 1 MB RecOptions.SetPostTriggerPercentage 60 ' 60% . . . RecOptions.Reset()

C++:

methods.

and

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

5.2 ISASRecOptions Interface

This interface is identical to the IRecOptions interface

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

6 SASPacket Object

The SASPacket object represents a single packet of the recorded trace file. The SASPacket object allows you to retrieve packet content and packet properties, such as

timestamp, link width, packet start lane, packet direction, and packet errors. The SASPacket object can be created by calling ISASTrace::GetBusPacket The SASPacket object supports the following interfaces:

Interfaces Description

IPacket ISASPacket

The ISASPacket interface is a primary interface for the SASPacket object.

Allows retrieval of the packet’s timestamp. Extends the IPacket interface.

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

6.1 IPacket Interface

The IPacket interface is a dual interface for the SASPacket object. IPacket implements the following method:

GetTimestamp

Note: All methods of the IPacket interface are also available in the ISASPacket interface

6.1.1 IPacket::GetTimestamp

HRESULT GetTimestamp ( [out, retval] double* timestamp

Returns the packet timestamp in nanoseconds.

Parameters

timestamp Timestamp of the beginning symbol of the packet, from the start of recording

Return values

Remarks

Example

WSH:

Set Analyzer = WScript.CreateObject( “LeCroy.SASTracer” ) Set Trace = Analyzer.MakeRecording( CurrentDir & "Input\test_ro.rec" ) TriggerPacket = Trace. GetTriggerPacketNum Set Packet = Trace.GetBusPacket(TriggerPacket) MsgBox "Trigger packet at " & Packet.GetTimestamp & " ns"

C++:

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

6.2 ISASPacket Interface

The ISASPacket interface is a primary dual interface for the SASPacket object. This interface is derived from the IPacket interface. The ISASPacket interface implements all methods from the IPacket interface plus the

following:

GetPacketData GetLinkNumber GetFrameType GetDirection GetErrors GetTotalDwords

6.2.1 IPacket::GetPacketData

HRESULT GetPacketData ( [in] EPacketFormat format, [out] VARIANT* packet, [out, retval] long* number_of_bytes )

Retrieves a raw packet representation.

Parameters

format Data representation format

The EPacketFormat enumerator has the following values:

PACKETFORMAT_BYTES PACKETFORMAT_SCRAMBLED_BYTES PACKETFORMAT_TEN_BIT

packet Raw packet data number_of_bytes Number of bytes in the packet

Return values

ANALYZERCOMERROR_WRONGCALL - Unknown packet format specified

Remarks

The packet parameter has VT_ARRAY | VT_VARIANT actual automation type. For PACKETFORMAT_BYTES and PACKETFORMAT_SCRAMBLED_BYTES, each

element of this array has the VT_UI1 automation type. For PACKETFORMAT_TEN_BIT, each element of this array has the VT_UI2 automation

type.

( 0 ) bytes

( 1 ) scrambled bytes

( 2 ) 10-bit codes

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

Example

VBScript:

<OBJECT

> </OBJECT>

<SCRIPT LANGUAGE="VBScript"> <!-- Function DecToBin(Param, NeedLen)

End Function

Sub BtnGetPacket_OnClick

StatusText.innerText = "Packet ( " & NumberOfUnits & " bytes ): " & PacketStr

End Sub

--> </SCRIPT>

ID = Analyzer

CLASSID = "clsid: 0B179BB7-DC61-11d4-9B71-000102566088"

While Param > 0

Param = Param/2 If Param - Int(Param) > 0 Then

Res = CStr(1) + Res

Else

Res = CStr(0) + Res End If Param = Int(Param)

Wend DecToBin = Replace( Space(NeedLen - Len(Res)), " ", "0") & Res

ClearStatus() On Error Resume Next Set Packet = CurrentTrace.GetBusPacket (TextPacketNumber.value)

If Err.Number <> 0 Then

MsgBox "GetBusPacket:" & Err.Number & ":" & Err.Description

Else

Timestamp = Packet.GetTimestamp() If Err.Number <> 0 Then

MsgBox "GetTimestamp:" & Err.Number & ":" & Err.Description End If

NumberOfUnits = Packet.GetPacketData ( PACKETFORMAT_BYTES, PacketData)

If Err.Number <> 0 Then

MsgBox "GetPacketData:" & Err.Number & ":" & Err.Description

Else For Each PacketByte In PacketData

PacketStr = PacketStr & DecToBin(PacketByte, 8) & " " NBytes = NBytes + 1

End If End If

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

C++:

ISASPacket* custom_packet; LONG packet_number;

. . .

VARIANT packet_data; double timestamp_ns; VariantInit( &packet_data ); long number_of_bytes; try { number_of_bytes = custom_packet->GetPacketData(PACKETFORMAT_BYTES, &packet_data);

} catch (_com_error& er) {

}

if ( packet_data.vt == ( VT_ARRAY | VT_VARIANT) ) {

_stprintf(packet_message, _T("packet #%ld: "), GetDlgItemInt(IDC_PACKET_NUMBER));

::MessageBox( NULL, _T("Error accessing array"), _T("SASTracer client"), MB_OK );

::MessageBox(NULL, _T("Array of bytes expected"), _T("SASTracer client"), MB_OK );

} else { ::MessageBox(NULL, _T("Invalid argument"), _T("SASTracer client"), MB_OK ); }

timestamp_ns = custom_packet->GetTimestamp ( );

if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(),_T("SASTracer client"), MB_OK ); return 1;

SAFEARRAY* packet_safearray = packet_data.parray; TCHAR* packet_message =

new TCHAR [ 3*packet_safearray->rgsabound[0].cElements + 64 ];

TCHAR elem[64];

_stprintf( elem, _T(" %.0lf ns"), timestamp_ns ); _tcscat( packet_message, elem ); _stprintf( elem, _T(", %d bytes: "), number_of_bytes ); _tcscat( packet_message, elem );

for ( long i=0; i<(long)packet_safearray->rgsabound[0].cElements; i++) {

VARIANT var; HRESULT hr = SafeArrayGetElement(packet_safearray, &i, &var); if (FAILED(hr)) {

return 1; }

if ( var.vt != ( VT_UI1) ) {

return 1; } _stprintf( elem, _T("%02X "), V_UI1(&var) );

_tcscat( packet_message, elem ); } ::MessageBox( NULL, packet_message, _T("packet"), MB_OK ); delete [] packet_message;

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

6.2.2 IPacket::GetDirection

HRESULT GetDirection ( [out, retval] long* direction )

Returns direction (host/device for SATA or initiator/target for SAS) of this packet.

Parameters

direction 0 - Host (initiator) packet

1 - Device (target) packet

Return values

Remarks

Example

WSH:

CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” ) ) Set Analyzer = WScript.CreateObject( “LeCroy.SASTracer” ) Set Trace = Analyzer.OpenFile( CurrentDir & “Input\errors.sas” ) Set Packet = Trace.GetBusPacket( 0 ) MsgBox "Direction: " & Packet.GetDirection

C++:

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

6.2.3 IPacket::GetErrors

HRESULT GetErrors ( [out] VARIANT* error_array, [out, retval] long* number_of_errors )

Returns an array of errors present in this packet.

Parameters

error_array Array of error IDs present in this packet.

See ITrace::AnalyserErrors

number_of_errors Total number of errors in this packet

Return values

Remarks

Example

WSH:

C++:

for error ID values.

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

7 SASTraceErrors Object

The SASTraceErrors object represents the collection of errors that occurred in the recorded trace file.

The SASTraceErrors object can be created by calling ITrace::AnalyzerErrors The ISASAnalyzerErrors interface is a primary interface for the SASTraceErrors object.

7.1 ISASAnalyzerErrors Dispinterface

This is a standard collection interface for collection of packet numbers with errors of a specified type (see ITrace::AnalyzerErrors

It has the following methods, which are standard for collection interfaces:

get_Item get_Count

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

7.1.1 ISASAnalyzerErrors::get_Item

HRESULT get_Item(

Parameters

index Index of the error in the collection packet_number

[in] long index, [out, retval] long* packet_number );

Error packet number

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

7.1.2 ISASAnalyzerErrors::get_Count

HRESULT get_Count(

Returns the number of errors in the trace.

Parameters

number_of_errors Number of elements in the collection

Remarks

Example

WSH:

' Makes recording and saves the portions of the recorded trace

' where "Running Disparity" errors occured. CurrentDir = Left(WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” )) Set Analyzer = WScript.CreateObject( “LeCroy.SASTracer” ) Set Trace = Analyzer.MakeRecording( CurrentDir & "Input\test_ro.rec" ) Set Errors = Trace.AnalyzerErrors( 32 ) ' Running Disparity Error For Each ErrorPacketNumber In Errors

[out, retval] long* number_of_errors );

ErrorFile = CurrentDir & "\Output\PckLen_error_span_" &

CStr(ErrorPacketNumber) & ".sas"

Trace.Save ErrorFile, CInt(ErrorPacketNumber)-5, CInt(ErrorPacketNumber)+5

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

C++:

ISASTrace* sas_trace;

. . .

ISASAnalyzerErrors* analyser_errors; try {

analyser_errors = sas_trace->AnalyzerErrors(error_type).Detach();

} catch (_com_error& er) {

if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(),_T("SASTracer client"), MB_OK ); return 1;

}

TCHAR all_errors[2048]; _stprintf( all_errors, _T("Errors: ") );

try {

long errors_count = analyser_errors->GetCount(); long analyzer_error; if ( !errors_count ) {

_tcscat( all_errors, _T("none") ); } for ( long i=0; i<errors_count && i<2048/32; i++ ) {

analyzer_error = analyser_errors->GetItem(i);

TCHAR cur_error[32];

_stprintf( cur_error, _T(" %ld"), analyzer_error );

_tcscat( all_errors, cur_error ); } if ( i>2048/32 )

_tcscat( all_errors, _T(" ...") );

} catch (_com_error& er) {

if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(),_T("SASTracer client"), MB_OK ); return 1;

}

analyser_errors->Release();

::SetWindowText( m_hwndStatus, all_errors );

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

8 SASVScriptEngine Object

The SASVScriptEngine object allows you to run verification scripts over the recorded trace. It extends the functionality of the ISASVerificationScript interface of a SASTrace object. The main advantage of a SASVScriptEngine object is that it allows clients implementing _IVScriptEngineEvents a callback interface to receive notifications when a verification script is running.

The SASVScriptEngine object can be created by calling

ISASVerificationScript:: GetVScriptEngine

The SASVScriptEngine object supports the following interfaces:

Interfaces Description

IVScriptEngine

_ISASAnalyzerEvents

The IVScriptEngine interface is a primary interface for the SASVScriptEngine object.

Remarks

Please refer to the SASTracer Manual, SASTracer Verification Script Engine Manual, and SASTracer File Based Decoding Manual for more details.

Provides advanced control over the verification script and allows you to execute the script asynchronously.

Events from SASVScriptEngine object

8.1 IVScriptEngine Interface

The IVScriptEngine interface is the primary dual interface for the SASVScriptEngine object. It implements the following properties and methods:

VscriptName Tag RunVScript RunVScriptEx LaunchVScript Stop GetScriptVar SetScriptVar

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

8.1.1 IVScriptEngine::VScriptName

[propget] HRESULT VScriptName ( [out, retval] BSTR *pVal )

[propget] HRESULT VScriptName ( [in] BSTR newVal )

Property puts and gets current verification script name.

Parameters

pVal Address of the variable where current verification script name is kept newVal Name of the verification script to initialize verification script engine

Return values

Remarks

only the name of the script, without a file extension, is specified, the SASTracer server searches for the named script among the scripts loaded from the \Scripts\VFScripts folder under the SASTracer installation folder. If the full path to the script is specified, then the server attempts to load the script from the specified path prior to running it.

Example

C++:

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

ISASTrace* sas_trace;

. . .

ISASVerificationScript* sas_vscript = NULL;

sas_trace->QueryInterface( IID_ISASVerificationScript, (void**)&sas_vscript ) ) assert( sas_vscript != NULL );

IVScriptEngine* sas_vsengine = NULL; sas_vsengine = sas_vscript -> GetVScriptEngine("MyVSEngine"); assert( sas_vsengine != NULL );

sas_vsengine -> PutVScriptName("Test_1"); assert( sas_vsengine -> GetVScriptName() == "Test_1" );

VS_RESULT result = sas_vsengine ->RunVScript(); if( result == PASSED ) {

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

}

. . .

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

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

8.1.2 IVScriptEngine::Tag

[propget] HRESULT Tag ( [out, retval] int* pVal )

[propget] HRESULT Tag ( [in] int newVal )

Property assigns and gets a tag to the VSE object. This tag will be used in event notifications, allowing a client event handler to determine which VSE object sent the event.

Parameters

pVal Address of the variable where the current VSE tag is kept newVal New tag for VSE

Return values

Remarks

Example

C++:

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

ISASTrace* sas_trace;

. . .

ISASVerificationScript* sas_vscript = NULL;

sas_trace->QueryInterface( IID_ISASVerificationScript, (void**)&sas_vscript ) ) assert( sas_vscript != NULL );

IVScriptEngine* sas_vsengine = NULL; sas_vsengine = sas_vscript -> GetVScriptEngine("Test_1"); assert( sas_vsengine != NULL );

sas_vsengine ->PutTag( 0xDDAADDAA ); assert( sas_vsengine -> GetTag() == 0xDDAADDAA );

VS_RESULT result = sas_vsengine ->RunVScript(); if( result == PASSED ) {

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

}

. . .

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

8.1.3 IVScriptEngine::RunVScript

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

Runs the verification script currently specified for this engine.

Parameters

pResult Address of the variable where the results of the verification are kept

Return values

Remarks

The name of the verification script is the name of the verification script file (*.pevs). If only the name of the script, without a file extension, is specified, the SASTracer server searches for the named script among the scripts loaded from the \Scripts\VFScripts folder under the SASTracer installation folder. If the full path to the script is specified, then the server attempts to load the script from the specified path prior to running it.

Example

C++:

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

ISASTrace* sas_trace;

. . .

ISASVerificationScript* sas_vscript = NULL;

sas_trace->QueryInterface( IID_ISASVerificationScript, (void**)&sas_vscript ) ) assert( sas_vscript != NULL );

IVScriptEngine* sas_vsengine = NULL; sas_vsengine = sas_vscript -> GetVScriptEngine("MyVSEngine"); assert( sas_vsengine != NULL );

sas_vsengine -> PutVScriptName("Test_1"); assert( sas_vsengine -> GetVScriptName() == "Test_1" );

VS_RESULT result = sas_vsengine ->RunVScript(); if( result == PASSED ) {

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

}

. . .

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

8.1.4 IVScriptEngine::RunVScriptEx

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

Changes the current verification script name and runs the verification script.

Parameters

script_name Name of the verification script to initialize the script verification engine pResult Address of the variable where the results of the verification are kept

Return values Remarks

This method makes a “synchronous” call, which means that this method does not

return until the script stops running.

See ISASVerificationScript:: RunVerificationScript

Example

C++:

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

ISASTrace* sas_trace;

. . .

ISASVerificationScript* sas_vscript = NULL;

sas_trace->QueryInterface( IID_ISASVerificationScript, (void**)&sas_vscript ) ) assert( sas_vscript != NULL );

IVScriptEngine* sas_vsengine = NULL; sas_vsengine = sas_vscript -> GetVScriptEngine("Test_1"); assert( sas_vsengine != NULL );

VS_RESULT result = sas_vsengine ->RunVScript(); if( result == PASSED ) {

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

}

result = sas_vsengine ->RunVScriptEx("Test_2"); if( result == PASSED ) {

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

}

result = sas_vsengine ->RunVScriptEx("C:\\MyTests\\Test_3.pevs"); if( result == PASSED ) {

::MessageBox( NULL, "Test 3 passed !!!", "SASTracer client", MB_OK ); } . . .

method for details.

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

8.1.5 IVScriptEngine::LaunchVScript

HRESULT LaunchVScript ( )

Launches the current verification script.

Parameters

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, which means that this method

immediately returns after the script starts running.

When the verification script stops running, the VSE object sends a special event notification _ IVScriptEngineEvents:: OnVScriptFinished can also terminate the running script using the method IVScriptEngine:: Stop

Example

C++:

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

ISASTrace* sas_trace;

. . .

ISASVerificationScript* sas_vscript = NULL;

sas_trace->QueryInterface( IID_ISASVerificationScript, (void**)&sas_vscript ) ) assert( sas_vscript != NULL );

IVScriptEngine* sas_vsengine = NULL; sas_vsengine = sas_vscript -> GetVScriptEngine("Test_1"); assert( sas_vsengine != NULL );

VS_RESULT result = sas_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.

. . .

to the client event handler. You

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

8.1.6 IVScriptEngine::Stop

HRESULT Stop ( )

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

Parameters

Return values

Remarks

Example

C++:

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

ISASTrace* sas_trace;

. . .

ISASVerificationScript* sas_vscript = NULL;

sas_trace->QueryInterface( IID_ISASVerificationScript, (void**)&sas_vscript ) ) assert( sas_vscript != NULL );

IVScriptEngine* sas_vsengine = NULL; sas_vsengine = sas_vscript -> GetVScriptEngine("Test_1"); assert( sas_vsengine != NULL );

VS_RESULT result = sas_vsengine ->LaunchVScript();

. . .

if( NotEnoughResourcesToProcessVS ) sas_vsengine ->Stop();

. . .

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

8.1.7 IVScriptEngine::GetScriptVar

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

Changes the current verification script name and runs the verification script.

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 where the result will be kept

Return values

E_PENDING – if this method is called when the script is already running

Remarks

If there is no such global variable or constant with the name var_name, the resulting

value will contain an empty VARIANT.

Example

C++:

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

ISASTrace* sas_trace;

. . .

ISASVerificationScript* sas_vscript = NULL;

sas_trace->QueryInterface( IID_ISASVerificationScript, (void**)&sas_vscript ) ) assert( sas_vscript != NULL );

IVScriptEngine* sas_vsengine = NULL; sas_vsengine = sas_vscript -> GetVScriptEngine("Test_1"); assert( sas_vsengine != NULL );

VS_RESULT result = sas_vsengine ->RunVScript();

. . .

VARIANT my_var; VariantInit( &my_var );

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

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

. . .

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

WSH:

. . .

Set Trace = Analyzer.OpenFile( TraceName ) ' Open the trace Set VSEngine = Trace.GetVScriptEngine( VScript ) ' Get VS Engine object

Result = VSEngine.RunVScript

MyIntVar = VSEngine.GetScriptVar( "MyIntVar" ) ' Let's suppose that MyIntVar contains an integer. MyStrVar = VSEngine.GetScriptVar( "MyStrVar" ) ' Let's suppose that MyStrVar contains a string.

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

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

8.1.8 IVScriptEngine::SetScriptVar

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

Allows you to set the value of some verification script global variable before/after executing the script (refer to the SASTracer Verification Script Engine Manual and the File Based Decoding Manual for information on how a script can declare, set, and use global variables).

Only integers, strings, or arrays of VARIANTs are allowed as correct values. Arrays of VARIANTs are converted into list values inside of scripts. See the SASTracer File Based Decoding 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 variable containing the new variable value

Return values

E_PENDING – if this method is called when the script is already running

Remarks

This function allows you to set internal script variables before running a script, giving you the opportunity to make run-time customization from COM/Automation client applications.

In order for this operation to take effect during execution of the script, a global variable with the name specified by var_name should be declared by the script.

Example

C++:

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

ISASTrace* sas_trace;

. . .

ISASVerificationScript* sas_vscript = NULL;

sas_trace->QueryInterface( IID_ISASVerificationScript, (void**)&sas_vscript ) ) assert( sas_vscript != NULL );

IVScriptEngine* sas_vsengine = NULL; sas_vsengine = sas_vscript -> GetVScriptEngine("Test_1"); assert( sas_vsengine != NULL );

VARIANT my_var; VariantInit( &my_var );

my_var.vt = VT_I4; // Integer my_var.lVal = 100;

// Set internal script variable 'MyVar' to 100. sas_vsengine->SetScriptVar( _bstr_t("MyVar"), my_var );

VS_RESULT result = sas_vsengine ->

. . .

RunVScript();

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

WSH:

. . .

Set Trace = Analyzer.OpenFile( TraceName ) ' Open the trace. Set VSEngine = Trace.GetVScriptEngine( VScript ) ' Get VS Engine object.

VSEngine.GetScriptVar( "MyIntVar" , 100 ) VSEngine.GetScriptVar( "MyStrVar" , "Hello !!!" ) Result = VSEngine.RunVScript

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

9 SASVScriptEngine Object Events

9.1 _IVScriptEngineEvents Interface

In order to retrieve event notifications from the SASTracer application when a verification script engine object is running the script, you must implement the _IVScriptEngineEvents callback interface. Since this interface is a default source interface for the SASVScriptEngine object, there is a very simple implementation from languages like Visual Basic, VBA, VBScript, and WSH.

Some script engines impose restrictions on handling events from “in direct” automation objects in typeless script languages (when an automation interface to the object is obtained from a call of some method, rather than from creation function, such as CreateObject() in VBScript). The SASTracer application provides a special COM class, allowing receiving and handling of notifications from a VSE object even in script languages not supporting event handling from "indirect" objects.

Example

C++ implementation used in the examples below implements an event sink object by deriving it from IdispEventImpl, but not specifying the type library as a template argument. Instead, the type library and default source interface for the object are determined using AtlGetObjectSourceInterface().

A SINK_ENTRY() macro is used for each event from each source interface that is to be handled:

C++:

class CVSEngineSink : public IDispEventImpl<IDC_SRCOBJ_VSE, CVSEngineSink > { public:

...

BEGIN_SINK_MAP(CVSEngineSink)

// Make sure the Event Handlers have __stdcall calling convention. SINK_ENTRY( IDC_SRCOBJ_VSE, 1, OnVScriptReportUpdated ) SINK_ENTRY( IDC_SRCOBJ_VSE, 2, OnVScriptFinished ) SINK_ENTRY( IDC_SRCOBJ_VSE, 3, OnNotifyClient )

END_SINK_MAP()

HRESULT __stdcall OnVScriptReportUpdated ( BSTR newLine, int TAG ); HRESULT __stdcall OnVScriptFinished( BSTR script_name, VS_RESULT result, int TAG ); HRESULT __stdcall OnNotifyClient ( int eventId, VARIANT eventBody, int TAG );

HRESULT Advise(IUnknown* pUnk) { AtlGetObjectSourceInterface(pUnk, &m_libid, &m_iid, &m_wMajorVerNum, &m_wMinorVerNum); return DispEventAdvise(pUnk, &m_iid); }

HRESULT Unadvise(IUnknown* pUnk) { AtlGetObjectSourceInterface(pUnk, &m_libid, &m_iid, &m_wMajorVerNum, &m_wMinorVerNum); return DispEventUnadvise(pUnk, &m_iid); }

... };

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

Then, after you have established the connection with the server, you need to advise your implementation of the event interface:

IVScriptEngine vscript_engine = NULL;

try {

} catch (_com_error& er ) {

}

if ( vscript_engine == NULL ) {

}

CVSEngineSink vse_sink; HRESULT hr = vse_sink . Advise( vscript_engine ); // “Subscribe” for receiving events.

...

VS_RESULT res = SCRIPT_NOT_FOUND; try {

} catch (_com_error& er) {

}

// Tear connection with the test case. vse_sink.Unadvise( vscript_engine );

...

vscript_engine = vscript ->GetVScriptEngine( "Test_1" );

SetStatusError( er );

vscript = NULL; return E_FAIL;

res = (VS_RESULT)vscript_engine ->RunVScript();

SetStatusError( er );

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

VBA: ( MS Excel )

Public SASTracer As SASAnalyzer Public Trace As SASTrace Public GVSEngine As VScriptEngine

' VSEngineEventsModule is a special class implementing VSE event handlers. ' It should have, in the global declaration section, the line like this: ' Public WithEvents VSEEvents As VScriptEngine

Dim X As New VSEngineEventsModule

Private Sub RunVScritButton_Click()

End Sub

Dim VSEngine As VScriptEngine Dim IVScript As ISASVerificationScript Dim ScriptName, fileToOpen As String

ScriptName = ThisWorkbook.Sheets("Sheet1").Cells(2, 2)

If SASTracer Is Nothing Then

Set SASTracer = New SASAnalyzer

If SASTracer Is Nothing Then

MsgBox "Unable to connect to SASTracer", vbExclamation Exit Sub

End If

fileToOpen = ThisWorkbook.Sheets("Sheet1").Cells(1, 2) Set Trace = SASTracer.OpenFile( fileToOpen )

Set IVScript = Trace ' Get the IfcVerificationScript interface. Set VSEngine = IVScript.GetVScriptEngine( ScriptName )

' "Subscribe" for receiving VSE events. ' The X variable (an instance of VSEngineEventsModule class) handles them.

Set X.VSEEvents = VSEngine

...

VSEngine.Tag = 12 ' Assign a tag for VSE object. VSEngine.RunVScript ' Run verification script.

Set X.VSEEvents = Nothing ' "Unsubscribe" for receiving VSE events. Set VSEngine = Nothing ' Release external Set IVScript = Nothing ' objects.

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

9.1.1 IVScriptEngineEvents::OnVScriptReportUpdated

HRESULT OnVScriptReportUpdated ( [in] BSTR newline, [in] int tag )

Fires when running a verification script. Calls the ReportText( newLine ) function (please refer to the SASTracer Verification Script Engine Manual for details on the ReportText function).

Parameters

newline New portion of text reported by the verification script tag VSE object's tag

Return values

Remarks

Make sure that C++ event handlers have __stdcall calling convention.

Example

C++:

HRESULT __stdcall OnVScriptReportUpdated (BSTR newLine, int TAG ) {

}

VBA (MS Excel):

Public WithEvents VSEEvents As VScriptEngine Public LineIndex As Integer

. . .

Private Sub VSEEvents_OnVScriptReportUpdated(ByVal newLine As String, ByVal Tag As Long)

ThisWorkbook.Sheets("Sheet1").Cells(LineIndex, 1) = newLine LineIndex = LineIndex + 1

End Sub

TRACE( "Line: %s, TAG: %d\n", newLine, TAG );

. . .

return S_OK;

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

9.1.2 IVScriptEngineEvents::OnVScriptFinished

HRESULT OnVScriptFinished ( [in] BSTR script_name, [in] VS_RESULT result, [in] int TAG )

Fires when running a verification script. Calls the ReportText( newLine ) function (please refer to the SASTracer Verification Script Engine Manual for details on the ReportText function).

Parameters

script_name Name of the verification script result Result of "verification"

See ISASVerificationScript::RunVerificationScript

TAG VSE object's tag

Return values Remarks

Make sure that C++ event handlers have __stdcall calling convention. Example

C++:

HRESULT __stdcall CComplTestSink::OnVScriptFinished(

BSTR script_name, VS_RESULT result, int TAG )

{

USES_CONVERSION;

TCHAR tmp[220]; sprintf( tmp, "Script completed, name : %s, result = %d, TAG = %d",

W2A(script_name), result, TAG ); . . .

return S_OK;

}

VBA (MS Excel):

Public WithEvents VSEEvents As VScriptEngine

. . .

Private Sub VSEEvents_OnVScriptFinished( ByVal script_name As String,

ByVal result As SASAutomationLib.VS_RESULT, ByVal Tag As Long )

Dim ResString As String ResString = "Script name : " & script_name & ", result = " &

CStr(result) & ", TAG = " & CStr(Tag)

ThisWorkbook.Sheets("Sheet1").Cells(7, 2) = ResString

End Sub

method for details.

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

9.1.3 IVScriptEngineEvents::OnNotifyCount

HRESULT OnNotifyCount (

[in] int eventId,

[in] VARIANT eventBody,

[in] int TAG )

Fired when running a verification script. Calls the NotifyClient() function.

Parameters

eventID Event ID

eventBody Body of event packed in a VARIANT object

TAG VSE object's tag

Return values

Remarks

The information packed in the event body is opaque for VSE. It only packs the information given to the NotifyClient() function inside of a verification script into a VARIANT object and sends it to client applications.

See the SASTracer Verification Script Engine Manual for details about the NotifyClient() script function.

Example

SASTracer Verification script:

ProcessEvent() {

. . .

NotifyClient( 2, [in.Index, in.Level, GetChannelName(), GetEventName(), TimeToText( in.Time )] );

. . .

}

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

VBA (MS Excel):

Public WithEvents VSEEvents As VScriptEngine

. . .

Private Sub VSEEvents_OnNotifyClient( ByVal eventId As Long,

Dim Col As Integer Dim Item As Variant

ThisWorkbook.Sheets("Sheet1").Cells(LineIndex, 1) = eventId

If IsArray(eventBody) Then Col = 3

For Each Item In eventBody ThisWorkbook.Sheets("Sheet1").Cells(LineIndex, Col) = Item Col = Col + 1 Next

Else ThisWorkbook.Sheets("Sheet1").Cells(LineIndex, 2) = eventBody

End If

LineIndex = LineIndex + 1

End Sub

ByVal eventBody As Variant, ByVal Tag As Long )

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

10 SASAnalyzer Object Events

10.1 _ISASAnalyzerEvents Dispinterface

In order to retrieve the events from a SASAnalyzer object, you must implement the _ISASAnalyzerEvents interface. Since this interface is the default source interface for the SASAnalyzer object, there is a very simple implementation from languages, such as Visual

Basic, VBA, VBScript, and WSH.

Some script engines impose restrictions on handling events from “in direct” automation objects in typeless script languages (when the automation interface to the object is obtained from a call of some method, rather than from a creation function, such as CreateObject() in VBScript). The SASTracer application provides a special COM class, allowing receiving and handling notifications from the VSE object even in script languages not supporting event handling from "indirect" objects.

C++ implementation used in the examples below utilizes a sink object by deriving it from IdispEventImpl, but not specifying the type library as a template argument. Instead, the type library and default source interface for the object are determined using AtlGetObjectSourceInterface().

A SINK_ENTRY() macro is used for each event from each source interface that is to be handled:

class CAnalyzerSink : public IDispEventImpl<IDC_SRCOBJ, CAnalyzerSink> { BEGIN_SINK_MAP(CAnalyzerSink)

END_SINK_MAP()

. . .

}

Then, after you establish a connection with the server, you need to advise as to your implementation of the event interface:

hr = CoCreateInstance( CLSID_SASAnalyzer, NULL,

poAnalyzerSink = new CAnalyzerSink();

// Make sure the COM object corresponding to pUnk implements IProvideClassInfo2 or // IPersist*. Call this method to extract info about source type library, if you // specified only two parameters to IDispEventImpl. hr = AtlGetObjectSourceInterface(m_poSASAnalyzer, &poAnalyzerSink->m_libid,

if ( FAILED(hr) )

return 1;

// Connect the sink and source. m_poSASAnalyzer is the source COM object. hr = poAnalyzerSink->DispEventAdvise(m_poSASAnalyzer, &poAnalyzerSink->m_iid);

if ( FAILED(hr) )

return 1;

// Make sure the Event Handlers have __stdcall calling convention. SINK_ENTRY(IDC_SRCOBJ, 1, OnTraceCreated) SINK_ENTRY(IDC_SRCOBJ, 2, OnStatusReport)

CLSCTX_SERVER, IID_ISASAnalyzer, (LPVOID *)&m_poSASAnalyzer );

&poAnalyzerSink->m_iid, &poAnalyzerSink->m_wMajorVerNum, &poAnalyzerSink->m_wMinorVerNum);

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

10.1.1 _ISASAnalyzerEvents::OnTraceCreated

HRESULT OnTraceCreated (

Fires when a trace is created. This event is a result of ISASAnalyzer::StartRecording

ISASAnalyzer::StopRecording

Parameters

trace Interface pointer to the SASTrace object

Return values

Remarks

Make sure the event handlers have __stdcall calling convention.

Example

VBScript:

<OBJECT

</OBJECT> <P ALIGN=LEFT ID=StatusText></P>

<SCRIPT LANGUAGE="VBScript"> <!-Dim CurrentTrace Sub Analyzer_OnTraceCreated(ByRef Trace)

End Sub

--> </SCRIPT>

C++:

HRESULT __stdcall OnTraceCreated( IDispatch* trace ) {

} . . . return hr; }

[in] IDispatch* trace );

method calls.

ID = Analyzer CLASSID = " clsid: 297CD804-08F5-4A4F-B3BA-779B2654B27C " >

On Error Resume Next Set CurrentTrace = Trace If Err.Number <> 0 Then

MsgBox Err.Number & ":" & Err.Description End If StatusText.innerText = "Trace '" & CurrentTrace.GetName & "' created"

ISASTrace* sas_trace; HRESULT hr; hr = trace->QueryInterface( IID_ISASTrace, (void**)&sas_trace );

if (FAILED(hr)) { _com_error er(hr); if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(),_T("SASTracer client"), MB_OK ); return hr;

and

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

10.1.2 _ISASAnalyzerEvents::OnStatusReport

HRESULT OnStatusReport (

Fires when there is a change in analyzer state or there is a change in progress (percent_done) of analyzer state.

Parameters

subsystem Subsystem sending event has the following values

state Current analyzer state ha s the following values: If the subsystem is

ANALYZERSTATE_IDLE (-1 ) ANALYZERSTATE_WAITING_TRIGGER ( 0 ) – ANALYZERSTATE_RECORDING_TRIGGERED ( 1 ) – ANALYZERSTATE_UPLOADING_DATA ( 2 ) – ANALYZERSTATE_SAVING_DATA ( 3 ) –

If the subsystem is GENERATION_PROGRESS_REPORT:

ANALYZERSTATE_GEN_IDLE ( 400 ) ANALYZERSTATE_GEN_DOWNLOADING ( 401 ) – ANALYZERSTATE_GEN_GENERATING ( 402 ) – ANALYZERSTATE_GEN_PAUSED ( 403 ) –

percent_done Shows the progress of currently performing operation: If the subsystem is

Return values Remarks

Make sure the event handlers have __stdcall calling convention.

[in] short subsystem,

[in] short state,

[in] long percent_done );

RECORDING_PROGRESS_REPORT ( 1 ) – recording subsystem GENERATION_PROGRESS_REPORT ( 2 ) – generation subsystem

RECORDING_PROGRESS_REPORT:

When analyzer state is ANALYZERSTATE_IDLE, this parameter is not applicable.

When analyzer state is ANALYZERSTATE_WAITING_TRIGGER or

ANALYZERSTATE_RECORDING_TRIGGERED,

memory utilization. When analyzer state is

shows the percent of data uploaded. When analyzer state is

shows the percent of data saved. If the subsystem is GENERATION_PROGRESS_REPORT,

this parameter represents current position of script execution.

idle record in progress, anal. waiting for trigger recording in progress, analyzer triggered uploading in progress saving data in progress

idle generator is downloading object code generator is working generator is paused

RECORDING_PROGRESS_REPORT:

this parameter shows analyzer

ANALYZERSTATE_UPLOADING_DATA, this parameter

ANALYZERSTATE_SAVING_DATA, this parameter

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

Example

VBScript:

<OBJECT

</OBJECT> <P ALIGN=LEFT ID=StatusText></P>

<SCRIPT LANGUAGE="VBScript"> <!-Function GetRecordingStatus(ByVal State, ByVal Percent)

End Function

Dim RecordingStatus Sub Analyzer_OnStatusReport(ByVal System, ByVal State, ByVal Percent)

End Sub

--> </SCRIPT>

ID = Analyzer CLASSID = "clsid:0B179BB8-DC61-11D4-9B71-000102566088" >

Select Case State

Case -1: GetRecordingStatus = "Idle"

Case 0: GetRecordingStatus = "Recording - Waiting for trigger"

Case 1: GetRecordingStatus = "Recording - Triggered"

Case 2: GetRecordingStatus = "Uploading"

Case 3: GetRecordingStatus = "Saving Data"

Case Else: GetRecordingStatus = "Invalid recording status" End Select GetRecordingStatus = GetRecordingStatus & ", " & Percent & "% done"

Select Case System

Case 1 RecordingStatus = GetRecordingStatus( State, Percent ) End Select

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

C++:

#define RECORDING_PROGRESS_REPORT ( 1 )

#define ANALYZERSTATE_IDLE ( -1 ) #define ANALYZERSTATE_WAITING_TRIGGER ( 0 ) #define ANALYZERSTATE_RECORDING_TRIGGERED ( 1 ) #define ANALYZERSTATE_UPLOADING_DATA ( 2 ) #define ANALYZERSTATE_SAVING_DATA ( 3 )

HRESULT __stdcall OnStatusReport(short subsystem, short state, long percent_done) {

}

void UpdateRecStatus( short state, long percent_done ) {

case ANALYZERSTATE_SAVING_DATA:

default:

}

_stprintf(m_RecordingStatus, _T("%s, done %ld%%"), status_buf, percent_done);

}

switch ( subsystem )

{

case RECORDING_PROGRESS_REPORT:

UpdateRecStatus( state, percent_done ); break;

}

TCHAR buf[1024];

_stprintf( buf, _T("%s"), m_RecordingStatus );

::SetWindowText( m_hwndStatus, buf );

return S_OK;

TCHAR status_buf[64];

switch ( state )

{

case ANALYZERSTATE_IDLE:

_tcscpy( status_buf, _T("Idle") ); break;

case ANALYZERSTATE_WAITING_TRIGGER:

_tcscpy( status_buf, _T("Recording - Waiting for trigger") ); break;

case ANALYZERSTATE_RECORDING_TRIGGERED:

_tcscpy( status_buf, _T("Recording - Triggered") ); break;

case ANALYZERSTATE_UPLOADING_DATA:

_tcscpy( status_buf, _T("Uploading") );

break;

_tcscpy( status_buf, _T("Saving data") );

break;

_tcscpy( status_buf, _T("Unknown") );

break;

LeCroy Corporation Automation API for SAS/SATATracer/Trainer Manual Version 1.11

How to Contact LeCroy

Type of Service Contact

Call for technical support… US and Canada: 1 (800) 909-7112

Worldwide: 1 (408) 727-6600 Fax your questions… Worldwide: 1 (408) 727-6622 Write a letter … LeCroy

Protocol Solutions Group

Customer Support

3385 Scott Blvd.

Santa Clara, CA 95054 Send e-mail… support@CATC.com Visit the LeCroy web site… http://www.lecroy.com/

Teledyne SAS-SATA User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Copyright

Contents

1 Introduction

1.1 System Requirements

1.2 Support Resources

1.3 Setting Up Automation for Local Use

1.4 Setting Up Automation for Remote Use

2 SASTracer/SATracer Object Model

3 SASAnalyzer Object

3.1 ISASAnalyzer Interface

3.1.1 ISASAnalyzer::GetVersion

3.1.2 ISASAnalyzer::OpenFile

3.1.3 ISASAnalyzer::StartGeneration

3.1.4 ISASAnalyzer::StopGeneration

3.1.5 ISASAnalyzer::StartRecording

3.1.6 ISASAnalyzer::StopRecording

3.1.7 ISASAnalyzer::MakeRecording

3.1.8 ISASAnalyzer::LoadDisplayOptions

3.1.9 ISASAnalyzer::GetRecordingOptions

3.1.10 ISASAnalyzer::ResumeGeneration

3.1.11 ISASAnalyzer::Attach

3.1.12 ISASAnalyzer::Detach

4 SASTrace Object

4.1 ITrace Interface

4.1.1 ITrace::GetName

4.1.2 ITrace::ApplyDisplayOptions

4.1.3 ITrace::Save

4.1.4 ITrace::ExportToText

4.1.5 ITrace::Close

4.1.6 ITrace::ReportFileInfo

4.1.7 ITrace::ReportErrorSummary

4.1.8 ITrace::GetPacket

4.1.9 ITrace::GetPacketsCount

4.1.10 ITrace::GetTriggerPacketNum

4.1.11 ITrace::AnalyzerErrors

4.2 ISASTrace Interface

4.2.1 ISASTrace::GetBusPacket

4.3 ISASVerificationScript Interface

4.3.1 ISASVerificationScript::RunVerificationScript

4.3.2 ISASVerificationScript:: GetVScriptEngine

5 SASRecOptions Object

5.1 IRecOptions Interface

5.1.1 IRecOptions::Load

5.1.2 IRecOptions::Save

5.1.3 IRecOptions::SetRecMode

5.1.4 IRecOptions::SetBufferSize

5.1.5 IRecOptions::SetPostTriggerPercentage

5.1.6 IRecOptions::SetTriggerBeep

5.1.7 IRecOptions::SetSaveExternalSignals

5.1.8 IRecOptions::SetTraceFileName

5.1.9 IRecOptions::Reset

5.2 ISASRecOptions Interface

6 SASPacket Object

6.1 IPacket Interface

6.1.1 IPacket::GetTimestamp

6.2 ISASPacket Interface

6.2.1 IPacket::GetPacketData

6.2.2 IPacket::GetDirection

6.2.3 IPacket::GetErrors

7 SASTraceErrors Object

7.1 ISASAnalyzerErrors Dispinterface

7.1.1 ISASAnalyzerErrors::get_Item

7.1.2 ISASAnalyzerErrors::get_Count

8 SASVScriptEngine Object

8.1 IVScriptEngine Interface

8.1.1 IVScriptEngine::VScriptName

8.1.2 IVScriptEngine::Tag

8.1.3 IVScriptEngine::RunVScript

8.1.4 IVScriptEngine::RunVScriptEx

8.1.5 IVScriptEngine::LaunchVScript

8.1.6 IVScriptEngine::Stop

8.1.7 IVScriptEngine::GetScriptVar

8.1.8 IVScriptEngine::SetScriptVar

9 SASVScriptEngine Object Events

9.1 _IVScriptEngineEvents Interface

9.1.1 IVScriptEngineEvents::OnVScriptReportUpdated