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.
Teledyne LeCroy Automation API for PETracer/PETrainer Document Disclaimer The information contained in this document has been carefully checked and is believed to be reliable. However, no responsibility can be assumed for inaccuracies that may not have been detected. Teledyne LeCroy reserves the right to revise the information presented in this document without notice or penalty.
Teledyne LeCroy Automation API for PETracer/PETrainer Table of Contents 1 2 3 4 5 Introduction .......................................................................................................................................... 1 1.1 System Requirements .................................................................................................................... 1 1.2 Support Resources .........................................................................................................
Teledyne LeCroy Automation API for PETracer/PETrainer 5.1.5 IRecOptions::SetPostTriggerPercentage .............................................................................. 58 5.1.6 IRecOptions::SetTriggerBeep ............................................................................................... 59 5.1.7 IRecOptions::SetSaveExternalSignals .................................................................................. 60 5.1.8 IRecOptions::SetTraceFileName..................................
Teledyne LeCroy Automation API for PETracer/PETrainer 7.1.1 IPacket::GetTimestamp ....................................................................................................... 101 7.2 IPEPacket interface .................................................................................................................... 102 7.2.1 IPEPacket::GetPacketData ................................................................................................. 103 7.2.2 IPEPacket::GetLinkWidth ............
Teledyne LeCroy Automation API for PETracer/PETrainer 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.
Teledyne LeCroy Automation API for PETracer/PETrainer 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.
Teledyne LeCroy Automation API for PETracer/PETrainer All objects implement ISupportErrorInfo interface for easy error handling from the client.
Teledyne LeCroy Automation API for PETracer/PETrainer 3 PEAnalyzer Object The PEAnalyzer object is a top-level object of PETracer™ API. The PEAnalyzer object allows user to control the recording and traffic generation, open trace files, and access to the recording and generation options.
Teledyne LeCroy Automation API for PETracer/PETrainer 3.1 IAnalyzer interface 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 3.1.1 IAnalyzer::GetVersion HRESULT GetVersion ( [in] EAnalyzerVersionType version_type, [out, retval] WORD* analyzer_version ) Retrieves the current version of a specified subsystem.
Teledyne LeCroy Automation API for PETracer/PETrainer 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 file_name String providing the full pathname to the trace file trace Address of a pointer to the PETrace object interface Return values Unable to open file ANALYZERCOMERROR_UNABLEOPENFILE Remarks PETrace object is created via this method call, if the call was successful.
Teledyne LeCroy Automation API for PETracer/PETrainer 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 gen_file_name String providing the full pathname to the generation file reserved1 Reserved for future use reserved2 Reserved for future use Return values Unable to open file Unable to start generation (invalid state, etc.
Teledyne LeCroy Automation API for PETracer/PETrainer 3.1.4 IAnalyzer::StopGeneration HRESULT StopGeneration ( ) Stops any current generation in progress. Return values Unable to stop generation (invalid state, etc.) ANALYZERCOMERROR_UNABLESTARTGENERATION 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.
Teledyne LeCroy Automation API for PETracer/PETrainer 3.1.5 IAnalyzer::StartRecording HRESULT StartRecording ( [in] BSTR ro_file_name ) Starts recording with the 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 returns.
Teledyne LeCroy Automation API for PETracer/PETrainer 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.
Teledyne LeCroy Automation API for PETracer/PETrainer 3.1.6 IAnalyzer::StopRecording HRESULT StopRecording ( [in] BOOL abort_upload ) Stops recording started by the IAnalyzer::StartRecording (see Page 10) method.
Teledyne LeCroy Automation API for PETracer/PETrainer 3.1.7 IAnalyzer::MakeRecording HRESULT MakeRecording ( [in] BSTR ro_file_name, [out, retval] IDispatch** trace ) Makes recording with the specified recording options file.
Teledyne LeCroy Automation API for PETracer/PETrainer 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 do_file_name String providing the full pathname to a display options file Return values ANALYZERCOMERROR_UNABLELOADDO Unable to load the display options file Remarks Use this method if you want to filter traffic of some type.
Teledyne LeCroy Automation API for PETracer/PETrainer 3.1.9 IAnalyzer::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 PERecOptions object interface Return values Remarks PERecOptions object is created via this method call, if the call was successful. Example WSH: Set Analyzer = WScript.CreateObject( “CATC.
Teledyne LeCroy Automation API for PETracer/PETrainer 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.
Teledyne LeCroy Automation API for PETracer/PETrainer 3.2 IPEAnalyzer interface The IPEAnalyzer interface is a dual interface for the PEAnalyzer object. This interface is derived from the IAnalyzer interface. The IPEAnalyzer interface implements all methods from IAnalyzer interface plus the following: GetGenerationOptions ResumeGeneration GetLinkStatus Note: All methods implemented by the IPEAnalyzer interface are also implemented by the IPEAnalyzer2 interface (see Page 20).
Teledyne LeCroy Automation API for PETracer/PETrainer 3.2.1 IPEAnalyzer::GetGenerationOptions HRESULT GetGenerationOptions ( [out, retval] IDispatch** generation_options ) Retrieves the interface for access to the generation options. Parameters generation_options Address of a pointer to the PEGenOptions object interface Return values Remarks PEGenOptions object is created via this method call, if the call was successful. Example WSH: Set Analyzer = WScript.CreateObject( “CATC.
Teledyne LeCroy Automation API for PETracer/PETrainer 3.2.2 IPEAnalyzer::ResumeGeneration HRESULT ResumeGeneration ( ) Resumes generation if it was previously paused. Return values Remarks Example C++: IPEAnalyzer* poAnalyzer; . . . try { poAnalyzer->ResumeGeneration(); } catch ( _com_error& er) { if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("PETracer client"), MB_OK ); else ::MessageBox( NULL, er.
Teledyne LeCroy Automation API for PETracer/PETrainer 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 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: “Detect.Quiet”, “Detect.Active”, “Polling.Active”, “Polling.
Teledyne LeCroy Automation API for PETracer/PETrainer 3.3 IPEAnalyzer2 interface The IPEAnalyzer2 interface is a dual interface for the PEAnalyzer object. This interface is derived from the IPEAnalyzer interface.
Teledyne LeCroy Automation API for PETracer/PETrainer 3.3.1 IPEAnalyzer2::GetHardwareInfo HRESULT GetHardwareInfo ( [in] EHardwareType type, [out, retval] int* info ) Returns information about the hardware (PETracer/PETrainer™) connected.
Teledyne LeCroy Automation API for PETracer/PETrainer return 1; } try { tracer_type = poAnalyzer->GetHardwareInfo( HARDWARETYPE_PETRACER ); } catch ( _com_error& er ) { if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("PETracer client"), MB_OK ); else ::MessageBox( NULL, er.
Teledyne LeCroy Automation API for PETracer/PETrainer 3.3.2 IPEAnalyzer2::ResetHardware HRESULT ResetHardware ( [in] EHardwareType type, [in] EResetType reset_type ) Resets the hardware specified.
Teledyne LeCroy Automation API for PETracer/PETrainer 3.4 IPEAnalyzer3 interface The IPEAnalyzer3 interface is a primary dual interface for the PEAnalyzer object. This interface is derived from the IPEAnalyzer2 interface.
Teledyne LeCroy Automation API for PETracer/PETrainer 3.4.1 IPEAnalyzer3::StartImportFile HRESULT StartImportFile ( [in] BSTR file_name ) Begins process of importing specified file into a trace file. Parameters file_name String providing the full pathname to the import file Return values S_OK S_FALSE Import started successfully Error starting import Remarks The format of the import file is defined in a proprietary Teledyne LeCroy specification. Please contact Teledyne LeCroy PSG for details.
Teledyne LeCroy Automation API for PETracer/PETrainer 4 PETrace Object PETrace object represents the recorded trace file.
Teledyne LeCroy Automation API for PETracer/PETrainer 4.1 ITrace interface The ITrace interface is a dual interface for the PETrace object. It implements the following methods: GetName ApplyDisplayOptions Save ExportToText Close ReportFileInfo ReportErrorSummary GetPacket GetPacketsCount GetTriggerPacketNum AnalyzerErrors Note: All methods of ITrace interface are also available in IPETrace (see Page 41).
Teledyne LeCroy Automation API for PETracer/PETrainer 4.1.1 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( “CATC.PETracer” ) CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” ) ) Set Trace = Analyzer.
Teledyne LeCroy Automation API for PETracer/PETrainer 4.1.2 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 if you want to filter traffic of some type in the recorded or opened trace.
Teledyne LeCroy Automation API for PETracer/PETrainer 4.1.3 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.
Teledyne LeCroy Automation API for PETracer/PETrainer 4.1.4 ITrace::ExportToText HRESULT ExportToText ( [in] BSTR file_name, [in, defaultvalue(-1)] long packet_from, [in, defaultvalue(-1)] long packet_to ); Exports the trace into a text file while allowing you to specify a range of packets.
Teledyne LeCroy Automation API for PETracer/PETrainer Here is a snippet of an exported text file: File C:\data.pex. From Packet #1880 to Packet #1890. Packet# _______|_______________________________________________________________________ Packet(1880) Downstream DLLP ACK AckNak_Seq_Num(3388) CRC 16(0xBB63) _______| Time Stamp(0002 . 069 437 652 s) _______|_______________________________________________________________________ Packet(1881) Upstream SKIP COM(K28.5 ) SKIP Symbols(K28.0 K28.0 K28.
Teledyne LeCroy Automation API for PETracer/PETrainer Example WSH: Set Analyzer = WScript.CreateObject( “CATC.PETracer” ) CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” ) ) Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec") Trace.ApplyDisplayOptions CurrentDir & "Input\test_do.opt" Trace.ExportToText CurrentDir & "Output\text_export.txt" C++: IPETrace* pe_trace; TCHAR file_name[_MAX_PATH]; LONG packet_from; LONG packet_to; . . .
Teledyne LeCroy Automation API for PETracer/PETrainer 4.1.5 ITrace::Close HRESULT Close ( ) Closes the trace. Parameters Return values Remarks Closes the current trace, but does not release the interface pointer. Call IUnknown::Release method right after this method call. No ITrace method call succeeds after calling ITrace::Close method. (Currently, there is no need to call ITrace::Close directly since IUnknown::Release closes the trace.
Teledyne LeCroy Automation API for PETracer/PETrainer 4.1.6 ITrace::ReportFileInfo HRESULT ReportFileInfo ( [in] BSTR file_name ) Saves trace information into a specified HTML file. Parameters file_name String providing the full pathname to a file where the trace information report is stored Return values ANALYZERCOMERROR_UNABLESAVE Unable to create the trace information report Remarks Creates a new trace information file if the file specified in the file_name parameter does not exist.
Teledyne LeCroy Automation API for PETracer/PETrainer 4.1.7 ITrace::ReportErrorSummary HRESULT ReportErrorSummary ( [in] BSTR file_name ) Saves trace error summary information into the specified text file. Parameters file_name String providing the full pathname to a file where the error summary report is stored. Return values ANALYZERCOMERROR_UNABLESAVE Unable to create trace information report Remarks This method doesn’t work on Multisegment traces.
Teledyne LeCroy Automation API for PETracer/PETrainer Here is an example of data stored using this method call: Error report for ErrorFinding_loop.pex recording file.
Teledyne LeCroy Automation API for PETracer/PETrainer Example WSH: Set Analyzer = WScript.CreateObject( “CATC.PETracer” ) CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” ) ) Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec") Trace.ReportErrorSummary CurrentDir & "Output\error_summary.txt" C++: IPETrace* pe_trace; TCHAR file_name[_MAX_PATH]; . . . try { pe_trace->ReportErrorSummary( file_name ); } catch ( _com_error& er) { if (er.Description().
Teledyne LeCroy 4.1.8 Automation API for PETracer/PETrainer ITrace::GetPacket HRESULT GetPacket ( [in] long packet_number, [in, out] VARIANT* packet, [out, retval] long* number_of_bytes ) Retrieves a raw packet representation in the PACKETFORMAT_BYTES format (see IPacket interface for details, Page 85).
Teledyne LeCroy Automation API for PETracer/PETrainer Example VBScript:
