Teledyne LeCroy Automation API for Teledyne LeCroy PETracer_PETrainer User Manual
Teledyne LeCroy Equipment
Table of contents
Document Outline
- Automation API
- For PETracer/Trainer Software Version 7.x
- Document Disclaimer
- Trademarks and Servicemarks
- Copyright
- Table of Contents
- 1 Introduction
- 2 PETracer Object Model
- A single object occupies the topmost tier of Teledyne LeCroy PETracer object hierarchy: PEAnalyzer.
- The Class ID and App ID for the PEAnalyzer object are the following.
- Class ID: 297CD804-08F5-4A4F-B3BA-779B2654B27C
- All objects implement ISupportErrorInfo interface for easy error handling from the client.
- Appropriate wrapper classes are created in .tli and .tlh files by the compiler.
- Samples of WSH, VBScript, and C++ client applications are provided.
- 3 PEAnalyzer Object
- The PEAnalyzer object is a top-level object of PETracer™ API.
- 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
- Example
- WSH:
- Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
- C++:
- IPEAnalyzer* poPEAnalyzer;
- The IAnalyzer interface is a dual interface for the PEAnalyzer object.
- Retrieves the current version of a specified subsystem.
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- Opens a trace file, and creates the PETrace object.
- Parameters
- Return values
- Remarks
- PETrace object is created via this method call, if the call was successful.
- Example
- WSH:
- C++:
- Starts traffic generation from the file.
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- Stops any current generation in progress.
- Return values
- Remarks
- Example
- C++:
- IPEAnalyzer* poAnalyzer;
- Starts recording with the specified recording options.
- Parameters
- Return values
- Remarks
- Example
- Sub BtnStartRecording_OnClick
- C++:
- Stops recording started by the IAnalyzer::StartRecording (see Page 10) method.
- Parameters
- Return values
- Remarks
- Example
- Sub BtnStopRecording_OnClick
- C++:
- IPEAnalyzer* pe_analyzer;
- Makes recording with the specified recording options file.
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- Loads display options that apply to a trace opened or recorded later.
- Parameters
- Return values
- Remarks
- Example
- See ITrace::ApplyDisplayOptions, Page 27.
- 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:
- C++:
- Returns analyzer's serial number.
- Parameters
- Return values
- Remarks
- Example
- The IPEAnalyzer interface is a dual interface for the PEAnalyzer object.
- This interface is derived from the IAnalyzer interface.
- Retrieves the interface for access to the generation options.
- Parameters
- Return values
- Remarks
- PEGenOptions object is created via this method call, if the call was successful.
- Example
- WSH:
- C++:
- Resumes generation if it was previously paused.
- Return values
- Remarks
- Example
- C++:
- IPEAnalyzer* poAnalyzer;
- Returns two text strings with the link and flow control status.
- Parameters
- Return values
- Remarks
- Example
- C++:
- IPEAnalyzer* poAnalyzer;
- USES_CONVERSION;
- SysFreeString( link_status );
- The IPEAnalyzer2 interface is a dual interface for the PEAnalyzer object.
- This interface is derived from the IPEAnalyzer interface.
- Returns information about the hardware (PETracer/PETrainer™) connected.
- Parameters
- Return values
- Remarks
- Example
- Resets the hardware specified.
- Parameters
- Remarks
- Example
- C++:
- IPEAnalyzer2* poAnalyzer;
- The IPEAnalyzer3 interface is a primary dual interface for the PEAnalyzer object.
- This interface is derived from the IPEAnalyzer2 interface.
- Begins process of importing specified file into a trace file.
- Parameters
- Return values
- Remarks
- Example
- C++:
- IPEAnalyzer3* poAnalyzer;
- 4 PETrace Object
- PETrace object represents the recorded trace file.
- The IPETrace interface is a primary interface for the PETrace object.
- The ITrace interface is a dual interface for the PETrace object.
- Note: All methods of ITrace interface are also available in IPETrace (see Page 41).
- Retrieves the trace name.
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- IPETrace* pe_trace;
- Applies the specified display options to the trace.
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- Saves trace into a file while allowing you to specify a range of packets.
- Parameters
- Remarks
- Example
- C++:
- Exports the trace into a text file while allowing you to specify a range of packets.
- Parameters
- Return values
- Remarks
- Packet#
- _______| CompleterID(000:07:2) Status(UR)-BAD BCM(1) Byte Cnt(2618)-BAD
- Packet(1887) Downstream TS2 COM(K28.5 ) Link Lane N_FTS
- Packet(1889) Downstream TS2 COM(K28.5 ) Link Lane N_FTS
- Example
- WSH:
- C++:
- Closes the trace.
- Parameters
- Return values
- Remarks
- Example
- Saves trace information into a specified HTML file.
- Parameters
- Return values
- Remarks
- Creates a new trace information file if the file specified in the file_name parameter does not exist.
- Example
- WSH:
- C++:
- Saves trace error summary information into the specified text file.
- Parameters
- Return values
- Remarks
- This method doesn’t work on Multisegment traces.
- Error report for ErrorFinding_loop.pex recording file.
- Example
- WSH:
- C++:
- Parameters
- Return values
- Remarks
- Example
- Sub BtnGetPacket_OnClick
- C++:
- SAFEARRAY* packet_safearray = packet.parray;
- Retrieves the total number of packets in the trace.
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- IPETrace* pe_trace;
- Retrieves the trigger packet number.
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- See an example for ITrace::GetPacketsCount, Page 37.
- Retrieves trace file errors. Returns an interface pointer to the PETraceErrors object.
- Parameters
- Return values
- Remarks
- PETraceErrors object is created via this method call if the call was successful.
- Example
- WSH:
- C++:
- IPETrace* pe_trace;
- The IPETrace interface is a primary dual interface for the PETrace object.
- This interface is derived from the ITrace interface.
- Retrieves the interface for a packet within a trace.
- Parameters
- Return values
- Remarks
- PEPacket object is created via this method call if the call was successful.
- Example
- WSH:
- C++:
- IPETrace* pe_trace;
- Remarks
- Attention:
- Runs a verification script over the recorded trace
- Parameters
- Return values
- Remarks
- Example
- Example
- C++:
- IPEVerificationScript* vscript = NULL;
- WSH:
- Dim Result
- If Result = 1 Then
- Else
- MsgBox( "Done" )
- Retrieves the verification script engine object
- Parameters
- Return values
- Remarks
- Example
- C++:
- IPETrace* pe_trace;
- IPEVerificationScript* pe_vscript = NULL;
- WSH:
- Dim Result
- If Result = 1 Then
- Else
- 5 PERecOptions Object
- The IPERecOptions2 interface is a primary interface for PERecOptions object.
- The IRecOptions interface is a dual interface for PERecOptions object.
- Loads recording options from the specified file. The load options are:
- Loads the whole Recording Options (.rec)
- Loads only the Recording Rules portions of the recording options (.rr)
- Loads only the Probe Settings portions of the recording options (.ps). This option only applies to the Summit T3-16, T3-8, T28 and T24 Protocol Analyzers.
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- Saves recording options into the specified file. The Save options are:
- Saves the whole Recording Options (.rec)
- Saves only the Recording Rules portions of the recording options (.rr)
- Saves only the Probe Settings portions of the recording options (.ps). This option only applies to the Summit T3-16, T3-8, T28 and T24 Protocol Analyzers.
- Parameters
- Return values
- Remarks
- If the specified file does not exist, it is created; if it exists, it is overwritten.
- Example
- WSH:
- C++:
- Sets the recording mode.
- Parameters
- Return values
- Remarks
- The default setting of recording options is a “snapshot” recording mode.
- Example
- WSH:
- C++:
- Sets the size of buffer to record.
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- Sets the post trigger buffer size.
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- Sets a flag to make a sound when a trigger occurs.
- Parameters
- Return values
- Remarks
- The default state of the beeper is FALSE.
- Example
- WSH:
- C++:
- Sets a flag to save external signals.
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- Sets the file path to where the trace is stored after recording.
- Parameters
- Return values
- Remarks
- If the specified file does not exist, it is created; if it exists, it is overwritten.
- Example
- WSH:
- C++:
- Resets the recording options to the initial state.
- Parameters
- Return values
- Remarks
- Example
- WSH:
- RecOptions.Reset
- C++:
- This interface is identical to the IRecOptions interface (see Page 48).
- The IPERecOptions2 interface is a primary dual interface for the PERecOptions object.
- This interface is derived from the IPERecOptions interface.
- Sets the hardware configuration for the recording options.
- Parameters
- Sets the link width.
- Parameters
- Sets PCI Express Base Specification 1.0 compatibility mode.
- Parameters
- Remarks
- Implemented for PETracer ML and PETracer EML. Not implemented for PETracer x1.
- Specifies whether to use the external or internal reference clock
- Parameters
- Disables/enables descrambling of incoming traffic.
- Parameters
- Remarks
- Implemented for PETracer ML and PETracer EML. Not implemented for PETracer x1.
- Disables/enables deskew of incoming traffic.
- Parameters:
- Remarks
- Implemented for PETracer ML and PETracer EML. Not implemented for PETracer x1.
- Enables/disables automatic polarity detection.
- Parameters:
- Remarks
- Implemented for PETracer ML and PETracer EML. Not implemented for PETracer x1.
- Inhibits one of the traffic directions.
- Parameters:
- Remarks
- Implemented for PETracer ML and PETracer EML. Not implemented for PETracer x1.
- Allows lane reversal on the specified traffic direction.
- Parameters:
- Remarks
- Implemented for PETracer ML and PETracer EML. Not implemented for PETracer x1.
- Allows polarity inversion of the specified lane and specified traffic direction.
- Parameters:
- Remarks
- The IPERecOptions3 interface is a primary dual interface for the PERecOptions object.
- This interface is derived from the IPERecOptions interface.
- Parameters:
- Parameters:
- Return values
- Remarks
- Example
- Returns simple filter interface of the given filter type.
- Parameters:
- Return values
- SimpleFilter object
- Remarks
- Example
- Restores factory default settings.
- Parameters:
- Return values
- SimpleFilter object
- Remarks
- Example
- Puts the trigger into enabled or disabled state.
- Sets the trigger's direction.
- Parameters:
- e_dir - enum that can have following values:
- DIRECTION_UPSTREAM ( 0 )
- DIRECTION_DOWNSTREAM ( 1 )
- DIRECTION_BOTH ( 2 )
- DIRECTION_NONE ( 4 )
- Example
- Gets the trigger's direction.
- SimpleFilter allows enabling /disabling the filter and setting data stream direction..
- Puts the filter into enabled or disabled state.
- Sets the filter's direction.
- Parameters:
- e_dir - enum that can have following values:
- DIRECTION_UPSTREAM ( 0 )
- DIRECTION_DOWNSTREAM ( 1 )
- DIRECTION_BOTH ( 2 )
- DIRECTION_NONE ( 4 )
- Example
- Gets the filter's direction.
- 6 PEGenOptions Object
- The IPERecOptions2 interface is a primary interface for PERecOptions object.
- The IgenOptions interface is a dual interface for the PEGenOptions object.
- Loads generation options from the specified file.
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- Saves generation options into the specified file.
- Parameters
- Return values
- Remarks
- If the specified file does not exist, it is created; if it exists, it is overwritten.
- Example
- WSH:
- C++:
- Resets the generation options to its initial state.
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- This interface is identical to the IGenOptions interface (see Page 69).
- The IPEGenOptions2 interface is a primary dual interface for the PEGenOptions object.
- This interface is derived from the IPEGenOptions interface.
- Sets the hardware configuration for the generation options.
- Parameters:
- Return values
- Remarks
- Example
- WSH:
- C++:
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- Sets the link width.
- Parameters:
- Return values
- Remarks
- Example
- WSH:
- C++:
- Sets the PCI Express Base Specification 1.0 compatibility mode.
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- Specifies whether to use the external or the internal reference clock
- Parameters
- Remarks
- Implemented for PETrainer ML. Not implemented for PETrainer EML.
- Disables/enables descrambling of incoming traffic.
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- Disables/enables scrambling of outgoing traffic.
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- Enables/disables automatic link configuration detection.
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- Allows lane reversal in the specified traffic direction.
- Parameters:
- Return values
- Remarks
- Example
- WSH:
- C++:
- Allows polarity inversion on the specified lane and specified traffic direction.
- Parameters:
- Return values
- Remarks
- Example
- WSH:
- For i = 1 To 4
- C++:
- Allows skew values to be set for each lane of outgoing traffic.
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- 7 PEPacket Object
- The PEPacket object represents a single packet of the recorded trace file.
- The PEPacket object can be created by calling IPETrace::GetBusPacket method (See Page 41)
- The IPacket interface is a dual interface for PEPacket object.
- Note: All methods of the IPacket interface are also available in the IPEPacket interface (see Page 57).
- Returns the packet timestamp in nanoseconds.
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- The IPEPacket interface is a primary dual interface for the PEPacket object.
- This interface is derived from the IPacket interface.
- Retrieves a raw packet representation.
- Parameters
- Return values
- Remarks
- Example
- ID = Analyzer
- While Param > 0
- Else
- DecToBin = Replace( Space(NeedLen - Len(Res)), " ", "0") & Res
- Sub BtnGetPacket_OnClick
- If Err.Number <> 0 Then
- Else
- NumberOfUnits = Packet.GetPacketData ( PACKETFORMAT_BYTES, PacketData)
- If Err.Number <> 0 Then
- For Each PacketByte In PacketData
- NBytes = NBytes + 1
- End If
- End Sub
- C++:
- SAFEARRAY* packet_safearray = packet_data.parray;
- Returns link width for this packet.
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- Returns start lane for this packet.
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- Returns direction (upstream/downstream) of this packet.
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- Returns an array of errors present in this packet.
- Parameters
- Return values
- Remarks
- Example
- WSH:
- C++:
- 8 PETraceErrors Object
- The PETraceErrors object represents the collection of errors that occurred in the recorded trace file.
- The PETraceErrors object can be created by calling ITrace::AnalyzerErrors method (see Page 45).
- The IAnalyzerErrors interface is a primary interface for the PETraceErrors object.
- Returns a zero based packet number from error collection
- Parameters
- Returns the number of errors in the trace.
- Parameters
- Remarks
- Example
- WSH:
- ' where "Running Disparity" errors occured
- Set Errors = Trace.AnalyzerErrors( 32 ) ' Running Disparity Error
- ErrorFile = CurrentDir & "\Output\PckLen_error_span_" &
- C++:
- IPETrace* pe_trace;
- 9 PEVScriptEngine Object
- The IVScriptEngine interface is a primary interface for PEVScriptEngine object.
- Remarks
- The IVScriptEngine interface is the primary dual interface for the PEVScriptEngine object.
- Property putting and getting current verification script name.
- Parameters
- Return values
- Remarks
- Example
- C++:
- IPETrace* pe_trace;
- IPEVerificationScript* pe_vscript = NULL;
- Parameters
- Return values
- Remarks
- Example
- C++:
- IPETrace* pe_trace;
- IPEVerificationScript* pe_vscript = NULL;
- Runs the verification script currently specified for this engine.
- Parameters
- Return values
- Remarks
- Example
- See C++ example to IVScriptEngine::VScriptName, Page 101.
- Changes the current verification script name and runs verification script .
- Parameters
- Return values
- Remarks
- Example
- C++:
- IPETrace* pe_trace;
- IPEVerificationScript* pe_vscript = NULL;
- Launches verification script.
- Return values
- Remarks
- Example
- C++:
- IPETrace* pe_trace;
- IPEVerificationScript* pe_vscript = NULL;
- VS_RESULT result = pe_vsengine ->LaunchVScript();
- Parameters
- Return values
- Remarks
- Example
- C++:
- IPETrace* pe_trace;
- IPEVerificationScript* pe_vscript = NULL;
- Parameters
- Return values
- Remarks
- Example
- C++:
- IPETrace* pe_trace;
- IPEVerificationScript* pe_vscript = NULL;
- WSH:
- Result = VSEngine.RunVScript
- MsgBox " MyIntVar = " & CStr(MyIntVar) & ", MyStrVar = " & MyStrVar
- Parameters
- Return values
- Remarks
- Example
- C++:
- IPETrace* pe_trace;
- IPEVerificationScript* pe_vscript = NULL;
- WSH:
- 10 PEVScriptEngine Object Events
- Example
- C++:
- 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 );
- IVScriptEngine vscript_engine = NULL;
- VBA: ( MS Excel )
- Public PETracer As PeAnalyzer
- Dim X As New VSEngineEventsModule...
- ScriptName = ThisWorkbook.Sheets("Sheet1").Cells(2, 2)
- If PETracer Is Nothing Then
- If PETracer Is Nothing Then
- Set X.VSEEvents = VSEngine
- Set X.VSEEvents = Nothing ' "Unsubscribe" for receiving VSE events
- Parameters
- Return values
- Remarks
- Make sure that C++ event handlers have __stdcall calling convention.
- Example
- C++:
- Public WithEvents VSEEvents As VScriptEngine
- Private Sub VSEEvents_OnVScriptReportUpdated(ByVal newLine As String, ByVal Tag As Long)
- ThisWorkbook.Sheets("Sheet1").Cells(LineIndex, 1) = newLine
- End Sub
- Fired when the verification script stops running.
- Parameters
- Return values
- Remarks
- Make sure that C++ event handlers have __stdcall calling convention.
- Example
- C++:
- HRESULT __stdcall CComplTestSink::OnVScriptFinished(
- USES_CONVERSION;
- Public WithEvents VSEEvents As VScriptEngine
- Dim ResString As String
- ThisWorkbook.Sheets("Sheet1").Cells(7, 2) = ResString
- Fired when running a verification script, calls the NotifyClient() function.
- Parameters
- Return values
- Remarks
- Example
- ThisWorkbook.Sheets("Sheet1").Cells(LineIndex, 1) = eventId
- If IsArray(eventBody) Then
- For Each Item In eventBody
- LineIndex = LineIndex + 1
- 11 PEAnalyzer Object Events
- END_SINK_MAP()
- Parameters
- Remarks
- Make sure the event handlers have __stdcall calling convention.
- Example
- Dim CurrentTrace
- C++:
- Parameters
- Return values
- Remarks
- Make sure the event handlers have __stdcall calling convention.
- Example
- Dim RecordingStatus
- End Sub
- C++:
- 12 CATCAnalyzerAdapter
- The Class ID and App ID for PEAnalyzer object are the following.
- Class ID: A0CB5386-38BA-4970-8782-3D1B707C3E5F
- Parameters
- Return values
- Remarks
- Example
- Sub BtnConnect_onclick
- Set Analyzer = AnalyzerAdapter.CreateObject("CATC.PETracer", RemoteServer.value )
- WSH:
- RemoteServer = "EVEREST"
- This method attaches the LeCroy analyzer object to the adapter.
- Parameters
- Return values
- Remarks
- Example
- Sub BtnConnect_onclick
- WSH:
- 'VBScript functioncreates object locally
- AnalyzerAdapter.Attach Analyzer ' Attach analyzer object to the adapter
- This method detaches the LeCroy analyzer object from the adapter.
- Parameters
- Return values
- Remarks
- Example
- Sub BtnConnect_onclick
- Set Analyzer = AnalyzerAdapter.CreateObject("CATC.PETracer", RemoteServer.value )
- Sub BtnDisconnect_OnClick
- WSH:
- RemoteServer = "EVEREST"
- This method helps to determine whether some automation object can be attached to the adapter.
- Parameters
- Return values
- Remarks
- Only LeCroy analyzer COM servers can be attached to the adapter.
- Example
- Sub BtnConnect_onclick
- 'Launch MS Excel instead of PETracer !!!
- If Not AnalyzerAdapter.IsValidObject( Analyzer ) Then
- 13 Teledyne LeCroy Internal Interfaces
- How to Contact Teledyne LeCroy