1. science
2. engineering

Automation API for Teledyne LeCroy SAS/
SATA Protocol Suite
Reference Manual
Document Version 1.8
SAS/SATA Protocol Suite software version 5.70
Generated: April 6, 2015, 09:07 Teledyne LeCroy Protocol Solutions Group Trademarks and Servicemarks:
Teledyne LeCroy, Teledyne LeCroy Protocol Solutions Group, CATC, SASSuite, SATASuite, SASTracer, SATracer, SASTrainer, SATrainer, SASTracker and Avalanche are trademarks of Teledyne LeCroy. Microsoft, Windows, Windows 2000, and Win‐
dows XP are registered trademarks of Microsoft Inc. Intel and Pentium are registered trademarks of Intel Corporation.
All other trademarks and registered trademarks are property of their respective owners.
THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL INFORMATION, EXAMPLES AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE REPRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS ARE FULLY RESPONSIBLE FOR THEIR APPLICATION OF ANY PRODUCTS.
THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN INFORMATION THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT Teledyne LeCroy FOR A COPY.
© 2012 Teledyne LeCroy, Inc. All rights reserved.
This document may be printed and reproduced without additional permission, but all copies should contain this copyright notice.
WEEE Program Teledyne LeCroy
3385 Scott Blvd.
Santa Clara, CA 95054
TEL: 800‐909‐7112 (USA and Canada)
TEL: 408‐653‐1260 (worldwide)
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
ii
Contents
Introduction................................................................................................................................... 1
System Requirements .....................................................................................................................................1
Support Resources .........................................................................................................................................1
Setting Up Automation for Local Use ............................................................................................................2
Setting Up Automation for Remote Use ........................................................................................................2
Teledyne LeCroy SAS/SATA Protocol Suite COM API Object Model ...................................... 2
SASAnalyzer Object ..................................................................................................................... 4
ISASAnalyzer Interface ...................................................................................................................................5
ISASAnalyzer::GetBoardPlatform .......................................................................................................6
ISASAnalyzer::GetVersion ...................................................................................................................7
ISASAnalyzer::OpenFile .......................................................................................................................9
ISASAnalyzer::StartGeneration .........................................................................................................10
ISASAnalyzer::StopGeneration .........................................................................................................11
ISASAnalyzer:: StartGenerationByPort ............................................................................................12
ISASAnalyzer:: StopGenerationByPort .............................................................................................13
ISASAnalyzer:: GetTrainerExitCode ..................................................................................................13
ISASAnalyzer::StartRecording ..........................................................................................................14
ISASAnalyzer::StopRecording ...........................................................................................................16
ISASAnalyzer::MakeRecording ..........................................................................................................18
ISASAnalyzer::IsRunning ...................................................................................................................20
ISASAnalyzer::LoadDisplayOptions .................................................................................................22
ISASAnalyzer::LoadGlobalGenOptions ............................................................................................23
ISASAnalyzer::GetRecordingOptions ...............................................................................................24
ISASAnalyzer::ResumeGeneration ...................................................................................................26
ISASAnalyzer::ActivateDevice ...........................................................................................................27
ISASAnalyzer::ActivateDeviceByBoard ............................................................................................28
ISASAnalyzer::DeactivateDevice .......................................................................................................29
ISASAnalyzer::SetScenarioToPort ....................................................................................................30
ISASAnalyzer:: StartScenario ............................................................................................................32
ISASAnalyzer:: StopScenario ............................................................................................................34
ISASAnalyzer:: SetPortConfiguration ...............................................................................................36
ISASAnalyzer:: LoadPreEmphasisSignalFile ...................................................................................40
ISASAnalyzer::SetTraceFileName .....................................................................................................40
ISASAnalyzer::DoSelfTest ..................................................................................................................41
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
iii
Teledyne LeCroy
Contents
ISASAnalyzer ::SetVSELogToSaveAutomatically ............................................................................42
ISASAnalyzer ::SetVSELogModeToMultipleFile ..............................................................................43
ISASAnalyzer ::SetVSELogModeToSingleFile .................................................................................44
ISASAnalyzer ::SetVSELogModeToTraceRelativePath ...................................................................45
SierraSASAnalyzer Object ......................................................................................................... 46
SierraSTAnalyzer Object............................................................................................................ 47
STXSASAnalyzer Object ............................................................................................................ 48
STXSTAnalyzer Object ............................................................................................................... 49
SASTrace Object......................................................................................................................... 50
ITrace Interface ..............................................................................................................................................51
ITrace::GetName .................................................................................................................................52
ITrace::ApplyDisplayOptions .............................................................................................................54
ITrace::Save .........................................................................................................................................56
ITrace::GetPacketRow ........................................................................................................................58
ITrace::ExportToText ..........................................................................................................................59
ITrace::ExportToExcel ........................................................................................................................64
ITrace::Close .......................................................................................................................................65
ITrace::ReportFileInfo .........................................................................................................................66
ITrace::ReportErrorSummary ............................................................................................................67
ITrace::GetPacket ................................................................................................................................70
ITrace::GetPacketsCount ...................................................................................................................73
ITrace::GetTriggerPacketNum ...........................................................................................................75
ITrace::AnalyzerErrors .......................................................................................................................76
ISASTrace Interface.......................................................................................................................................78
ISASTrace::GetBusPacket .................................................................................................................79
ISASVerificationScript Interface ..................................................................................................................80
ISASVerificationScript::RunVerificationScript .................................................................................81
ISASVerificationScript:: GetVScriptEngine ......................................................................................84
SASRecOptions Object .............................................................................................................. 86
IRecOptions Interface ...................................................................................................................................86
IRecOptions::Load ..............................................................................................................................87
IRecOptions::Save ..............................................................................................................................88
IRecOptions::SetRecMode .................................................................................................................89
IRecOptions::SetBufferSize ...............................................................................................................90
IRecOptions::SetPostTriggerPercentage .........................................................................................91
IRecOptions::SetTriggerBeep ............................................................................................................92
IRecOptions::SetSaveExternalSignals ..............................................................................................93
IRecOptions::SetTraceFileName .......................................................................................................94
IRecOptions::Reset ............................................................................................................................95
ISASRecOptions Interface ............................................................................................................................95
iv
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Contents
Teledyne LeCroy
SASPacket Object....................................................................................................................... 96
IPacket Interface ............................................................................................................................................96
IPacket::GetTimestamp ......................................................................................................................97
ISASPacket Interface.....................................................................................................................................98
IPacket::GetPacketData ......................................................................................................................99
IPacket::GetDirection ........................................................................................................................103
IPacket::GetErrors ............................................................................................................................104
IPacket:: GetLinkNumber .................................................................................................................105
IPacket:: GetFrameType ...................................................................................................................106
IPacket:: GetTotalDwords ................................................................................................................107
SASTraceErrors Object............................................................................................................ 108
ISASAnalyzerErrors Dispinterface.............................................................................................................108
ISASAnalyzerErrors::get_Item .........................................................................................................109
ISASAnalyzerErrors::get_Count ......................................................................................................110
SASVScriptEngine Object........................................................................................................ 112
IVScriptEngine Interface .............................................................................................................................113
IVScriptEngine::RunVScript .............................................................................................................114
IVScriptEngine::RunVScriptEx ........................................................................................................115
IVScriptEngine::LaunchVScript .......................................................................................................117
IVScriptEngine::Stop ........................................................................................................................118
SASVScriptEngine Object Events........................................................................................... 119
_IVScriptEngineEvents Interface ...............................................................................................................119
IVScriptEngineEvents::OnVScriptReportUpdated .........................................................................123
IVScriptEngineEvents::OnVScriptFinished ....................................................................................124
IVScriptEngineEvents::OnNotifyCount ...........................................................................................126
SASAnalyzer Object Events .................................................................................................... 128
_ISASAnalyzerEvents Dispinterface..........................................................................................................128
_ISASAnalyzerEvents::OnTraceCreated .........................................................................................130
_ISASAnalyzerEvents::OnStatusReport .........................................................................................132
How to Contact Teledyne LeCroy .......................................................................................... 136
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
v
Teledyne LeCroy
vi
Contents
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Introduction
The Teledyne LeCroy SAS/SATA Protocol Suite software provides a rich COM/Automation API to the most important functionalities of the Teledyne LeCroy Sierra/STX Protocol Analyzers and Teledyne LeCroy Sierra/STX Exercisers for implementation of automated programs for complicated testing, development, and debugging. The "dual" nature of the interfaces provided makes it easy to use the Teledyne LeCroy SAS/SATA Protocol Suite COM API in the different Integrated Development Environments (IDE) that support the COM architecture. Special support for typeless script languages (such as VB and JavaScript), while overriding 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 Teledyne LeCroy SAS/SATA Protocol Suite an attractive tool for automating and speeding many engineering processes.
System Requirements
The Automation API was introduced with the following release: 

Teledyne LeCroy SAS/SATA Protocol Suite software 2.60/4.60. This document covers the functionality available in Teledyne LeCroy SAS/SATA Protocol Suite 4.0 and above.
Support Resources
As new functionalities are added to the API, not all of them are supported by older versions of the analyzer software. For newer releases of analyzer software, please refer to the Teledyne LeCroy web site: www.teledynelecroy.com
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
1
Teledyne LeCroy
Teledyne LeCroy SAS/SATA Protocol Suite COM API Object Model
Setting Up Automation for Local Use
To run Automation on the Sierra/STX Host Controller (the host machine attached to the Sierra/STX), 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. To use the Teledyne LeCroy SAS/SATA Protocol Suite COM API, the application should be registered during the installation process as a COM server in a system registry.
Setting Up Automation for Remote Use
To access Teledyne LeCroy SAS/SATA Protocol Suite COM API remotely over a network, install the application on both server and client systems and accept the Enabling Remote Access option during installation. You can also perform a manual DCOM configuration.
Teledyne LeCroy SAS/SATA Protocol Suite COM API Object Model
The Teledyne LeCroy SAS/SATA 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 Teledyne LeCroy SAS/SATA API object hierarchy: SASAnalyzer. The following object model diagram shows how the objects in the object model fit together:
2
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
Teledyne LeCroy SAS/SATA Protocol Suite COM API Object Model
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.
Object
SASAnalyzer
Interface
ISASAnalyzer _ISASAnalyzerEvents
SASTrace
ITrace
ISASTrace*
ISASVerificationScript*
IRecOptions
ISASRecOptions
IPacket
ISASPacket*
SASRecOptions
SASPacket
SASTraceErrors
ISASAnalyzerErrors*
Description
Represents the Teledyne LeCroy SAS/
SATA Protocol Suite COM API application.
Represents the recorded trace.
Represents recording options.
Represents a single packet of the recorded trace.
Represents the collection of errors that occurred in the recorded trace.
* 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.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
3
Teledyne LeCroy
SASAnalyzer Object
SASAnalyzer Object
The SASAnalyzer object is the top‐level object of the SAS 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
ISASAnalyzer
_ISASAnalyzerEvents
Description
Facilitates recording and traffic generation, opens trace files, and retrieves recording options. Adds advanced generator functionality and retrieves generation options.
Events from SASAnalyzer object.
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;
4
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer Interface
The ISASAnalyzer interface is a dual interface for the SASAnalyzer object.
ISASAnalyzer implements the following methods: 




























