Teledyne Automation API User Manual
Protocol Solutions Group
3385 Scott Blvd., Santa Clara, CA 95054
Tel: +1/408.727.6600
Fax: +1/408.727.6622
Automation API
for
Teledyne LeCroy PETracer/PETrainer™
Reference Manual
For PETracer/Trainer Software Version 7.x
January 2014
Teledyne LeCroy Automation API for PETracer/PETrainer
ii
Document Disclaim er
The information contained in this document has been carefully checked and is believed to be
reliable. However, no responsibility can be assumed for inaccuracies that may not have been
detected.
Teledyne LeCroy reserves the right to revise the information presented in this document without
notice or penalty.
Trademarks and Servicemarks
Teledyne LeCroy, CATC, PETracer EML, PETracer M L, PETr ac er, PETr a iner E ML, PETr ai ner
ML, and PETracer Autom at ion are trademarks of Teledyne LeCroy.
Microsoft and Windows are registered trademarks of Microsoft Inc.
All other trademarks are property of their respective companies.
Copyright
© 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.
Teledyne LeCroy Automation API for PETracer/PETrainer
iii
Table of Contents
1 Introduction .......................................................................................................................................... 1
1.1 System Requirements .................................................................................................................... 1
1.2 Support Resources ......................................................................................................................... 1
1.3 Setting Up Automation for Local Use ............................................................................................. 1
1.4 Setting Up Automation for Remote Use ......................................................................................... 1
2 PETracer Object Model........................................................................................................................ 2
3 PEAnalyzer Object ............................................................................................................................... 4
3.1 IAnalyzer interface .......................................................................................................................... 5
3.1.1 IAnalyzer::GetVersion ............................................................................................................. 6
3.1.2 IAnalyzer::OpenFile ................................................................................................................. 7
3.1.3 IAnalyzer::StartGeneration ...................................................................................................... 8
3.1.4 IAnalyzer::StopGeneration ...................................................................................................... 9
3.1.5 IAnalyzer::StartRecording ..................................................................................................... 10
3.1.6 IAnalyzer::StopRecording ...................................................................................................... 12
3.1.7 IAnalyzer::MakeRecording .................................................................................................... 13
3.1.8 IAnalyzer::LoadDisplayOptions ............................................................................................. 14
3.1.9 IAnalyzer::GetRecordingOptions ........................................................................................... 15
3.1.10 IAnalyzer::GetSerialNumber .................................................................................................. 16
3.2 IPEAnalyzer interface ................................................................................................................... 17
3.2.1 IPEAnalyzer::GetGenerationOptions .................................................................................... 18
3.2.2 IPEAnalyzer::ResumeGeneration ......................................................................................... 19
3.2.3 IPEAnalyzer::GetLinkStatus .................................................................................................. 20
3.3 IPEAnalyzer2 interface ................................................................................................................. 21
3.3.1 IPEAnalyzer2::GetHardwareInfo ........................................................................................... 22
3.3.2 IPEAnalyzer2::ResetHardware .............................................................................................. 24
3.4 IPEAnalyzer3 interface ................................................................................................................. 25
3.4.1 IPEAnalyzer3::StartImportFile ............................................................................................... 26
4 PETrace Object .................................................................................................................................. 27
4.1 ITrace interface ............................................................................................................................. 28
4.1.1 ITrace::GetName ................................................................................................................... 29
4.1.2 ITrace::ApplyDisplayOptions ................................................................................................. 30
4.1.3 ITrace::Save .......................................................................................................................... 31
4.1.4 ITrace::ExportToText ............................................................................................................. 32
4.1.5 ITrace::Close ......................................................................................................................... 35
4.1.6 ITrace::ReportFileInfo ............................................................................................................ 36
4.1.7 ITrace::ReportErrorSummary ................................................................................................ 37
4.1.8 ITrace::GetPacket ................................................................................................................. 40
4.1.9 ITrace::GetPacketsCount ...................................................................................................... 43
4.1.10 ITrace::GetTriggerPacketNum .............................................................................................. 44
4.1.11 ITrace::AnalyzerErrors .......................................................................................................... 45
4.2 IPETrace interface ........................................................................................................................ 47
4.2.1 IPETrace::GetBusPacket ...................................................................................................... 47
4.3 IPEVerificationScript interface ...................................................................................................... 48
4.3.1 IPEVerificationScript::RunVerificationScript .......................................................................... 49
4.3.2 IPEVerificationScript::GetVScriptEngine ............................................................................... 51
5 PERecOptions Object ........................................................................................................................ 53
5.1 IRecOptions interface ................................................................................................................... 54
5.1.1 IRecOptions::Load ................................................................................................................. 54
5.1.2 IRecOptions::Save ................................................................................................................ 55
5.1.3 IRecOptions::SetRecMode .................................................................................................... 56
5.1.4 IRecOptions::SetBufferSize ................................................................................................... 57
Teledyne LeCroy Automation API for PETracer/PETrainer
iv
5.1.5 IRecOptions::SetPostTriggerPercentage .............................................................................. 58
5.1.6 IRecOptions::SetTriggerBeep ............................................................................................... 59
5.1.7 IRecOptions::SetSaveExternalSignals .................................................................................. 60
5.1.8 IRecOptions::SetTraceFileName ........................................................................................... 61
5.1.9 IRecOptions::Reset ............................................................................................................... 62
5.2 IPERecOptions interface .............................................................................................................. 63
5.3 IPERecOptions2 interf ac e ............................................................................................................ 63
5.3.1 IPERecOptions2::SetTargetAnalyzer .................................................................................... 64
5.3.2 IPERecOptions2::SetLinkWidth ............................................................................................. 65
5.3.3 IPERecOptions2::SetBase10Spec ........................................................................................ 66
5.3.4 IPERecOptions2::SetExternalRefClock ................................................................................ 67
5.3.5 IPERecOptions2::SetDisableDescrambling .......................................................................... 68
5.3.6 IPERecOptions2::SetDisableDeskew ................................................................................... 69
5.3.7 IPERecOptions2::SetAutoConfigPolarity .............................................................................. 70
5.3.8 IPERecOptions2::SetInhibit ................................................................................................... 71
5.3.9 IPERecOptions2::SetReverseLanes ..................................................................................... 72
5.3.10 IPERecOptions2::SetInvertPolarity ....................................................................................... 73
5.4 IPERecOptions3 interf ac e ............................................................................................................ 74
5.4.1 IPERecOptions3::SetLinkSpeed ........................................................................................... 74
5.4.2 IPERecOptions3::GetSimpleTrigger...................................................................................... 75
5.4.3 IPERecOptions3::GetSimpleFilter ......................................................................................... 77
5.4.4 IPERecOptions3:: RestoreDefaultFactorySettings ................................................................ 78
5.5 SimpleTrigger ............................................................................................................................... 79
5.5.1 SimpleTrigger::SetEnabled ................................................................................................... 79
5.5.2 SimpleTrigger::IsEnabled ...................................................................................................... 79
Retrieves trigger's state. ...................................................................................................................... 79
5.5.3 SimpleTrigger::SetDirection .................................................................................................. 79
5.5.4 SimpleTrigger::GetDirection .................................................................................................. 80
5.6 SimpleFilter ................................................................................................................................... 81
5.6.1 SimpleFilter::SetEnabled ....................................................................................................... 81
5.6.2 SimpleFilter::IsEnabled ......................................................................................................... 81
Retrieves filter's state. .......................................................................................................................... 81
5.6.3 SimpleFilter::SetDirection ...................................................................................................... 81
5.6.4 SimpleFilter::GetDirection ..................................................................................................... 82
6 PEGenOptions Object ....................................................................................................................... 83
6.1 IGenOptions interface ................................................................................................................... 84
6.1.1 IGenOptions::Load ................................................................................................................ 85
6.1.2 IGenOptions::Save ................................................................................................................ 86
6.1.3 IGenOptions::Reset ............................................................................................................... 87
6.2 IPEGenOptions interf ac e .............................................................................................................. 88
6.3 IPEGenOptions2 interface ............................................................................................................ 88
6.3.1 IPEGenOptions2::SetTargetGenerator ................................................................................. 89
6.3.2 IPEGenOptions2::SetWorkAsRoot ........................................................................................ 90
6.3.3 IPEGenOptions2::SetLinkWidth ............................................................................................ 91
6.3.4 IPEGenOptions2::SetBase10Spec ....................................................................................... 92
6.3.5 IPEGenOptions2::SetExternalRefClock ................................................................................ 93
6.3.6 IPEGenOptions2::SetDisableDescrambling .......................................................................... 94
6.3.7 IPEGenOptions2::SetDisableScrambling .............................................................................. 95
6.3.8 IPEGenOptions2::SetAutoConfig .......................................................................................... 96
6.3.9 IPEGenOptions2::SetReverseLanes ..................................................................................... 97
6.3.10 IPEGenOptions2::SetInvertPolarity ....................................................................................... 98
6.3.11 IPEGenOptions2::SetSkew ................................................................................................... 99
7 PEPacket Object .............................................................................................................................. 100
7.1 IPacket interface ......................................................................................................................... 101
Teledyne LeCroy Automation API for PETracer/PETrainer
v
7.1.1 IPacket::GetTimestamp ....................................................................................................... 101
7.2 IPEPacket interface .................................................................................................................... 102
7.2.1 IPEPacket::GetPacketData ................................................................................................. 103
7.2.2 IPEPacket::GetLinkWidth .................................................................................................... 106
7.2.3 IPEPacket::GetStartLane .................................................................................................... 107
7.2.4 IPEPacket::GetLFSR ........................................................................................................... 108
7.2.5 IPEPacket::GetDirection ...................................................................................................... 109
7.2.6 IPEPacket::GetErrors .......................................................................................................... 110
8 PETraceErrors Object...................................................................................................................... 111
8.1 IAnalyzerErrors dispinterface ..................................................................................................... 111
8.1.1 IAnalyzerErrors::get_Item .................................................................................................... 112
8.1.2 IAnalyzerErrors::get_Count ................................................................................................. 113
9 PEVScriptEngine Object ................................................................................................................. 115
9.1 IVScriptEngine interf ace ............................................................................................................. 116
9.1.1 IVScriptEngine::VScriptName ............................................................................................. 117
9.1.2 IVScriptEngine::Tag ............................................................................................................ 118
9.1.3 IVScriptEngine::RunVScript ................................................................................................ 119
9.1.4 IVScriptEngine::RunVScriptEx ............................................................................................ 120
9.1.5 IVScriptEngine::LaunchVScript ........................................................................................... 122
9.1.6 IVScriptEngine::Stop ........................................................................................................... 123
9.1.7 IVScriptEngine::GetScriptVar .............................................................................................. 124
9.1.8 IVScriptEngine::SetScriptVar .............................................................................................. 126
10 PEVScriptEngine Object Events ................................................................................................. 128
10.1 _IVScriptEngineEvents interface ............................................................................................ 128
10.1.1 _IVScriptEngineEvents::OnVScriptReportUpdated............................................................. 131
10.1.2 _IVScriptEngineEvents::OnVScriptFinished ....................................................................... 132
10.1.3 _IVScriptEngineEvents::OnNotifyClient .............................................................................. 133
11 PEAnalyzer Object Events .......................................................................................................... 134
11.1 _IAnalyzerEvents dispinterface ............................................................................................... 134
11.1.1 _IAnalyzerEvents::OnTraceCreated.................................................................................... 135
11.1.2 _IAnalyzerEvents::OnStatusReport .................................................................................... 136
12 CATCAnalyzerAdapter ................................................................................................................. 139
12.1 IAnalyzerAdapter Interface ..................................................................................................... 140
12.1.1 IAnalyzerAdapter::CreateObject.......................................................................................... 140
12.1.2 IAnalyzerAdapter::Attach ..................................................................................................... 142
12.1.3 IAnalyzerAdapter::Detach ................................................................................................... 143
12.1.4 IAnalyzerAdapter::IsValidObject.......................................................................................... 145
13 Teledyne LeCroy Internal Interfaces .......................................................................................... 146
How to Contact Teledyne LeCroy .......................................................................................................... 147
Teledyne LeCroy Automation API for PETracer/PETrainer
1
1 Introduction
Teledyne LeCroy’s PETracer™ software provides a rich, functional COM/Automation API to the most
important functionalities of the Teledyne LeCroy PETracer Protocol Analyzer and Teledyne LeCroy PETrainer™
Exerciser. This makes it a great tool for implementation of automated programs for complicated testing,
development, and debugging. The "dual" nature of the interfaces provided makes it easy to use the PETracer
COM API in different IDEs (Integrated Development Environment) supporting the COM architecture.
A special support for typeless script languages, like VB and JavaScript, while overriding some restrictions
imposed by script engines (remote access, dynamic object creation, and handling events), gives the opportunity
to write client applications very quickly and easily. One does not require significant programming skills nor
installing 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 PETracer
an attractive tool in automating and speeding up many engineering processes.
1.1 System Requirements
The Automation API was introduced with the following release: PETracer software 4.10. This document
covers the functionality available in PETracer 4.00
1.2 Support Resources
As new functionalities are added to the API, not all of them are supported by older versions of the
PETracer software. For newer releases of PETracer software, please refer to the Teledyne LeCroy web site:
www.teledynelecroy.com
1.3 Setting Up Automation for Local Use
If you intend to run Automation on the PETracer/PETrainer Host Controller (i.e., the PC attached to the
PETracer/PETrainer), you do not need to perform any special configuration. You can simply execute the scripts
or programs you have created and they run the analyzer. In order to use the PETracer COM API, the application
should be registered as a COM server in a system registry. This is done during the installation process.
1.4 Setting Up Automation for Remote Use
If you would like to access PETracer remotely over a network, you should install the PETracer application
on both server and client machine and accept enabling remote access option during the installation. You can
also perform a manual DCOM configuration.
Teledyne LeCroy Automation API for PETracer/PETrainer
2
2 PETracer Object Model
Teledyne LeCroy’s PETracer™ 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 PETracer object hierarchy: PEAnalyzer.
The following object model diagram shows how the objects in an object model fit together:
PEAnalyzer
Only the
C/C++ client), instantiation of an object of other classes requires API calls.
The Class ID and App ID for the PEAnalyzer object are the following.
Class ID: 297CD804-08F5-4A4F-B3BA-779B2654B27C
App ID: CATC.PETracer
All interfaces are dual interfaces that allow simple use from typeless languages, like VBScript, as well as from
C/C++.
PEAnalyzer object is creatable at the top level (for instance, via the CoCreateInstance call from a
PETrace
PETraceErrors
PEVScriptEngine
PERecOptions
PEGenOptions
PEPacket
Teledyne LeCroy Automation API for PETracer/PETrainer
3
Objects
Interfaces
Description
PEAnalyzer
IAnalyzer
Represents the PETracer
IPEAnalyzer
IPEAnalyzer2
IPEAnalyzer3*
_IAnalyzerEvents
PETrace
ITrace
Represents recorded trace
IPETrace*
IPEVerificationScript*
PERecOptions
IRecOptions
Represents recording options
IPERecOptions
IPERecOptions2*
PEGenOptions
IGenOptions
Represents generation options
IPEGenOptions
IPEGenOptions2*
PEPacket
IPacket
Represents single packet of the
IPEPacket*
PETraceErrors
IAnalyzerErrors*
Represents the collection of
trace
All objects implement ISupportErrorInfo interface for easy error handling from the client.
application
recorded trace
errors occurred in the recorded
* 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 "PEAutomation.tlb" no_namespace named_guids
Appropriate wrapper classes are created in .tli and .tlh files by the compiler.
Samples of WSH, VBScript, and C++ client applications are provided.
Teledyne LeCroy Automation API for PETracer/PETrainer
4
Interfaces
Description
IAnalyzer
Facilitates recording and traffic generation, opens trace files,
and retrieves recording options,
IPEAnalyzer
Extends the IAnalyzer interface:
options.
IPEAnalyzer2
Extends the IPEAnalyzer interface:
Adds StartImportFile method.
_IAnalyzerEvents
Events from PEAnalyzer object
3 PEAnalyzer Object
The PEAnalyzer
The PEAnalyzer
to the recording and generation options.
The PEAnalyzer
object is a top-level object of PETracer™ API.
object allows user to control the recording and traffic generation, open trace files, and access
object supports the following interfaces:
Adds advanced generator functionality, retrieves generation
IPEAnalyzer3
Adds hardware information and control methods.
Extends the IPEAnalyzer2 interface:
The IPEAnalyzer3 interface is a primary interface for the PEAnalyzer object.
The Class ID and App ID for the PEAnalyzer object are the following.
Class ID: 297CD804-08F5-4A4F-B3BA-779B2654B27C
App ID: CATC.PETracer
Example
WSH:
C++:
CLSID_PEAnalyzer,
NULL, CLSCTX_SERVER,
IID_IPEAnalyzer,
(LPVOID *)&poPEAnalyzer ) )
return;
Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
IPEAnalyzer* poPEAnalyzer;
// create PEAnalyzer object
if ( FAILED( CoCreateInstance(
Teledyne LeCroy Automation API for PETracer/PETrainer
5
3.1 IAnalyzer interfac e
The IAnalyzer interface is a dual interface for the PEAnalyzer object.
IAnalyzer implements the following methods:
GetVersion
OpenFile
StartGeneration
StopGeneration
StartRecording
StopRecording
MakeRecording
LoadDisplayOptions
Note: All methods of the IAnalyzer interface are also available in the IPEAnalyzer (see Page 16), IPEAnalyzer2
(see Page 20), and IPEAnalyzer3 (see Page 25) interfaces.
Teledyne LeCroy Automation API for PETracer/PETrainer
6
version_type
Subsystem being queried for version; EAnalyzerVersionType
ANALYZERVERSION_SOFTWARE ( 0 ) – software
analyzer_version
Version of the subsystem queried
3.1.1 IAnalyzer::GetVersion
HRESULT GetVersion (
[in] EAnalyzerVersionType version_type,
[out, retval] WORD* analyzer_version )
Retrieves the current version of a specified subsystem.
Parameters
enumerator has the following values:
Return values
ANALYZERCOMERROR_INVALIDVERSIONTYPE Specified version type is invalid
Remarks
Example
WSH:
Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
SwVersion = Analyzer.GetVersion( 0 )
MsgBox "Software " & SwVersion
C++:
HRESULT hr;
IPEAnalyzer* poPEAnalyzer;
// create PEAnalyzer object
if ( FAILED( CoCreateInstance(
CLSID_PEAnalyzer,
NULL, CLSCTX_SERVER,
IID_IPEAnalyzer,
(LPVOID *)&poPEAnalyzer ) )
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("PETracer client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("PETracer client"), MB_OK );
return 1;
}
TCHAR buffer[20];
_stprintf(buffer, _T("Software version:%X.%X"), HIBYTE(sw_version), LOBYTE(sw_version));
Teledyne LeCroy Automation API for PETracer/PETrainer
7
file_name
String providing the full pathname to the trace file
trace
Address of a pointer to the PETrace object interface
3.1.2 IAnalyzer::OpenFile
HRESULT OpenFile (
[in] BSTR file_name,
[out, retval] IDispatch** trace )
Opens a trace file, and creates the PETrace object.
Parameters
Return values
ANALYZERCOMERROR_UNABLEOPENFILE Unable to open file
Remarks
PETrace object is created via this method call, if the call was successful.
Example
WSH:
CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” ) )
Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set Trace = Analyzer.OpenFile( CurrentDir & "Input\errors.pex" )
C++:
HRESULT hr;
IPEAnalyzer* poPEAnalyzer;
// create PEAnalyzer object
if ( FAILED( CoCreateInstance(
CLSID_PEAnalyzer,
NULL, CLSCTX_SERVER,
IID_IPEAnalyzer,
(LPVOID *)&poPEAnalyzer ) )
return;
// open trace file
IDispatch* trace;
try
{
trace = poPEAnalyzer->OpenFile( m_szRecFileName ).Detach();
}
catch ( _com_error& er)
{
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(), _T("PETracer client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("PETracer client"), MB_OK );
return 1;
}
// query for VTBL interface
IPETrace* pe_trace;
hr = trace->QueryInterface( IID_IPETrace, (LPVOID *)&pe_trace );
trace->Release();
if( FAILED(hr) )
return;
Teledyne LeCroy Automation API for PETracer/PETrainer
8
gen_file_name
String providing the full pathname to the generation file
reserved1
Reserved for future use
reserved2
Reserved for future use
3.1.3 IAnalyzer::StartGeneration
HRESULT StartGeneration (
[in] BSTR gen_file_name,
[in] long reserved1,
[in] long reserved2 )
Starts traffic generation from the file.
Parameters
Return values
ANALYZERCOMERROR_UNABLEOPENFILE Unable to open file
ANALYZERCOMERROR_UNABLESTARTGENERATION
Remarks
Example
WSH:
CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” ) )
Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
ret = Analyzer.StartGeneration( CurrentDir & "Input\connect.peg", 0, 0 )
C++:
HRESULT hr;
IPEAnalyzer* poPEAnalyzer;
TCHAR m_szGenFileName [_MAX_PATH];
// create PEAnalyzer object
if ( FAILED( CoCreateInstance(
CLSID_PEAnalyzer,
NULL, CLSCTX_SERVER,
IID_IPEAnalyzer,
(LPVOID *)&poPEAnalyzer ) )
return;
. . .
try
{
poAnalyzer->StartGeneration( m_szGenFileName, 0, 0 );
}
catch ( _com_error& er)
{
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(), _T("PETracer client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("PETracer client"), MB_OK );
return 1;
}
Unable to start generation (invalid state, etc.)
Teledyne LeCroy Automation API for PETracer/PETrainer
9
3.1.4 IAnalyzer::StopGeneration
HRESULT StopGeneration ( )
Stops any current generation in progress.
Return values
ANALYZERCOMERROR_UNABLESTARTGENERATION Unable to stop generation (invalid state, etc.)
Remarks
Example
C++:
IPEAnalyzer* poAnalyzer;
. . .
try
{
poAnalyzer->StopGeneration();
}
catch ( _com_error& er)
{
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(), _T("PETracer client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("PETracer client"), MB_OK );
return 1;
}
Teledyne LeCroy Automation API for PETracer/PETrainer
10
ro_file_name
String providing the full pathname to the recording options file; if the
options
3.1.5 IAnalyzer::StartRecording
HRESULT StartRecording (
[in] BSTR ro_file_name )
Starts recording with the specified recording options.
Parameters
parameter is omitted, then recording starts with default recording
Return values
Remarks
the StopRecording method call is performed. During the recording, the events are sent to event sink (see the
_IAnalyzerEvents interface, Page 119).
create this file when you select “Setup -> Recording Options…” from the PETracer application menu, change
the settings in the “Recording Options” dialog box, and then select the “Save…” button.
Example
VBScript:
On Error Resume Next
Analyzer.StartRecording TextRecOptions.value
If Err.Number <> 0 Then
MsgBox Err.Number & ":" & Err.Description
End If
ANALYZERCOMERROR_UNABLESTARTRECORDING Unable to start recording
After recording starts, this function returns. The analyzer continues recording until it is finished or until
The recording options file is the file with extension .rec created by the PETracer application. You can
<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
End Sub
-->
</SCRIPT>
Teledyne LeCroy Automation API for PETracer/PETrainer
11
C++:
IPEAnalyzer* pe_analyzer;
BSTR ro_file_name;
. . .
try
{
pe_analyzer->StartRecording( ro_file_name )
}
catch ( _com_error& er)
{
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(), _T("PETracer client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("PETracer client"), MB_OK );
return 1;
}
Teledyne LeCroy Automation API for PETracer/PETrainer
12
abort_upload
TRUE if the caller wants to abort the upload, no trace file is created;
FALSE if the caller wants to upload the recorded trace
3.1.6 IAnalyzer::StopRecording
HRESULT StopRecording (
[in] BOOL abort_upload )
Stops recording started by the IAnalyzer::StartRecording (see Page 10) method.
Parameters
Return values
Remarks
actually stopped (via the _IAnalizerEvents
Example
VBScript:
On Error Resume Next
Analyzer.StopRecording True
If Err.Number <> 0 Then
MsgBox Err.Number & ":" & Err.Description
End If
C++:
ANALYZERCOMERROR_UNABLESTOPRECORDING Error stopping recording
Stops recording that was started by the StartRecording method. The event is issued when recording is
interface) if the parameter of this method call was FALSE.
<OBJECT
RUNAT=Server
ID = Analyzer
CLASSID = "clsid: 297CD804-08F5-4A4F-B3BA-779B2654B27C "
>
</OBJECT>
<SCRIPT LANGUAGE="VBScript">
<!-Sub BtnStopRecording_OnClick
End Sub
-->
</SCRIPT>
IPEAnalyzer* pe_analyzer;
. . .
try
{
pe_analyzer->StopRecording( FALSE )
}
catch ( _com_error& er)
{
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(), _T("PETracer client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("PETracer client"), MB_OK );
return 1;
}
Teledyne LeCroy Automation API for PETracer/PETrainer
13
ro_file_name
String providing the full pathname to a recording options file;
recording options
trace
Address of a pointer to the PETrace object interface
3.1.7 IAnalyzer::MakeRecording
HRESULT MakeRecording (
[in] BSTR ro_file_name,
[out, retval] IDispatch** trace )
Makes recording with the specified recording options file.
Parameters
if the parameter is omitted, then recording starts with default
Return values
ANALYZERCOMERROR_UNABLESTARTRECORDING
Remarks
This method acts like the StartRecording method but does not return until recording is completed. The
PETrace object is created via this method call if the call was successful.
The recording options file is the file with extension .rec created by the PETracer application. You can
create this file when you select “Setup -> Recording Options…” from the PETracer application menu, change
the settings in the “Recording Options” dialog box, and then select the “Save…” button.
Example
WSH:
CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” ) )
Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set Trace = Analyzer.MakeRecording( CurrentDir & "Input\test_ro.rec" )
C++:
IDispatch* trace;
IPEAnalyzer* pe_analyzer;
BSTR ro_file_name;
HRESULT hr;
. . .
try
{
trace = pe_analyzer->MakeRecording( ro_file_name ).Detach();
}
catch ( _com_error& er)
{
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(), _T("PETracer client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("PETracer client"), MB_OK );
return 1;
}
// query for VTBL interface
IPETrace* pe_trace;
hr = trace->QueryInterface( IID_IPETrace, (LPVOID *)&pe_trace );
trace->Release();
Unable to start recording
Teledyne LeCroy Automation API for PETracer/PETrainer
14
do_file_name
String providing the full pathname to a display options file
3.1.8 IAnalyzer::LoadDisplayOptions
HRESULT LoadDisplayOptions (
[in] BSTR do_file_name )
Loads display options that apply to a trace opened or recorded later.
Parameters
Return values
Remarks
apply only on trace file opened or recorded after this call.
this file when you select “Setup -> Display Options…” from the PETracer application menu, change the settings
in the “Display Options” dialog box, and then select the “Save…” button. Example
ANALYZERCOMERROR_UNABLELOADDO Unable to load the display options file
Use this method if you want to filter traffic of some type. The display options loaded by this method call
Display options file is the file with extension .opt created by the PETracer application. You can create
See ITrace::ApplyDisplayOptions, Page 27.
Teledyne LeCroy Automation API for PETracer/PETrainer
15
recording_options
Address of a pointer to the PERecOptions object interface
3.1.9 IAnalyzer::GetRecordingOptions
HRESULT GetRecordingOptions (
[out, retval] IDispatch** recording_options )
Retrieves the interface for access to the recording options.
Parameters
Return values
Remarks
PERecOptions object is created via this method call, if the call was successful.
Example
WSH:
Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set RecOptions = Analyzer.GetRecordingOptions( )
C++:
HRESULT hr;
IPEAnalyzer* poPEAnalyzer;
// create PEAnalyzer object
if ( FAILED( CoCreateInstance(
CLSID_PEAnalyzer,
NULL, CLSCTX_SERVER,
IID_IPEAnalyzer,
(LPVOID *)&poPEAnalyzer ) )
return;
// open trace file
IDispatch* rec_opt;
try
{
rec_opt = poPEAnalyzer->GetRecordingOptions().Detach();
}
catch ( _com_error& er)
{
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(), _T("PETracer client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("PETracer client"), MB_OK );
return 1;
}
// query for VTBL interface
IPERecOptions* ib_rec_opt;
hr = rec_opt->QueryInterface( IID_IPERecOptions, (LPVOID *)&ib_rec_opt );
rec_opt->Release();
if( FAILED(hr) )
return;
Teledyne LeCroy Automation API for PETracer/PETrainer
16
3.1.10 IAnalyzer::GetSerialNumber
HRESULT GetSerialNumber ( [out, retval] WORD* serial_number )
Returns analyzer's serial number.
Parameters
Return values
WORD serial_number
Remarks
Example
Set Analyzer = WScript.CreateObject("CATC.PETracer")
SerialNum = Analyzer.GetSerialNumber()
WScript.Echo "SerialNum= " & CLng(SerialNum)
Teledyne LeCroy Automation API for PETracer/PETrainer
17
3.2 IPEAnalyzer interf ace
The IPEAnalyzer interface is a dual interface for the PEAnalyzer object.
This interface is derived from the IAnalyzer interface.
The IPEAnalyzer
GetGenerationOptions
ResumeGeneration
GetLinkStatus
Note: All methods implemented by the IPEAnalyzer interface are also implemented by the IPEAnalyzer2
interface (see Page 20).
interface implements all methods from IAnalyzer interface plus the following:
Teledyne LeCroy Automation API for PETracer/PETrainer
18
generation_options
Address of a pointer to the PEGenOptions object interface
3.2.1 IPEAnalyzer::GetGenerationOptions
HRESULT GetGenerationOptions (
[out, retval] IDispatch** generation_options )
Retrieves the interface for access to the gen erati on o ptio ns .
Parameters
Return values
Remarks
PEGenOptions object is created via this method call, if the call was successful.
Example
WSH:
Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set GenOptions = Analyzer.GetGenerationOptions( )
C++:
HRESULT hr;
IPEAnalyzer* poPEAnalyzer;
// create PEAnalyzer object
if ( FAILED( CoCreateInstance(
CLSID_PEAnalyzer,
NULL, CLSCTX_SERVER,
IID_IPEAnalyzer,
(LPVOID *)&poPEAnalyzer ) )
return;
// open trace file
IDispatch* gen_opt;
try
{
gen_opt = poPEAnalyzer->GetGenerationOptions().Detach();
}
catch ( _com_error& er)
{
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(), _T("PETracer client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("PETracer client"), MB_OK );
return 1;
}
// query for VTBL interface
IPEGenOptions* pe_gen_opt;
hr = gen_opt->QueryInterface( IID_IPEGenOptions, (LPVOID *)&pe_gen_opt );
gen_opt->Release();
if( FAILED(hr) )
return;
Teledyne LeCroy Automation API for PETracer/PETrainer
19
3.2.2 IPEAnalyzer::ResumeGeneration
HRESULT ResumeGeneration ( )
Resumes generation if it was previously paused.
Return values
Remarks
Example
C++:
try
{
poAnalyzer->ResumeGeneration();
}
catch ( _com_error& er)
{
}
IPEAnalyzer* poAnalyzer;
. . .
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(), _T("PETracer client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("PETracer client"), MB_OK );
return 1;
Teledyne LeCroy Automation API for PETracer/PETrainer
20
fc_status
Flow control status, one of the following values can be returned:
“Pending”, “Complete”, or “Not initialized”
link_status
Link status, one of the following values can be returned: “
“Recovery.Idle”, “Loopback”, “Hot Reset”, or “Disabled”
3.2.3 IPEAnalyzer::GetLinkStatus
HRESULT GetLinkStatus (
[out] VARIANT* fc_status ,
[out, retval] BSTR* link_status )
Returns two text strings with the link and flow control status.
Parameters
“Detect.Active”, “Polling.Active”, “Polling.Compliance”,
“Polling.Configuration”, “Polling.Speed”,
“Configuration.Linkwidth.Start”, “Configuration.Linkwidth.Accept”,
“Configuration.Lanenum.Wait”, “Configuration.Lanenum.Accept”,
“Configuration.Complete”, “Configuration.Idle”, “L0”, “L0s.Idle”,
“L0s.FTS”, “L1”, “L2”, “Recovery.RcvrLock”, “Recovery.RcvrCfg”,
Return values
Remarks
Example
C++:
. . .
{
USES_CONVERSION;
TCHAR str_status[512];
_tcscpy( str_status, "Link Status: ");
_tcscat( str_status, OLE2T( link_status) );
_tcscat( str_status, "; Flow Control: ");
_tcscat( str_status, OLE2T(V_BSTR(&pe_status)) );
SysFreeString( link_status );
IPEAnalyzer* poAnalyzer;
BSTR link_status; // Link Status
VARIANT pe_status; // Flow Control
VariantInit(&pe_status);
try
link_status = poAnalyzer->GetLinkStatus( &pe_status );
}
catch ( _com_error& er)
{
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(), _T("PETracer client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("PETracer client"), MB_OK );
return 1;
}
::MessageBox( NULL, str_status, _T("Status"), MB_OK );
Detect.Quiet”,
Teledyne LeCroy Automation API for PETracer/PETrainer
21
3.3 IPEAnalyzer2 interface
The IPEAnalyzer2 interface is a dual interface for the PEAnalyzer object.
This interface is derived from the IPEAnalyzer interface.
The IPEAnalyzer2
GetHardwareInfo
ResetHardware
interface implements all methods from IPEAnalyzer interface plus the following:
Teledyne LeCroy Automation API for PETracer/PETrainer
22
type
Hardware type being queried; the
HARDWARETYPE_PETRAINER ( 1 ) - PETrainer
info
The following values can be returned
3.3.1 IPEAnalyzer2::GetHardwareInfo
HRESULT GetHardwareInfo (
[in] EHardwareType type,
[out, retval] int* info )
Returns information about the hardware (PETracer/PETrainer™) connected.
Parameters
EHardwareType enumerator has the
following valu e s :
HARDWARETYPE_PETRACER ( 0 ) – PETracer
Return values
Remarks
Example
C++:
IPEAnalyzer2* poAnalyzer;
. . .
int tracer_type = 0;
int trainer_type = 0;
try
{
trainer_type = poAnalyzer->GetHardwareInfo( HARDWARETYPE_PETRAINER );
}
catch ( _com_error& er )
{
if (er.Description().length() > 0)
else
When type is HARDWARETYPE_PETRACER:
1 – PETracer ML
2 – PETracer ML (2 units)
3 – PETracer EML
4 – Edge T1-4
5
– (reserved)
6
– PETracer Sum mit / Summit T2-16
7
– Summit T3-16
8
– Summit T3-8
9
– Summit T28
10
– Summit T3-8 (2 units)
11 – Summit T24
When type is HARDWARETYPE_PETRAINER:
0 – PETrainer ML
1 – PETrainer EML
2 – Summit Z2-16
3 – Summit Z3-16
::MessageBox( NULL, er.Description(), _T("PETracer client"), MB_OK );
::MessageBox( NULL, er.ErrorMessage(), _T("PETracer client"), MB_OK );
Teledyne LeCroy Automation API for PETracer/PETrainer
23
}
try
{
tracer_type = poAnalyzer->GetHardwareInfo( HARDWARETYPE_PETRACER );
}
catch ( _com_error& er )
{
}
return 1;
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(), _T("PETracer client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("PETracer client"), MB_OK );
return 1;
Teledyne LeCroy Automation API for PETracer/PETrainer
24
type
Hardware type to reset; the EHardwareType enumerator has the
HARDWARETYPE_PETRAINER ( 1 ) - PETrainer
reset_type
Type of the reset; the
values:
RESETTYPE_LINK ( 0 ) – link reset
3.3.2 IPEAnalyzer2::ResetHardware
HRESULT ResetHardware (
[in] EHardwareType type,
[in] EResetType reset_type )
Resets the hardware specified.
Parameters
following values:
HARDWARETYPE_PETRACER ( 0 ) – PETracer
EResetType enumerator has the following
Remarks
Example
C++:
. . .
{
poAnalyzer->ResetHardware( HARDWARETYPE_PETRAINER, RESETTYPE_LINK );
}
catch ( _com_error& er )
{
IPEAnalyzer2* poAnalyzer;
try
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(), _T("PETracer client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("PETracer client"), MB_OK );
return 1;
}
Teledyne LeCroy Automation API for PETracer/PETrainer
25
3.4 IPEAnalyzer3 interface
The IPEAnalyzer3 interface is a primary dual interface for the PEAnalyzer object.
This interface is derived from the IPEAnalyzer2 interface.
The IPEAnalyzer3
StartImportFile
interface implements all methods from IPEAnalyzer2 interface plus the following:
Loading...