Teledyne SAS-SATA User Manual

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;

+ 65 hidden pages

Teledyne SAS-SATA 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