GetBoardPlatform
GetVersion
OpenFile
StartGeneration
StopGeneration
StartGenerationByPort
StopGenerationByPort
StartRecording
StopRecording
MakeRecording
IsRunning
LoadDisplayOptions
LoadGlobalGenOptions
GetRecordingsOption
ResumeGeneration
ActivateDevice
ActivateDeviceByBoard
DeactivateDevice
SetScenarioToPort
StartScenario
StopScenario
SetPortConfiguration
GetTrainerExitCode
LoadPreEmphasisSignalFile
SetTraceFileName
SetVSELogToSaveAutomatically
SetVSELogModeToMultipleFile
SetVSELogModeToSingleFile
SetVSELogModeToTraceRelativePath
Note: All API functions work in real mode. They do not work in simulation mode.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
5
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer::GetBoardPlatform
HRESULT GetBoardPlatform([out, retval]int* pnBoardPlatform);
Retrieves the current version of the specified subsystem.
Retrieves connected board platform.
Parameters
None
Return Value
Returns below values for each platform:
34 : Sierra M124
32 : Sierra M122
14 : Sierra M6‐4
12 : Sierra M6‐2
11 : Sierra M6‐1
24 : STX 460, STX 431
22 : STX 231
6
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer::GetVersion
HRESULT GetVersion (
[in] EAnalyzerVersionType version_type,
[out, retval] WORD* analyzer_version );
Retrieves the current version of the specified subsystem.
Parameters
version_type
Subsystem whose version is requested
EAnalyzerVersionType enumerator has the following values:
ANALYZERVERSION_SOFTWARE ( 0 ) Software
analyzer_version
Version of the subsystem queried
ANALYZERVERSION_SOFTWARE: Upper Byte = Software Major Version, Lower Byte = Software Minor Version
Return Value
ANALYZERCOMERROR_INVALIDVERSIONTYPE
Specified version type is invalid.
Example
WSH:
Set Analyzer = WScript.CreateObject("Lecroy.SASAnalyzer")
SwVersion = Analyzer.GetVersion(0)
MsgBox "Software" & SwVersion
C++:
HRESULT
ISASAnalyzer*
hr;
poSASAnalyzer;
// Create SASAnalyzer object.
if ( FAILED( CoCreateInstance (
CLSID_SASAnalyzer,
NULL, CLSCTX_SERVER,
IID_ISASAnalyzer,
(LPVOID *)&poSASAnalyzer ) )
return;
WORD sw_version;
try
{
sw_version = poAnalyzer->GetVersion( ANALYZERVERSION_SOFTWARE );
}
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;
}
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
7
Teledyne LeCroy
SASAnalyzer Object
TCHAR buffer[20];
_stprintf( buffer, _T("Software version:%d.%d"), HIBYTE(sw_version),
LOBYTE(sw_version) );
8
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer::OpenFile
HRESULT OpenFile (
[in] BSTR file_name,
[out, retval] IDispatch** trace );
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.scs")
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
{
trace = poSASAnalyzer->OpenFile( m_szRecFileName );
}
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;
}
// Query for VTBL interface
ISASTrace* SAS_trace;
hr = trace->QueryInterface( IID_ISASTrace, (LPVOID *)&SAS_trace );
trace->Release();
if( FAILED(hr) )
return;
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
9
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer::StartGeneration
HRESULT StartGeneration (
[in] BSTR gen_file_name);
Starts traffic generation from the file.
Parameters
gen_file_nameString providing the full pathname to the generation file
Return Values
ANALYZERCOMERROR_UNABLEOPENFILE Unable to open file ANALYZERCOMERROR_UNABLESTARTGENERATION Unable to start generation (invalid state, etc.)
Remarks
Example
WSH:
CurrentDir = Left( WScript.ScriptFullName,
InstrRev( WScript.ScriptFullName, “\”))
Set Analyzer = WScript.CreateObject( “Lecroy.SASAnalyzer” )
ret = Analyzer.StartGeneration( CurrentDir & "Input\connect.ssg")
C++:
HRESULT
hr;
ISASAnalyzer* poSASAnalyzer;
TCHAR m_szGenFileName [_MAX_PATH];
// Create SASAnalyzer object.
if ( FAILED( CoCreateInstance(
CLSID_SASAnalyzer,
NULL, CLSCTX_SERVER,
IID_ISASAnalyzer,
(LPVOID *)&poSASAnalyzer ) )
return;
. . .
try
{
poAnalyzer->StartGeneration( m_szGenFileName);
}
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;
}
10
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer::StopGeneration
HRESULT StopGeneration ( );
Stops any generation in progress.
Parameters
Return Values
ANALYZERCOMERROR_UNABLESTARTGENERATION
Unable to stop generation(invalid state, etc.) 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;
}
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
11
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer:: StartGenerationByPort
HRESULT StartGenerationByPort (
[in] BSTR gen_file_name,
[in] int nBoardIndex,
[in] int nPortIndex);
This function runs generation on specified ports.
Parameters
gen_file_name
Specifies the SAS/SATA Protocol Suite file name to load.
nBoardIndex
Zero based index of board. If you have only one board, this parameter should be set to zero.
nPortIndex
Port index where generation should start.
Remarks
You can run generation files on specific ports on the connected board. The difference between this function and the StartGeneration function is that this one starts generation on only specified ports while the StartGeneration function starts generation on all ports.
12
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer:: StopGenerationByPort
HRESULT StopGenerationByPort (
[in] int nBoardIndex,
[in] int nPortIndex);
This function stops generation on specified ports.
Parameters
nBoardIndex
Zero based index of board. If you have only one board, this parameter should be set to zero.
nPortIndex
Port index where generation should stop.
Remarks
You can stop generation files on specific ports on the connected board. The difference between this function and the StopGeneration function is that this one stops generation on only specified ports while the StopGeneration function stops generation on all ports.
ISASAnalyzer:: GetTrainerExitCode
HRESULT GetTrainerExitCode (
[in] int nBoardIndex,
[in] int nPortIndex,
[out, retval] BYTE*pyTrainerExitCode);
This function returns SAS/SATA Protocol Suite exit code by board and port index.
Parameters
nBoardIndex
Zero based index of board. If you have only one board, this parameter should be set to zero.
nPortIndex
Specifies the port index.
Remarks
Receives the board and port index and retrieves the exit code of the last running generation. This function is normally called after generation is stopped to examine the exit code of generation execution.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
13
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer::StartRecording
HRESULT StartRecording (
[in] BSTR ro_file_name );
Starts recording with specified recording options.
Parameters
ro_file_name
String providing the full pathname to the recording options file. If the parameter is omitted, then recording starts with default recording options.
Return Values
ANALYZERCOMERROR_UNABLESTARTRECORDING Unable to start recording
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 the ISASAnalyzer Interface).
The recording options file is the file with extension .sac created by the SAS/SATA Protocol Suite application. You can create this file when you select File –> Protocol Analyzer… from the SAS Protocol Suite application menu, change the recording options in the Protocol Analyzer project, and select the Save… button.
Example
VBScript:
<OBJECT
RUNAT=Server
ID = Analyzer
CLASSID = " clsid: 297CD804-08F5-4A4F-B3BA-779B2654B27C
"
>
</OBJECT>
<INPUT TYPE=TEXT
VALUE="" NAME="TextRecOptions">
<SCRIPT LANGUAGE="VBScript">
<!-Sub BtnStartRecording_OnClick
On Error Resume Next
Analyzer.StartRecording TextRecOptions.value
If Err.Number <> 0 Then
MsgBox Err.Number & ":" & Err.Description
End If
End Sub
-->
</SCRIPT>
C++:
14
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer* sas_analyzer;
BSTR
ro_file_name;
. . .
try
{
sas_analyzer->StartRecording( ro_file_name )
}
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;
}
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
15
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer::StopRecording
HRESULT StopRecording (
[in] BOOL abort_upload );
Stops recording started by the ISASAnalyzer::StartRecording method.
Parameters
abort_upload
TRUE If the caller wants to abort the upload. No trace file is created.
FALSEIf the caller wants to upload the recorded trace.
Return Values
ANALYZERCOMERROR_UNABLESTOPRECORDING Error stopping recording
Remarks
Stops recording started by the StartRecording method. The event is issued when recording is actually stopped (by the ISASAnalyzer Interface), if the parameter of method call was FALSE.
16
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object
Example (for SAS/SATA Protocol Suite application)
VBScript:
<OBJECT
RUNAT=Server
ID = Analyzer
CLASSID = "clsid: 0B179BB7-DC61-11d4-9B71-000102566088"
>
</OBJECT>
<SCRIPT LANGUAGE="VBScript">
<!-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
{
sas_analyzer->StopRecording( FALSE )
}
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;
}
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
17
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer::MakeRecording
HRESULT MakeRecording (
[in] BSTR ro_file_name,
[out, retval] IDispatch** trace );
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 Unable to start recording
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.
The recording options file is the file with extension .sac created by the SAS/SATA Protocol Suite application. You can create this file when you select File –> Protocol Analyzer… from the SAS Protocol Suite application menu, change the recording options in the Protocol Analyzer project, and select the Save… button.
Example
WSH:
CurrentDir = Left(WScript.ScriptFullName,
InstrRev(WScript.ScriptFullName, "\"))
Set Analyzer =
WScript.CreateObject("Lecroy.SASAnalyzer")
Set Trace = Analyzer.MakeRecording (CurrentDir &
"Input\test_ro.sac")
C++:
IDispatch*
trace;
ISASAnalyzer* sas_analyzer;
BSTR
ro_file_name;
HRESULT
hr;
. . .
18
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object
try
{
trace = sas_analyzer->MakeRecording( ro_file_name )
}
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;
}
// Query for VTBL interface
ISASTrace* sas_trace;
hr = trace->QueryInterface( IID_ISASTrace, (LPVOID
*)&sas_trace );
trace->Release();
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
19
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer::IsRunning
HRESULT IsRunning (
[in] int nFunctionality,
[out, retval] BOOL* pbIsRunning)
This function returns the running status of projects.
Parameters
nFunctionality This parameter specifies the functionality of the project that you want to check its running status. You should set this parameter as below:
0
: to check all available functionalities status at once
1
: to check Analyzer running status
2
: to check Infusion running status
3
: to check Sierra/STX running status
4
: to check whether Target/Device emulator is active or not
5
: to check Initiator emulator running status
Return Value
pbIsRunning
This parameter returns the running status
Remarks
By calling this function, you will be able to check whether the Analyzer, Infusion, Sierra/STX, Target/Device Emulator and Initiator Emulator are running or not. If you want to check all these functionalities at once, you have to set the first parameter (nFunctionality) to zero.
Example
VBScript:
Dim bIsRunning
Dim Timer
Dim TimeOut
Timer = 0
bIsRunning = TRUE
'Set waiting time out to 60 Seconds
TimeOut= 60 'seconds
'Wait for project to stop or timeout happen
While bIsRunning <> FALSE And Timer < TimeOut
20
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object
'bIsRunning = Analyzer.IsRunning(0)'Checks all
bIsRunning = Analyzer.IsRunning(1)'checks Analyzer
'bIsRunning = Analyzer.IsRunning(2)'Checks Infusion
'bIsRunning = Analyzer.IsRunning(3)'Checks Trainer
'bIsRunning = Analyzer.IsRunning(4)'Checks Target
'bIsRunning = Analyzer.IsRunning(5)'checks Initiator
WScript.Sleep(1000)'Sleep 1 Second
Timer = Timer + 1
MySTATS.ReportText ("Project is running, Time = " &
CSTR(Timer) & "second(s)")
Wend
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
21
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer::LoadDisplayOptions
HRESULT LoadDisplayOptions (
[in] BSTR do_file_name
[in] short do_layers );
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:
LAYER_LINK (0x0001) //00000000 00000001
LAYER_IDLE (0x0002) //00000000 00000010
LAYER_TRANSPORT (0x0004) //00000000 00000100
LAYER_ATA_COMMAND (0x0008) //00000000 00001000
LAYER_SCSI_COMMAND (0x0010) //00000000 00010000
LAYER_SMP_COMMAND (0x0020) //00000000 00100000
LAYER_TASK_COMMAND (0x0040) //00000000 01000000
LAYER_DATA_REPORT (0x0080) //00000000 10000000
LAYER_QUEUE_COMMAND (0x0100) //00000001 00000000
LAYER_OOB_SEQUENCE (0x0200) //00000010 00000000
Return Values
ANALYZERCOMERROR_UNABLELOADDO Unable to load the display options file
Remarks
Use this method 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 .sfl created by the SAS/SATA Protocol Suite application by the filter dialog.
Example
See ITrace::ApplyDisplayOptions. 22
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer::LoadGlobalGenOptions
HRESULT LoadGlobalGenOptions (
[in] BSTR bstrGenOptionsFile,
[out, retval] BOOL* pbRetval)
This function loads the global generator options.
Parameters
bstrGenOptionsFile String providing the full pathname to a generator options file;
Return Value
pbRetval
This function returns a BOOL value. This value shows whether the load is done successfully or not. Remarks
If any SAS/SATA Protocol Suite file has its own generator options, calling this function will not change its options otherwise, it will load the specified options file and will set it as its generator options.
Example
VBScript:
On Error Resume Next
Analyzer.LoadGlobalGenOptions("E:\MyGenOptions.gen")
If Err.Number <> 0 Then
MsgBox Err.Number & ":" & Err.Description
End If
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
23
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer::GetRecordingOptions
HRESULT GetRecordingOptions (
[out, retval] IDispatch** recording_options );
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
{
rec_opt = poSASAnalyzer->GetRecordingOptions();
}
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;
}
24
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object
// 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;
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
25
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer::ResumeGeneration
HRESULT ResumeGeneration ( )
Resumes generation if it was previously paused.
Return Value
Remarks
Example
C++:
ISASAnalyzer* poAnalyzer;
. . .
try
{
poAnalyzer->ResumeGeneration();
}
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;
}
26
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer::ActivateDevice
HRESULT ActivateDevice (
[in] BSTR bstrFileName)
This function activates the target/device emulator.
Parameters
bstrFileName
Specifies the path of the target/device emulator project file.
Remarks
Activates the specified project. If device is already activated, an error will be returned. Note that the port configuration will be set by the SetPortConfiguration function.
If no port configuration is set, the default value is the running configuration.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
27
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer::ActivateDeviceByBoard
HRESULT ActivateDeviceByBoard (
[in] BSTR bstrFileName,
[in] nBoardIndex)
This function activates the target/device emulator.
Parameters
bstrFileName
BoardIndex
(zero base)
Remarks
This activates the target/device emulator on the given board index using the give target/
device project. If the device is already activated on the given board, an error will be returned. Notes
1. You should set the port configuration by the SetPortConfiguration function before calling ActivateDeviceByBoard. If no port configuration is set, the default value is the running configuration.
2. This function is applicable when you want to activate the target/device emulator when you cascade Seirra (or STX) boards. When using only one Sierra (or STX) board, you can call the ActivateDevice function.
28
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer::DeactivateDevice
HRESULT DeactivateDevice ()
This function deactivates the already activated target/device emulator.
Remarks
Deactivates the specified project. If device is not already activated, no action will be done, and nothing will be affected.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
29
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer::SetScenarioToPort
HRESULT SetScenarioToPort (
[in] int nBoardIndex
[in]int nPortIndex,
[in] BSTR bstrLibraryName,
[in] BSTR bstrScenarioName,
[out, retval] int* pnErrorCode);
This function assigns a scenario from mentioned library to a specific port of the board.
Parameters
nBoardIndex
Zero based index of board. If you have only one board, this parameter should be set to zero.
nPortIndex
Port index that the scenario should assign
bstrLibraryName
Specifies the name of the library bstrScenarioName Name of the scenario that will assigned to the specified port.
pnErrorCode
Pointer to an integer which contains an error code if one or more error(s) has occurred.
Return Values
ANALYZERCOMERROR_UNABLE_TO_START_JAMMER Software is in simulation mode
ANALYZERCOMERROR_UNABLESTARTRECORDING Failed to get LeCroy Scenario Manager
Failed to open LeCroy script local file database
Failed to get LeCroy Configure Manager
Failed to create LeCroy script local file database
Failed to load local file scenario
Failed to load local file scenario because invalid scenario
There is no scenario in local file.
Failed to upload the scenario to InFusion device
Failed to upload the scenario to InFusion device
Failed to upload the scenario to InFusion device
Failed to set selected the scenario from InFusion device
Can not find scenario in local file database
Remarks
Before a scenario is started, you must assign it to the available ports using this function. 30
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object
Example
C++:
HRESULT
IFCAnalyzer*
hr;
poFCAnalyzer;
// Create FCAnalyzer object.
if ( FAILED( CoCreateInstance(
CLSID_FCAnalyzer,
NULL, CLSCTX_SERVER,
IID_IFCAnalyzer,
(LPVOID *)&poFCAnalyzer ) )
return;
// Open trace file.
IDispatch* rec_opt;
try
{
poFCAnalyzer-> SetScenarioToPort(m_yUnitIndex,
m_yPortIndex,
m_strLibPath.AllocSysString(),
m_strScenarioName.AllocSysString());
}
catch (_com_error& er)
{
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(), _T("FCSuite
client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("FCSuite
client"), MB_OK );
return 1;
}
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
31
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer:: StartScenario
HRESULT StartScenario (
[in] int nBoardIndex
[in]int nPortIndex);
This function runs the assigned scenario of the port.
Parameters
nBoardIndex Zero based index of board. If you have only one board, this parameter should be set to zero.
nPortIndex
Port index where the scenario should start.
Return Values
ANALYZERCOMERROR_UNABLE_TO_START_JAMMER
Software is in simulation mode
Device does not have sufficient license to run InFusion
Failed to start the Jammer session
Remarks
Starts scenarios on ports. You must call this function for every port of any board on which you want to run scenarios. The port configuration is set by the SetPortConfiguration function.
32
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object
Example
C++:
HRESULT
IFCAnalyzer*
hr;
poFCAnalyzer;
// Create FCAnalyzer object.
if ( FAILED( CoCreateInstance(
CLSID_FCAnalyzer,
NULL, CLSCTX_SERVER,
IID_IFCAnalyzer,
(LPVOID *)&poFCAnalyzer ) )
return;
// Open trace file.
IDispatch* rec_opt;
try
{
poFCAnalyzer->StartScenario(m_yUnitIndex,
m_yPortIndex);
}
catch (_com_error& er)
{
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(), _T("FCSuite
client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("FCSuite
client"), MB_OK );
return 1;
}
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
33
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer:: StopScenario
HRESULT StopScenario (
[in] int nBoardIndex
[in]int nPortIndex);
This function stops the scenario of the specified port.
Parameters
nBoardIndex Zero based index of board. If you have only one board, this parameter should be set to zero.
nPortIndex
Port index where scenario should start.
Return Values
ANALYZERCOMERROR_UNABLE_TO_STOP_JAMMER
Software is in simulation mode
Failed to stop the Jammer session
Remarks
Stops scenarios. You must call this function for every port of any board on which you want to stop scenarios. Example
C++:
HRESULT
IFCAnalyzer*
hr;
poFCAnalyzer;
// Create FCAnalyzer object.
if ( FAILED( CoCreateInstance(
CLSID_FCAnalyzer,
NULL, CLSCTX_SERVER,
IID_IFCAnalyzer,
(LPVOID *)&poFCAnalyzer ) )
return;
34
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object
// Open trace file.
IDispatch* rec_opt;
try
{
poFCAnalyzer->StopScenario(m_yUnitIndex, m_yPortIndex);
}
catch (_com_error& er)
{
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(), _T("FCSuite
client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("FCSuite
client"), MB_OK );
return 1;
}
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
35
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer:: SetPortConfiguration
HRESULT SetPortConfiguration (
[in] int nBoardIndex
[in]int nPortConfiguration);
This function specifies port configuration by board index.
Parameters
nBoardIndex
Zero based index of board. If you have only one board, this parameter should be set to zero.
nPortConfiguration
DeviceConfigurationTypeEnum enumeration specifies functionality of ports for connected board:
DeviceConfigurationTypeEnum enumeration:
//‐‐‐‐‐‐‐‐‐Sierra M6‐4‐‐‐‐‐‐‐‐‐‐‐‐‐
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
36
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object
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
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
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
37
Teledyne LeCroy
SASAnalyzer Object
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
//‐‐‐‐‐‐‐‐‐Performance ‐‐‐‐‐‐‐‐‐‐‐‐‐
DEVICE_CONFIG_PA_PA_PA_PA = 85,
//‐‐‐‐‐‐‐‐‐Sierra M6‐4‐‐‐‐‐‐‐‐‐‐‐‐‐
DEVICE_CONFIG_T_T_A_A = 86,
DEVICE_CONFIG_A_A_T_T = 87,
DEVICE_CONFIG_AT_AT_0_0 = 88,
DEVICE_CONFIG_0_0_AT_AT = 89,
38
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object
//‐‐‐ Sierra M6‐2 Configurations ‐‐‐‐
DEVICE_CONFIG_AHE_0_0_0 = 90,
DEVICE_CONFIG_0_AHE_0_0 = 91,
DEVICE_CONFIG_ADE_0_0_0 = 92,
DEVICE_CONFIG_0_ADE_0_0 = 93,
// ‐‐‐‐‐‐ DE & HE together ‐‐‐‐‐‐‐‐
DEVICE_CONFIG_AHE_0_ADE_0 = 100,
DEVICE_CONFIG_ADE_0_AHE_0 = 101,
DEVICE_CONFIG_DE_DE_HE_HE = 102,
DEVICE_CONFIG_HE_HE_DE_DE = 103,
DEVICE_CONFIG_HE_DE_HE_DE = 104,
DEVICE_CONFIG_HE_DE_0_0 = 105,
DEVICE_CONFIG_HE_DE_A_A = 106,
DEVICE_CONFIG_AT_0_AT_0 = 108,
DEVICE_CONFIG_T_0_JA_0 = 109,
DEVICE_CONFIG_AJA_0_AJA_0 = 110,
DEVICE_CONFIG_0_AHE_0_0 = 111,
DEVICE_CONFIG_0_AJA_0_AJA = 112,
Remarks
Before you run any function on your board, you must specify its port configuration before running Analyzer, Exerciser, Sierra/STX, or InFusion. Port configuration specifies what functionality should be considered for each port of the specified board.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
39
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer:: LoadPreEmphasisSignalFile
HRESULT LoadPreEmphasisSignalFile(
[in] BSTR bstrPreEmphasisSignalFile,
[out, retval] pbRetval);
This function gets the file of pre emphasis signal and loads it to the board.
Parameters
bstrPreEmphasisSignalFile
Specifies the file name of pre emphasis signal.
Return Values
True if it loads the file successfully. False if it fails.
Remarks
The Pre emphasis dialog in the SAS/SATA software gives the probability of saving the signal settings into a file. By calling this function, you can load that file into the board without running the SAS/SATA software.
ISASAnalyzer::SetTraceFileName
HRESULT SetTraceFileName ([in] BSTR bstrTraceFileName)
This function sets the name of next running generated trace file.
Parameters
bstrTraceFileName
String providing the name of the trace file
Remarks
Calling this function sets the next running generated trace file name. If you do not call this function, then the trace file name will be the same as the Analyzer project file name. This function helps you create different trace files when you want to run a project several times with different settings (such as connection speed). Before any run, call this function to change the trace file name.
Example
VBScript:
Analyzer.SetTraceFileName("MyTrace")
If Err.Number <> 0 Then
MsgBox Err.Number & ":" & Err.Description
End If
40
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer::DoSelfTest
HRESULT DoSelfTest (
[in] int SelfTestType,
[out, retval] int* pnResult)
This function is used to run the self test on the currently connected board and report its faults and defects.
Parameters
SelfTestType : This parameter specifies the type of the self test. This type can be one of these numbers:
1
: SELF_TEST_MEMORY 2
: SELF_TEST_CLOCK 3
: SELF_TEST_BUZZER_LED
4
: SELF_TEST_VIRTEX_VIRTEX_BUS_TEST
5
: SELF_TEST_MARVELL
6
:SELF_TEST_VITESSE_VIRTESSE_BUS_TEST
7
: SELF_TEST_VITESSE_EXTERNAL_LOOP_BACK
8
: SELF_TEST_VITESSE_EXPANTION_CARD
0 value for SelfTestType means doing the following tests:
SELF_TEST_MEMORY SELF_TEST_CLOCK SELF_TEST_VIRTEX_VIRTEX_BUS_TEST SELF_TEST_MARVELL SELF_TEST_VITESSE_VIRTESSE_BUS_TEST SELF_TEST_VITESSE_EXTERNAL_LOOP_BACK
SELF_TEST_VITESSE_EXPANTION_CARD
Return Value
pnResult
A zero value for this parameter shows that the self test has passed and a non‐zero value shows that the self test failed. When the self test fails it means that an error or problem has been detected. To get more information on the detected problem you can view the Self Test Log file. It is in the User folder of the software. Remarks
Doing a self test on SELF_TEST_BUZZER_LED and SELF_TEST_VITESSE_EXPANTION_CARD needs user interaction during test..
Example
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
41
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer ::SetVSELogToSaveAutomatically
HRESULT SetVSELogToSaveAutomatically (
[in] BOOL bSaveAutomatically,
[out,retval] BOOL *pResult);
This function sets the flag for automatically saving, or not saving, VSE log files.
Parameters
bSaveAutomatically
TRUE = Saves the log file automatically after a VSE script run.
FALSE = Does not save the log file after a VSE script run.
Return Values
pResult
TRUE = Flag set successfully.
FALSE = Could not set the flag.
Remarks
Default value is retrieved from the VSE settings. Note that, after installation, the VSE settings have no value for the flag. To have a default value, you must enter the value manually in the VSE settings.
Before using this command to automatically save log files, you must make sure that the VSE settings have the path to the folder in which to save log files. Note that, after installation, the VSE settings have no value for the path. To set the path, you can enter the value manually in the VSE settings. Alternatively, before calling this function, you can run the SetVSELogModeToMultipleFile command to set the folder path. If the SetVSELogToSaveAutomatically function parameter is set to FALSE, the system does not save any log files, regardless of any other method settings.
Example
VBScript:
Analyzer.SetVSELogToSaveAutomatically(1)
Analyzer.SetVSELogToSaveAutomatically(0)
42
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer ::SetVSELogModeToMultipleFile
HRESULT SetVSELogModeToMultipleFile (
[in] BSTR bstrLogFolderPath,
[out,retval] BOOL *pResult);
This function sets the folder path for saving log files from VSE script runs. Parameters
bstrLogFolderPath
String providing the folder path for the saved log file
Return Values
pResult
TRUE = Folder path set successfully.
FALSE = Could not set the folder path.
Remarks
Default value is retrieved from the VSE settings. Note that, after installation, the VSE settings have no value for the path. To have a default value, you must enter the value manually in the VSE settings.
If a value is set in the ATS script before this method is called, the method will override that setting. The folder path must exist. If the folder path does not exist, the method returns FALSE and shows the error in the ATS output.
Note: This function saves all log files into the directory specified by the function parameter. Example
VBScript:
Analyzer.SetVSELogModeToMultipleFile("D:\AvailableFolde
rPath\")
If Err.Number <> 0 Then
MsgBox Err.Number & ":" & Err.Description
End If
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
43
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer ::SetVSELogModeToSingleFile
HRESULT SetVSELogModeToSingleFile (
[in] BSTR bstrLogFilePath,
[out,retval] BOOL *pResult);
This function set mode to save all logs for VSE scripts in single file and set the file log path.
Parameters
bstrLogFolderPath
String providing the folder path for the save log file
Return Values
pResult
TRUE = file path set successfully.
FALSE = could not set the file path.
Remarks
Default value is retrieve from VSE setting. It will over ride any other log setting if there is any on the ATS script before this method. The folder path must exist, and the file name should be valid otherwise the method return false and show the error in the ATS output.
Example
VBScript:
Analyzer.SetVSELogModeToSingleFile("D:\VSELogFileName.
log")
If Err.Number <> 0 Then
MsgBox Err.Number & ":" & Err.Description
End If
44
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object
ISASAnalyzer ::SetVSELogModeToTraceRelativePath
HRESULT SetVSELogModeToTraceRelativePath (
[out,retval] BOOL *pResult);
This function set mode to save all logs for VSE scripts in separate files and set the folder path to the corresponding Trace file Path.
Return Values
pResult
TRUE = set successfully.
FALSE = could not set path.
Remarks
Default value is retrieve from VSE setting. It will over ride any other log setting if there is any on the ATS script before this method. Example
VBScript:
Analyzer.SetVSELogModeToTraceRelativePath()
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
45
Teledyne LeCroy
SierraSASAnalyzer Object
SierraSASAnalyzer Object
The SierraSASAnalyzer object is the Sierra version of the SASAnalyzer object in the SAS software. This object is delivered by the SAS software automation API. All functionality is the same as the SASAnalyzer object. The Class ID and App ID for the SierraSASAnalyzer object are the following:
Class ID: SierraSASAnalyzer 8EBF31F8‐8861‐435c‐8305‐51EAFD4F5BCE
AppID: SierraSASAnalyzer Lecroy.SierraSASAnalyzer
Example
WSH:
Set Analyzer = WScript.CreateObject(
“Lecroy.SierraSASAnalyzer” )
C++:
ISierraSASAnalyzer* poSierraSASAnalyzer;
// create SierraSASAnalyzer object
if ( FAILED( CoCreateInstance(
CLSID_SierraSASAnalyzer,
NULL, CLSCTX_SERVER,
IID_ISeirraSASAnalyzer,
(LPVOID *)&poSierraSASAnalyzer ) )
46
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SierraSTAnalyzer Object
SierraSTAnalyzer Object
The SierraSTAnalyzer object is the Sierra version of the SASAnalyzer object in the SATA software. This object is delivered by the SATA software automation API. All functionality is the same as the SASAnalyzer object. The Class ID and App ID for the SierraSTAnalyzer object are the following:
Class ID: SierraSTAnalyzer AF294105‐9BA9‐4a90‐943D‐8162E29635FF
AppID: SierraSTAnalyzer Lecroy.SierraSTAnalyzer
Example
WSH:
Set Analyzer = WScript.CreateObject(
“Lecroy.SierraSTAnalyzer” )
C++:
ISierraSTAnalyzer* poSierraSTAnalyzer;
// create SierraSTAnalyzer object
if ( FAILED( CoCreateInstance(
CLSID_SierraSTAnalyzer,
NULL, CLSCTX_SERVER,
IID_ISeirraSTAnalyzer,
(LPVOID *)&poSierraSTAnalyzer ) )
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
47
Teledyne LeCroy
STXSASAnalyzer Object
STXSASAnalyzer Object
The STXSASAnalyzer object is the Sierra version of the SASAnalyzer object in the SAS software. This object is delivered by the STX SAS software automation API. All functionality is the same as the SASAnalyzer object. The Class ID and App ID for the STXSASAnalyzer object are the following:
Class ID: STXSASAnalyzer 4E677701‐FD40‐4152‐8B11‐4406F87BB4FF
AppID: STXSASAnalyzer Lecroy.STXSASAnalyzer
Example
WSH:
Set Analyzer = WScript.CreateObject(
“Lecroy.STXSASAnalyzer” )
C++:
ISTXSASAnalyzer* poSTXSASAnalyzer;
// create STXSASAnalyzer object
if ( FAILED( CoCreateInstance(
CLSID_STXSASAnalyzer,
NULL, CLSCTX_SERVER,
IID_ISTXSASAnalyzer,
(LPVOID *)&poSTXSASAnalyzer ) )
48
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
STXSTAnalyzer Object
STXSTAnalyzer Object
The STXSTAnalyzer object is the Sierra version of the SASAnalyzer object in the SATA software. This object is delivered by the STX SATA software automation API. All functionality is the same as the SASAnalyzer object. The Class ID and App ID for the STXSTAnalyzer object are the following:
Class ID: STXSTAnalyzer 9A94D6AA‐9A86‐439d‐9FBB‐970FABA36888
AppID: STXSTAnalyzer Lecroy.STXSTAnalyzer
Example
WSH:
Set Analyzer = WScript.CreateObject(
“Lecroy.STXSTAnalyzer” )
C++:
ISTXSTAnalyzer* poSTXSTAnalyzer;
// create STXSTAnalyzer object
if ( FAILED( CoCreateInstance(
CLSID_STXSTAnalyzer,
NULL, CLSCTX_SERVER,
IID_ISTXTAnalyzer,
(LPVOID *)&poSTXSTAnalyzer ) )
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
49
Teledyne LeCroy
SASTrace Object
SASTrace Object
The SASTrace object represents the recorded trace file. The SASTrace object allows users to: 



Get trace information.
Access trace packets.
Access trace errors.
Save/export the trace or a portion of the trace.
The SASTrace object can be created by: 


Using the ISASAnalyzer::OpenFile method
Using the ISASAnalyzer::MakeRecording method
Handling the _ISASAnalyzerEvents::OnTraceCreated event
The SASTrace object supports the following interfaces:
Interfaces
Itrace ISASTrace ISASVerificationScript Description
Implements trace packets and trace errors access, different report types, exporting, and saving.
Extends ITrace interface: Adds functionality for accessing the SASTracePacket object. Exposes functionality for running verification scripts.
The ISASTrace interface is a primary interface for the SASTrace object.
50
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASTrace Object
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 the ISASTrace Interface.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
51
Teledyne LeCroy
SASTrace Object
ITrace::GetName
HRESULT GetName (
[out, retval] BSTR* trace_name );
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.sac")
MsgBox “Trace name “ & Trace.GetName
C++:
ISASTrace* sas_trace;
. . .
_bstr_t bstr_trace_name;
try
{
bstr_trace_name = sas_trace->GetName();
}
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 str_trace_name[256];
52
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASTrace Object
_tcscpy( str_trace_name, (TCHAR*)( bstr_trace_name)
);
SysFreeString( bstr_trace_name );
::MessageBox( NULL, str_trace_name, _T("Trace name"),
MB_OK );
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
53
Teledyne LeCroy
SASTrace Object
ITrace::ApplyDisplayOptions
HRESULT ApplyDisplayOptions (
[in] BSTR do_file_name );
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
Unable to load the display options file
Remarks
Use this method to filter traffic of some type in the recorded or opened trace. The display options file is the file with extension .sfl created by the filter dialog.
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.sac ")
Trace.ApplyDisplayOptions
CurrentDir &
"Input\test_do.slf"
Trace.Save
CurrentDir &
"Output\saved_file.scs"
C++:
ISASTrace* sas_trace;
TCHAR file_name[_MAX_PATH];
. . .
try
{
sas_trace->ApplyDisplayOptions( file_name );
}
catch (_com_error& er)
{
if (er.Description().length() > 0)
54
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASTrace Object
::MessageBox(
client"), MB_OK
else
::MessageBox(
client"), MB_OK
return 1;
}
NULL, er.Description(),
);
_T("SASTracer
NULL, er.ErrorMessage(), _T("SASTracer
);
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
55
Teledyne LeCroy
SASTrace Object
ITrace::Save
HRESULT Save (
[in] BSTR file_name,
[in, defaultvalue(-1)] long packet_from,
[in, defaultvalue(-1)] long packet_to );
Saves trace into a file while allowing you to specify a range of packets.
Parameters
file_name
String providing the full pathname to the file where the trace is saved
packet_from
Beginning packet number when you are saving a range of packets,. –1 = first packet of the saved trace is the first packet of this trace.
packet_to
Ending packet number when you are saving a range of packets. –1 = last packet of the saved trace is the last packet of this trace.
Return Values
ANALYZERCOMERROR_UNABLESAVE
Unable to save the trace file
ANALYZERCOMERROR_INVALIDPACKETNUMBER
Bad packet range
Remarks
Use this method to save a recorded or opened trace into a file. If the display options apply to this trace (see ITrace::ApplyDisplayOptions or ISASAnalyzer::LoadDisplayOptions, then hidden packets would not be saved. 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 is 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.sac")
Trace.ApplyDisplayOptions
CurrentDir &
"Input\test_do.slf"
Trace.Save
CurrentDir &
"Output\saved_file.scs"
56
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASTrace Object
C++:
ISASTrace* sas_trace;
TCHAR file_name[_MAX_PATH];
LONG packet_from;
LONG packet_to;
. . .
try
{
sas_trace->Save( file_name, packet_from, packet_to );
}
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;
}
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
57
Teledyne LeCroy
SASTrace Object
ITrace::GetPacketRow
HRESULT GetPacketRow (
[in] long packet_number,
[in] VIEW_TYPE view_type,
[out] long* packet_row);
Changes packet number to row number.
Parameters
packet_number Integer for packet number
view_type VIEW_TYPE can be: COLUMN_VIEW (0), FRAME_TEXT_VIEW (1) [valid parameter for this method], PACKET_VIEW (2), WAVEFORM_VIEW (3), ST_REPORT_VIEW (4), SPREAD_SHEET_VIEW (5) [valid parameter for this method], HISTOGRAM_VIEW (6), BUS_UTILIZATION_VIEW (7).
packet_row
Integer of packet row. Remarks
Use this function before ExportToText and ExportToExcel to change packet numbers to row numbers.
Example
See ExportToText examples.
58
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASTrace Object
ITrace::ExportToText
HRESULT ExportToText (
[in] BSTR file_name,
[in] VIEW_TYPE export_view_type,
[in] long from_row,
[in] long to_row);
Exports Spreadsheet View and Frame View 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
export_view_type VIEW_TYPE can be: COLUMN_VIEW (0), FRAME_TEXT_VIEW (1) [valid parameter for this method], PACKET_VIEW (2), WAVEFORM_VIEW (3), ST_REPORT_VIEW (4), SPREAD_SHEET_VIEW (5) [valid parameter for this method], HISTOGRAM_VIEW (6), BUS_UTILIZATION_VIEW (7).
from_row
Beginning packet number when you are exporting a range of packets. 0 = first packet of the exported trace is the first packet of this trace.
to_row
Ending packet number when you are exporting a range of packets.
–1 = last packet of the exported trace is the last packet of this trace.
Return Value
ANALYZERCOMERROR_UNABLESAVE
Unable to export trace file
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 or ISASAnalyzer::LoadDisplayOptions), then hidden packets would not be exported.
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 is adjusted automatically.
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)
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
59
Teledyne LeCroy
SASTrace Object
_______| 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.sac")
Trace.ApplyDisplayOptions
CurrentDir &
"Input\test_do.slf"
Trace.ExportToText
CurrentDir &
"Output\text_export.txt"
C++:
ISASTrace* sas_trace;
TCHAR file_name[_MAX_PATH];
LONG packet_from;
LONG packet_to;
. . .
try
60
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASTrace Object
{
sas_trace->ExportToText( file_name, packet_from,
packet_to );
}
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;
}
Example 2
TestFileName = "MultiOpenClose"
On Error Resume Next
result = 1 ' pass
'###########################################
'Create STATS to report the results.
Set MySTATS = WScript.CreateObject("LECROY.STATS")
If Err.Number <> 0 Then
WScript.Echo "STATS Creation Failed"
WScript.Quit
ELSE
MySTATS.ReportText (TestFileName & " Started...")
MySTATS.ReportText("STATS Automation object is created")
End If
'############################################
'Create Analyzer object.
Set Analyzer = WScript.CreateObject("LECROY.SASAnalyzer")
If Err.Number <> 0 Then
MySTATS.ReportError Err.number, Err.Description
result = 2 ' fail
End If
MySTATS.ReportText ("Analyzer is created successfully")
'#############################################
' First
' Trace file path
ProjectPath = MySTATS.GetProjectPath
Set SASTracer =
Analyzer.OpenFile(ProjectPath & "Cascading-3 Board.scs")
If Err.Number <> 0 Then
MySTATS.ReportError Err.number, Err.Description
result = 2 ' fail
Else
MySTATS.ReportText ("Sample file is opened")
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
61
Teledyne LeCroy
SASTrace Object
End If
MySTATS.ReportText ("Number of packets in trace file :
" & CSTR(SASTracer.GetPacketsCount()))
'Get specific row of spread sheet view.
start_row = SASTracer.GetPacketRow (0, 5)
If Err.Number <> 0 Then
MySTATS.ReportError Err.number, Err.Description
result = 2 ' fail
End If
end_row = SASTracer.GetPacketRow (100, 5)
If Err.Number <> 0 Then
MySTATS.ReportError Err.number, Err.Description
result = 2 ' fail
End If
MySTATS.ReportText ("Star export row: " & CSTR(start_row))
MySTATS.ReportText ("End export row: " & CSTR(end_row))
SASTracer.ExportToText
ProjectPath & "SpreadSheet.txt", 5, start_row, end_row
SASTracer.ExportToText
ProjectPath & "FrameView.txt", 1 ' entire sample
If Err.Number <> 0 Then
MySTATS.ReportError Err.number, Err.Description
result = 2 ' fail
Else
MySTATS.ReportText ("Export to text has been done.")
End If
SASTracer.ExportToExcel
ProjectPath & "SpreadSheet.csv", 5 ' entire sample
SASTracer.ExportToExcel
ProjectPath & "FrameView.csv", 1, 1, 100 ' from row 1 to 100
If Err.Number <> 0 Then
MySTATS.ReportError Err.number, Err.Description
result = 2 ' fail
Else
MySTATS.ReportText ("Export to Excel has been done.")
End If
SASTracer.Close()
If Err.Number <> 0 Then
MySTATS.ReportError Err.number, Err.Description
result = 2 ' fail
Else
MySTATS.ReportText ("Trace file is closed")
End If
'#########################################
'Report the result.
MySTATS.ReportResult(result)
62
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASTrace Object
MySTATS.ReportText ("Finished")
'#########################################
'Remove the object.
WScript.DisconnectObject Analyzer
'#########################################
'Quit from the script.
WScript.Quit
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
63
Teledyne LeCroy
SASTrace Object
ITrace::ExportToExcel
HRESULT ExportToExcel (
[in] BSTR file_name,
[in] VIEW_TYPE export_view_type,
[in] long from_row,
[in] long to_row);
Exports Spreadsheet View and Frame View to an Excel file, while allowing you to specify a range of packets.
Parameters
file_name
String providing the full file pathname for the exported trace
export_view_type VIEW_TYPE can be: COLUMN_VIEW (0), FRAME_TEXT_VIEW (1) [valid parameter for this method], PACKET_VIEW (2), WAVEFORM_VIEW (3), ST_REPORT_VIEW (4), SPREAD_SHEET_VIEW (5) [valid parameter for this method], HISTOGRAM_VIEW (6), BUS_UTILIZATION_VIEW (7).
from_row
Beginning packet number when you are exporting a range of packets. 1 = first packet of the exported trace is the first packet of this trace.
to_row
Ending packet number when you are exporting a range of packets.
1 = last packet of the exported trace is the last packet of this trace.
Return Value
ANALYZERCOMERROR_UNABLESAVE
Unable to export trace file
Remarks
Use this method if you want to export a recorded or opened trace into an Excel file. If the display options apply to this trace, then hidden packets are not exported.
If the packet range specified is invalid, then the packet range is adjusted automatically.
Example
See ExportToText example.
64
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASTrace Object
ITrace::Close
HRESULT Close ( );
Closes the trace.
Parameters
Return Value
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 method.
Note: Currently there is no need to call ITrace::Close directly, since IUnknown::Release will close the
trace.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
65
Teledyne LeCroy
SASTrace Object
ITrace::ReportFileInfo
HRESULT ReportFileInfo (
[in] BSTR file_name )
Saves trace information into a specified text file.
Parameters
file_name
String providing the full pathname to file where the trace information report is stored
Return Value
ANALYZERCOMERROR_UNABLESAVE
Unable to create trace information report
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.sac")
Trace.ReportFileInfo
CurrentDir &
"Output\file_info.txt"
C++:
ISASTrace* sas_trace;
TCHAR file_name[_MAX_PATH];
. . .
try
{
sas_trace->ReportFileInfo( file_name );
}
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;
}
66
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASTrace Object
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 Value
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.
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):
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
67
Teledyne LeCroy
SASTrace Object
_______|_______________________________________________________________________
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):
_______|_______________________________________________________________________
Example
WSH:
Set Analyzer =
WScript.CreateObject("LeCroy.SASnalyzer")
CurrentDir = Left(WScript.ScriptFullName,
InstrRev(WScript.ScriptFullName, "\"))
Set Trace = Analyzer.MakeRecording (CurrentDir &
"Input\test_ro.sac")
Trace.ReportErrorSummary CurrentDir &
"Output\error_summary.txt"
C++:
ISASTrace* sas_trace;
TCHAR file_name[_MAX_PATH];
. . .
try
{
sata_trace->ReportErrorSummary( file_name );
}
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;
}
68
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASTrace Object
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
69
Teledyne LeCroy
SASTrace Object
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
packet
Raw packet representation
number_of_bits Number of bits in the raw packet representation
Return Value
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
ID = Analyzer
CLASSID = "clsid: 297CD804-08F5-4A4F-B3BA-779B2654B27C"
>
</OBJECT>
<INPUT TYPE=TEXT NAME="TextPacketNumber">
<P ALIGN=LEFT ID=StatusText></P>
<SCRIPT LANGUAGE="VBScript">
<!-Function DecToBin(Param, NeedLen)
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
End Function
70
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASTrace Object
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
PacketStr = PacketStr & DecToBin(PacketByte, 8) & " "
NBytes = NBytes + 1
Next
PacketStr = Left( PacketStr, NumberOfBits )
StatusText.innerText = "Packet ( " & NumberOfBits &
" bits ): " & PacketStr
End If
End Sub
-->
</SCRIPT>
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;
}
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
71
Teledyne LeCroy
SASTrace Object
if ( packet.vt == ( VT_ARRAY | VT_VARIANT) )
{
SAFEARRAY* packet_safearray = packet.parray;
TCHAR packet_message[256];
TCHAR elem[64];
_stprintf( packet_message, _T("packet #%ld: "),
packet_number );
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);
}
72
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASTrace Object
ITrace::GetPacketsCount
HRESULT GetPacketsCount (
[out, retval] long* number_of_packets );
Retrieves the total number of packets in the trace.
Parameters
number_of_packets
Total number of packets in the trace
Return Value
Remarks
Example
WSH:
Set Analyzer =
WScript.CreateObject("LeCroy.SASAnalyzer")
CurrentDir = Left(WScript.ScriptFullName,
InstrRev(WScript.ScriptFullName, "\"))
Set Trace = Analyzer.MakeRecording (CurrentDir &
"Input\test_ro.sac")
MsgBox Trace.GetPacketsCount & " packets recorded"
C++:
ISASTrace* sas_trace;
. . .
long number_of_packets;
long trigg_packet_num;
try
{
bstr_trace_name = sas_trace->GetName();
number_of_packets = sas_trace->GetPacketsCount();
trigg_packet_num = sas_trace->GetTriggerPacketNum();
}
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;
}
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
73
Teledyne LeCroy
SASTrace Object
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"), str_trace_name,
number_of_packets, trigg_packet_num );
::SetWindowText( m_hwndStatus, trace_info );
74
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASTrace Object
ITrace::GetTriggerPacketNum
HRESULT GetTriggerPacketNum (
[out, retval] long* packet_number );
Retrieves the trigger packet number.
Parameters
packet_number
Zero based number of the packet where the trigger occurred
Return Value
Remarks
Example
WSH:
CurrentDir = Left(WScript.ScriptFullName,
InstrRev(WScript.ScriptFullName, "\"))
Set Analyzer =
WScript.CreateObject("LeCroy.SASAnalyzer")
Set Trace = Analyzer.MakeRecording (CurrentDir &
"Input\test_ro.sac")
TriggerPacket = Trace.GetTriggerPacketNum
Trace.Save CurrentDir & "Output\trigger_portion.sas",
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.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
75
Teledyne LeCroy
SASTrace Object
ITrace::AnalyzerErrors
HRESULT AnalyzerErrors (
[in] long error_type,
[out, retval] ISASAnalyzerErrors**
analyzer_errors );
Retrieves trace file errors. Returns an interface pointer to the SASTraceErrors object Parameters
error_type
Type of error collection you want to retrieve; 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











analyzer_errors
Address of a pointer to the SASTraceErrors Object interface
Return Value
ANALYZERCOMERROR_INVALIDERROR
Invalid error type specified
Remarks
The SASTraceErrors object is created by 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.sac")
Set Errors = Trace.AnalyzerErrors (16) 'Bad CRC16
76
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASTrace Object
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;
}
. . .
analyser_errors->Release();
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
77
Teledyne LeCroy
SASTrace Object
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
78
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASTrace Object
ISASTrace::GetBusPacket
HRESULT GetBusPacket (
[in] long packet_number,
[out, retval] IDispatch** packet )
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 Object interface
Return Value
Remarks
The SASPacket object is created by this method call, if the call was successful. Example
WSH:
C++:
ISASTrace* sas_trace;
. . .
IDispatch* packet;
try
{
packet =
sas_trace->GetBusPacket(
GetDlgItemInt(IDC_PACKET_NUMBER) ).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;
}
ISASPacket* custom_packet;
HRESULT hr =
packet->QueryInterface(IID_ISASPacket,
(void**)&custom_packet);
packet->Release();
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
79
Teledyne LeCroy
SASTrace Object
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 dua, 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 use a special feature of the Teledyne LeCroy SAS/SATA Protocol Suite application, its Verification Script Engine. Please refer to the SASTracer Manual, SASTracer Verification Script Engine Manual, and 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 needed.
80
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASTrace Object
ISASVerificationScript::RunVerificationScript
HRESULT RunVerificationScript (
[in] BSTR verification_script,
[out, retval] VSResult *result )
Runs a verification script over the recorded trace.
Parameters
verification_script
Name of the verification script to run
result
Address of a variable in which to keep the verification result
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
Return Value
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 script name, without file extension, is specified, the Sierra/STX server searches for the named script among the scripts loaded from the \Scripts\VFScripts folder under the SAS/SATA Protocol Suite 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.
Example
C++:
// This example uses wrapper functions provided by the
#import directive.
ISASTrace* trace;
. . .
ISASVerificationScript* vscript = NULL;
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
81
Teledyne LeCroy
SASTrace Object
if ( SUCCEEDED ( trace->QueryInterface(
IID_ISASVerificationScript,
(void**)&vscript
) )
{
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;
}
}
else
{
::MessageBox( NULL, "Unable to get
ISASVerificationScript interface !!!",
_T("SASTracer client"), MB_OK );
return 1 ;
}
. . .
WSH:
Set Analyzer = WScript.CreateObject("LeCroy.SASTracer")
Set Trace = Analyzer.OpenFile( "C:\Some trace
files\some_trace.sas" )
82
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASTrace Object
Dim Result
Result = Trace.RunVerificationScript( "Test1" )
If Result = 1 Then
Msgbox "PASSED"
Else
Msgbox "FAILED"
End If
MsgBox( "Done" )
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
83
Teledyne LeCroy
SASTrace Object
ISASVerificationScript:: GetVScriptEngine
HRESULT GetVScriptEngine (
[in] BSTR script_name,
[out, retval] IVScriptEngine** vs_engine )
Retrieves the verification script engine object.
Parameters
script_name Name of the verification script to initialize the verification script engine
vs_engine
Address of a pointer to the SASVScriptEngine Object interface
Return Value
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 for details.
84
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASTrace Object
Example
C++:
// This example uses 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" )
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
85
Teledyne LeCroy
SASRecOptions Object
SASRecOptions Object
The SASRecOptions object represents the options for the Sierra/STX hardware and specifies the recording parameters. The SASRecOptions object allows you to: 


Load/save the recording options from/to the file.
Set up recording mode and recording buffer size.
Set up custom recording parameters, such as ChannelSettings, DataTruncate, MultiSegment mode, and SpoolMode.
The SASRecOptions object can be created by using the ISASAnalyzer::GetRecordingOptions method. The SASRecOptions object supports the following interfaces:
Interfaces
IRecOptions ISASRecOptions Description
Allows you to load/save recording options from/to the file, reset recording options, and set recording mode, recording buffer size, trigger position, and trace file name.
Identical to the IRecOptions interface
The ISASRecOptions interface is a primary interface for the SASRecOptions object.
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.
86
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASRecOptions Object
IRecOptions::Load
HRESULT Load (
[in] BSTR ro_file_name );
Loads recording options from the specified file.
Parameters
ro_file_name
String that provides the full pathname to the recording options file
Return Value
ANALYZERCOMERROR_UNABLEOPENFILE Unable to open file
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.sac" )
C++:
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
87
Teledyne LeCroy
SASRecOptions Object
IRecOptions::Save
HRESULT Save (
[in] BSTR ro_file_name );
Saves recording options into the specified file.
Parameters
ro_file_name
String that provides the full pathname to the recording options file
Return Value
ANALYZERCOMERROR_UNABLEOPENFILE
Unable to open file
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.sac" )
C++:
88
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASRecOptions Object
IRecOptions::SetRecMode
HRESULT SetRecMode (
[in] ERecModes rec_mode );
Sets the recording mode.
Parameters
rec_mode
Enumerated value providing the mode to set.
ErecModes enumerator has the following values:
snapshot recording mode
( 1 ) = manual trigger ( 2 ) = event trigger
RMODE_SNAPSHOT ( 0 ) =
RMODE_MANUAL
RMODE_USE_TRG
Return Value
E_INVALIDARG
Invalid recording mode specified
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++:
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
89
Teledyne LeCroy
SASRecOptions Object
IRecOptions::SetBufferSize
HRESULT SetBufferSize (
[in] long buffer_size );
Sets the size of the recording buffer.
Parameters
buffer_size
Size of the recording buffer in bytes
Return Value
E_INVALIDARG
Invalid buffer size specified
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++:
90
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASRecOptions Object
IRecOptions::SetPostTriggerPercentage
HRESULT SetPostTriggerPercentage (
[in] short posttrigger_percentage );
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 Value
E_INVALIDARG
Invalid percentage specified
Remarks
This method call has no effect if recording mode is set to RMODE_SNAPSHOT (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++:
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
91
Teledyne LeCroy
SASRecOptions Object
IRecOptions::SetTriggerBeep
HRESULT SetTriggerBeep (
[in] BOOL beep );
Sets a flag to make a sound when a trigger occurs.
Parameters
beep
TRUE = Beep when trigger occurs.
FALSE = Do not beep when trigger occurs.
Return Value
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++:
92
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASRecOptions Object
IRecOptions::SetSaveExternalSignals
HRESULT SetSaveExternalSignals (
[in] BOOL save );
Sets a flag to save external signals.
Parameters
save
TRUE = Save external signals.
FALSE = Do not save external signals.
Return Value
Remarks
By default, external signals are not saved.
Example
WSH:
Set Analyzer =
WScript.CreateObject("LeCroy.SASAnalyzer")
Set RecOptions = Analyzer.GetRecordingOptions
RecOptions.SetSaveExternalSignals TRUE
C++:
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
93
Teledyne LeCroy
SASRecOptions Object
IRecOptions::SetTraceFileName
HRESULT SetTraceFileName (
[in] BSTR file_name );
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 will be stored
Return Value
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.sas" )
C++:
94
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASRecOptions Object
IRecOptions::Reset
HRESULT Reset ( )
Resets the recording options to the initial state.
Parameters
Return Value
Remarks
For default values of recording options, see the remarks sections of the IRecOptions Interface and ISASRecOptions Interface methods.
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++:
ISASRecOptions Interface
This interface is identical to the IRecOptions Interface.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
95
Teledyne LeCroy
SASPacket Object
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
IPacket ISASPacket Description
Allows retrieval of the packet timestamp.
Extends the IPacket interface.
The ISASPacket interface is a primary interface for the SASPacket object.
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.
96
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASPacket Object
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.sac" )
TriggerPacket = Trace. GetTriggerPacketNum
Set Packet = Trace.GetBusPacket(TriggerPacket)
MsgBox "Trigger packet at " & Packet.GetTimestamp & "
ns"
C++:
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
97
Teledyne LeCroy
SASPacket Object
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: 





98
GetPacketData
GetLinkNumber
GetFrameType
GetDirection
GetErrors
GetTotalDwords
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASPacket Object
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
( 0 )
bytes
PACKETFORMAT_SCRAMBLED_BYTES
( 1 )
scrambled bytes
PACKETFORMAT_TEN_BIT
( 2 ) 10‐bit codes
packet
Raw packet data
number_of_bytes
Number of bytes in the packet
Return Value
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.
Example
VBScript:
<OBJECT
ID = Analyzer
CLASSID = "clsid: 0B179BB7-DC61-11d4-9B71-000102566088"
>
</OBJECT>
<INPUT TYPE=TEXT NAME="TextPacketNumber">
<P ALIGN=LEFT ID=StatusText></P>
<SCRIPT LANGUAGE="VBScript">
<!-Function DecToBin(Param, NeedLen)
While Param > 0
Param = Param/2
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
99
Teledyne LeCroy
SASPacket Object
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
End Function
Sub BtnGetPacket_OnClick
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
Next
StatusText.innerText =
"Packet ( " & NumberOfUnits & " bytes
): " & PacketStr
End If
End If
End Sub
-->
100
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASPacket Object
</SCRIPT>
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);
timestamp_ns = custom_packet->GetTimestamp ( );
}
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_data.vt == ( VT_ARRAY | VT_VARIANT) )
{
SAFEARRAY* packet_safearray = packet_data.parray;
TCHAR* packet_message =
new TCHAR [ 3*packet_safearray->rgsabound[0].cElements
+ 64 ];
TCHAR elem[64];
_stprintf(packet_message, _T("packet #%ld: "),
GetDlgItemInt(IDC_PACKET_NUMBER));
_stprintf( elem, _T(" %.0lf ns"), timestamp_ns );
_tcscat( packet_message, elem );
_stprintf( elem, _T(", %d bytes: "), number_of_bytes
);
_tcscat( packet_message, elem );
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
101
Teledyne LeCroy
SASPacket Object
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 );
}
::MessageBox( NULL, packet_message, _T("packet"),
MB_OK );
delete [] packet_message;
}
else
{
::MessageBox(NULL, _T("Invalid argument"),
_T("SASTracer client"), MB_OK );
}
102
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASPacket Object
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 Value
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++:
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
103
Teledyne LeCroy
SASPacket Object
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::AnalyzerErrors for error ID values.
number_of_errors
Total number of errors in this packet
Return Value
Remarks
Example
WSH:
C++:
104
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASPacket Object
IPacket:: GetLinkNumber
HRESULT GetLinkNumber (
[out, retval] long* link_number )
Returns analyzer link number of this packet.
Parameters
Link_number It is the analyzer link number of this packet which starts from 1 (I1 and T1). Return Value
Remarks
Example
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
105
Teledyne LeCroy
SASPacket Object
IPacket:: GetFrameType
HRESULT GetFrameType (
[out, retval] long* frame_type )
Returns frame type of this packet.
Parameters
frame_type It is the frame type of this packet which can be one of the following values:
SAS_FT_UNKNOWN 0
SAS_FT_PRIMITIVE 1
SAS_FT_AF_OPEN 3
SAS_FT_AF_IDENTIFY 4
SAS_FT_SSP_FRAME 5
SAS_FT_SMP_FRAME 6
SAS_FT_STP_FRAME 7
SAS_FT_IDLE 8 SAS_FT_TRAINING 9 SAS_FT_OOB_SIGNAL 10
SAS_FT_DEV_SLP 11
Return Value
Remarks
Example
106
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASPacket Object
IPacket:: GetTotalDwords
HRESULT GetTotalDwords (
[out, retval] long* total_dwords )
Returns DWords’ number of this packet.
Parameters
total_dwords It is total number of DWords of this packet.
Return Value
Remarks
Example
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
107
Teledyne LeCroy
SASTraceErrors Object
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.
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: 

108
get_Item
get_Count
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASTraceErrors Object
ISASAnalyzerErrors::get_Item
HRESULT get_Item(
[in] long index,
[out, retval] long* packet_number );
Get items.
Parameters
index
Index of the error in the collection
packet_number
Error packet number
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
109
Teledyne LeCroy
SASTraceErrors Object
ISASAnalyzerErrors::get_Count
HRESULT get_Count(
[out, retval] long* number_of_errors );
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.sac" )
Set Errors = Trace.AnalyzerErrors( 32 ) ' Running
Disparity Error
For Each ErrorPacketNumber In Errors
ErrorFile = CurrentDir & "\Output\PckLen_error_span_" &
CStr(ErrorPacketNumber) & ".sas"
Trace.Save ErrorFile, CInt(ErrorPacketNumber)-5,
CInt(ErrorPacketNumber)+5
Next
C++:
ISASTrace* sas_trace;
. . .
ISASAnalyzerErrors* analyser_errors;
try
{
analyser_errors = sas_trace>AnalyzerErrors(error_type).Detach();
}
110
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASTraceErrors Object
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 );
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
111
Teledyne LeCroy
SASVScriptEngine Object
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
IVScriptEngine
_ISASAnalyzerEvents
Description
Provides advanced control over the verification script and allows you to execute the script asynchronously.
Events from SASVScriptEngine object The IVScriptEngine interface is a primary interface for the SASVScriptEngine 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 use a special feature of the SAS/SATA Protocol Suite application, its Verification Script Engine. Please refer to the SASTracer Manual, SASTracer Verification Script Engine Manual, and File Based Decoding Manual for more details.
112
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASVScriptEngine Object
IVScriptEngine Interface
The IVScriptEngine interface is the primary dual interface for the SASVScriptEngine object. It implements the following properties and methods: 



RunVScript
RunVScriptEx
LaunchVScript
Stop
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
113
Teledyne LeCroy
SASVScriptEngine Object
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 Value
Remarks
The name of the verification script is the name of the verification script file (*.pevs). If only the script name, without a file extension, is specified, the Sierra/STX server searches for the named script among the scripts loaded from the \Scripts\VFScripts folder under the SAS/SATA Protocol Suite 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++:
// This example uses 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 );
}
. . .
114
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASVScriptEngine Object
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 Value
Remarks
This method makes a “synchronous” call, which means that this method does not return until the script stops running. The name of the verification script is the name of the verification script file (*.pevs). If only the script name, without a file extension, is specified, the Sierra/STX server searches for the named script among the scripts loaded from the \Scripts\VFScripts folder under the SAS/SATA Protocol Suite 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.
See the ISASVerificationScript::RunVerificationScript method for details.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
115
Teledyne LeCroy
SASVScriptEngine Object
Example
C++:
// This example uses 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 );
}
. . .
116
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASVScriptEngine Object
IVScriptEngine::LaunchVScript
HRESULT LaunchVScript ( )
Launches the current verification script.
Parameters
Return Value
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 to the client event handler. You can also terminate the running script using the method IVScriptEngine::Stop.
Example
C++:
// This example uses 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.
. . .
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
117
Teledyne LeCroy
SASVScriptEngine Object
IVScriptEngine::Stop
HRESULT Stop ( )
Stops the verification script previously launched by IVScriptEngine::LaunchVScript.
Parameters
Return Value
Remarks
Example
C++:
// This example uses 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();
. . .
118
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASVScriptEngine Object Events
Teledyne LeCroy
SASVScriptEngine Object Events
_IVScriptEngineEvents Interface
To retrieve event notifications from the Teledyne LeCroy SAS/SATA Protocol Suite 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 such as Visual Basic, VBA, VBScript, and WSH. Some script engines impose restrictions on handling events from “indirect” 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 SAS/SATA Protocol Suite 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
The 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: Example
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);
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
119
Teledyne LeCroy
SASVScriptEngine Object Events
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);
}
...
};
Then, after you have established the connection with the server, you must advise your implementation of the event interface: IVScriptEngine vscript_engine = NULL;
try
{
vscript_engine = vscript ->GetVScriptEngine( "Test_1"
);
}
catch (_com_error& er )
{
SetStatusError( er );
}
if ( vscript_engine == NULL )
{
vscript = NULL;
return E_FAIL;
}
CVSEngineSink vse_sink;
HRESULT hr = vse_sink . Advise( vscript_engine );
// “Subscribe” for receiving events.
...
120
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASVScriptEngine Object Events
Teledyne LeCroy
VS_RESULT res = SCRIPT_NOT_FOUND;
try
{
res = (VS_RESULT)vscript_engine ->RunVScript();
}
catch (_com_error& er)
{
SetStatusError( er );
}
// Tear connection with the test case.
vse_sink.Unadvise( vscript_engine );
...
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, a
line like this:
' Public WithEvents VSEEvents As VScriptEngine
Dim X As New VSEngineEventsModule
Private Sub RunVScritButton_Click()
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
End If
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
121
Teledyne LeCroy
SASVScriptEngine Object Events
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.
End Sub
122
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASVScriptEngine Object Events
IVScriptEngineEvents::OnVScriptReportUpdated
HRESULT OnVScriptReportUpdated (
[in] BSTR newline,
[in] int tag )
Fires when running a verification script. Calls the ReportText(newLine) function (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 tag
Return Value
Remarks
Make sure that C++ event handlers have the __stdcall calling convention.
Example
C++:
HRESULT __stdcall OnVScriptReportUpdated (BSTR newLine,
int TAG )
{
TRACE( "Line: %s, TAG: %d\n", newLine, TAG );
. . .
return S_OK;
}
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
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
123
Teledyne LeCroy
SASVScriptEngine Object Events
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 (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 the ISASVerificationScript::RunVerificationScript method for details.
TAG
VSE object tag
Return Value
Remarks
Make sure that C++ event handlers have the __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 )
124
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASVScriptEngine Object Events
Teledyne LeCroy
Dim ResString As String
ResString = "Script name : " & script_name & ", result =
" &
CStr(result) & ", TAG = " & CStr(Tag)
ThisWorkbook.Sheets("Sheet1").Cells(7, 2) = ResString
End Sub
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
125
Teledyne LeCroy
SASVScriptEngine Object Events
IVScriptEngineEvents::OnNotifyCount
HRESULT OnNotifyCount (
[in] int eventId,
[in] VARIANT eventBody,
[in] int TAG )
Fires 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 tag
Return Value
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 )] );
. . .
}
126
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASVScriptEngine Object Events
Teledyne LeCroy
VBA (MS Excel):
Public WithEvents VSEEvents As VScriptEngine
. . .
Private Sub VSEEvents_OnNotifyClient( ByVal eventId As
Long,
ByVal eventBody As Variant,
ByVal Tag 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
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
127
Teledyne LeCroy
SASAnalyzer Object Events
SASAnalyzer Object Events
_ISASAnalyzerEvents Dispinterface
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 “indirect” 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 Teledyne LeCroy SAS/SATA Protocol Suite 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. The 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)
// Make sure the Event Handlers have __stdcall calling
convention.
SINK_ENTRY(IDC_SRCOBJ, 1, OnTraceCreated)
SINK_ENTRY(IDC_SRCOBJ, 2, OnStatusReport)
END_SINK_MAP()
. . .
}
128
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object Events
Then, after you establish a connection with the server, you must advise as to your implementation of the event interface: hr = CoCreateInstance( CLSID_SASAnalyzer, NULL,
CLSCTX_SERVER, IID_ISASAnalyzer, (LPVOID
*)&m_poSASAnalyzer );
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,
&poAnalyzerSink->m_iid, &poAnalyzerSink>m_wMajorVerNum,
&poAnalyzerSink->m_wMinorVerNum);
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;
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
129
Teledyne LeCroy
SASAnalyzer Object Events
_ISASAnalyzerEvents::OnTraceCreated
HRESULT OnTraceCreated (
[in] IDispatch* trace );
Fires when a trace is created. This event is a result of ISASAnalyzer::StartRecording and ISASAnalyzer::StopRecording method calls.
Parameters
trace
Interface pointer to the SASTrace object
Return Value
Remarks
Make sure the event handlers have the __stdcall calling convention.
130
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object Events
Example
VBScript:
<OBJECT
ID = Analyzer
CLASSID = " clsid: 297CD804-08F5-4A4F-B3BA-779B2654B27C
" >
</OBJECT>
<P ALIGN=LEFT ID=StatusText></P>
<SCRIPT LANGUAGE="VBScript">
<!-Dim CurrentTrace
Sub Analyzer_OnTraceCreated(ByRef Trace)
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"
End Sub
-->
</SCRIPT>
C++:
HRESULT __stdcall OnTraceCreated( IDispatch* trace )
{
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;
}
. . .
return hr;
}
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
131
Teledyne LeCroy
SASAnalyzer Object Events
_ISASAnalyzerEvents::OnStatusReport
HRESULT OnStatusReport (
[in] short subsystem,
[in] short state,
[in] long percent_done );
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 RECORDING_PROGRESS_REPORT
( 1 ) Recording subsystem
GENERATION_PROGRESS_REPORT ( 2 ) Generation subsystem
\state
Current analyzer state has the following values:
If the subsystem is RECORDING_PROGRESS_REPORT: ANALYZERSTATE_IDLE (-1 )
= idle
ANALYZERSTATE_WAITING_TRIGGER ( 0 )= recording in progress, analyzer waiting for trigger
ANALYZERSTATE_RECORDING_TRIGGERED ( 1 ) = recording in progress, analyzer triggered
ANALYZERSTATE_UPLOADING_DATA ( 2 )
ANALYZERSTATE_SAVING_DATA ( 3 )
=
=
uploading in progress
saving data in progress
If the subsystem is GENERATION_PROGRESS_REPORT: ANALYZERSTATE_GEN_IDLE
( 400 ) = idle
ANALYZERSTATE_GEN_DOWNLOADING ( 401 ) = generator is downloading object code
ANALYZERSTATE_GEN_GENERATING
( 402 ) = generator is working
ANALYZERSTATE_GEN_PAUSED
( 403 ) = generator is paused
percent_done
132
Shows the progress of currently performing operation:
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object Events
If the subsystem is RECORDING_PROGRESS_REPORT: When analyzer state is ANALYZERSTATE_IDLE, is not applicable.
When analyzer state is ANALYZERSTATE_WAITING_TRIGGER or ANALYZER‐
STATE_RECORDING_TRIGGERED, shows analyzer memory utilization.
When analyzer state is ANALYZERSTATE_UPLOADING_DATA, shows the percent of data uploaded.
When analyzer state is ANALYZERSTATE_SAVING_DATA, shows the percent of data saved.




If the subsystem is GENERATION_PROGRESS_REPORT, represents current position of script execution.
Return Value
Remarks
Make sure the event handlers have the __stdcall calling convention.
Example
VBScript:
<OBJECT
ID = Analyzer
CLASSID = "clsid:0B179BB8-DC61-11D4-9B71-000102566088"
>
</OBJECT>
<P ALIGN=LEFT ID=StatusText></P>
<SCRIPT LANGUAGE="VBScript">
<!-Function GetRecordingStatus(ByVal State, ByVal Percent)
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"
End Function
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
133
Teledyne LeCroy
SASAnalyzer Object Events
Dim RecordingStatus
Sub Analyzer_OnStatusReport(ByVal System, ByVal State,
ByVal Percent)
Select Case System
Case 1 RecordingStatus = GetRecordingStatus( State,
Percent )
End Select
End Sub
-->
</SCRIPT>
C++:
#define
#define
#define
#define
#define
#define
RECORDING_PROGRESS_REPORT ( 1 )
ANALYZERSTATE_IDLE( -1 )
ANALYZERSTATE_WAITING_TRIGGER( 0 )
ANALYZERSTATE_RECORDING_TRIGGERED( 1 )
ANALYZERSTATE_UPLOADING_DATA( 2 )
ANALYZERSTATE_SAVING_DATA( 3 )
HRESULT __stdcall OnStatusReport(short subsystem, short
state,
long 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;
}
void UpdateRecStatus( short state, long percent_done )
{
TCHAR status_buf[64];
switch ( state )
{
case ANALYZERSTATE_IDLE:
_tcscpy( status_buf, _T("Idle") );
break;
case ANALYZERSTATE_WAITING_TRIGGER:
134
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy
SASAnalyzer Object Events
_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;
case ANALYZERSTATE_SAVING_DATA:
_tcscpy( status_buf, _T("Saving data") );
break;
default:
_tcscpy( status_buf, _T("Unknown") );
break;
}
_stprintf(m_RecordingStatus, _T("%s, done %ld%%"),
status_buf,
percent_done);
}
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
135
Teledyne LeCroy
How to Contact Teledyne LeCroy How to Contact Teledyne LeCroy
Type of Service
Call for technical support…
Fax your questions…
Write a letter …
Send e‐mail…
Visit Teledyne LeCroy’s web site…
136
Contract
US and Canada:1 (800) 909‐7112
Worldwide: 1 (408) 653‐1260 Worldwide:1 (408) 727‐6622
Teledyne LeCroy
Protocol Solutions Group
Customer Support
3385 Scott Blvd.
Santa Clara, CA 95054‐3115
USA
psgsupport@teledynelecroy.com
teledynelecroy.com/
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite