Deprecated
xx
PPI.COM
ZZZ
TLA Pattern Generator Programmatic Interface
PrintedHelpDocument
www.tektronix.com
077-0396-00
Deprecated
Copyright © Tektronix. All rights reserved. Licensed software products are owned by Tektronix or its subsidiaries
or suppliers, and are protected by national copyright laws and international treaty provisions.
Tektronix products are covered by U.S. and foreign patents, issued and pending. Information in this publication
supersedes that in all previously published material. Specifications and price change privileges reserved.
TEKTRONIX and TEK are registered trademarks of Tektronix, Inc.
Contacting Tektronix
Tektronix, Inc.
14200 SW Karl Braun Drive
P.O . B o x 5 00
Beaverto
USA
For product information, sales, service, and technical support:
n, OR 97077
In North America, call 1-800-833-9200.
Worl d wide , vis it www.tektronix.com to find contacts in your area.
Deprecated
Table of Contents
Tektronix Logic Analyzer Family 1
Pattern Generator Programmatic Interface (PPI) Manual 1
Table of Contents 3
Introduction ......................................................................................................5
General Characteristics ...................................................................................5
Deliverables .....................................................................................................7
Setting up PPI............................................................................................7
Objects and Interfaces .....................................................................................7
Setting up PPI 8
Client application on the TLA 700....................................................................8
Client application across the network ..............................................................8
Share level access ....................................................................................8
User level access ......................................................................................9
Client machine using Microsoft Windows NT ..................................................9
Client machine using Microsoft Windows 95 ...................................................9
Share-level access ..................................................................................10
User-level access ....................................................................................10
Client machine using Microsoft Windows 98 .................................................11
Share-level access ..................................................................................11
User-level access ....................................................................................11
Client machine using other platforms ............................................................12
Registering/Unregistering PPI........................................................................12
Server side Registration/UnRegistration .................................................12
Other Issues with DCOM.........................................................................13
Connecting to the Tektronix Pattern Generator Application (Server) ............14
Disconnecting from the Tektronix Pattern Generator Server.........................14
Samples .........................................................................................................14
Sample Visual Basic Client (Dispatch) ..........................................................15
Sample Visual Basic Client (Vtable) ..............................................................16
Other Samples ...............................................................................................17
Errors .............................................................................................................17
Messages.......................................................................................................17
Slot Numbers and Expansion Mainframes ....................................................17
Reference 18
Quick Reference ............................................................................................18
Application Object....................................................................................18
System Object .........................................................................................18
Module Object .........................................................................................19
Listing of Methods..........................................................................................20
IPGApplication::GetSystem.....................................................................20
IPGSystem::GetNumModuleSlots...........................................................21
IPGSystem::GetFirstModuleSlot .............................................................22
IPGSystem::GetSWVersion ....................................................................23
IPGSystem::GetDiagnosticsStatus..........................................................24
IPGSystem::GetModulePropertiesBySlot................................................25
IPGSystem::GetModuleTypeBySlot ........................................................27
IPGSystem::GetModuleBySlot ................................................................29
IPGSystem::GetModuleByName.............................................................31
Tektronix Pattern Generator PPI Manual Page 3 of 56
Deprecated
IPGSystem::GetModuleNames ...............................................................32
IPGSystem::LoadSystem ........................................................................33
IPGSystem::SaveSystem........................................................................35
IPGSystem::Run......................................................................................36
IPGSystem::Stop.....................................................................................37
IPGSystem::GetRunStatus......................................................................38
IPGModule::LoadModule.........................................................................39
IPGModule::SaveModule ........................................................................40
IPGModule::Import ..................................................................................42
IPGModule::Export ..................................................................................44
IPGApplication::ShowWindow.................................................................46
IPGModule::SetClockMode.....................................................................47
IPGModule::SetClockPeriod....................................................................48
IPGModule::SetClockThreshold..............................................................49
IPGModule::SetClockPolarity..................................................................50
IPGModule::SetOutputLevel....................................................................51
IPGModule::GetGroupNames .................................................................52
IPGModule::GetGroupSize......................................................................53
IPGModule::GetProbeChannelNames ....................................................54
Miscellaneous Topics 55
Tektronix TLA Data Exchange Format ..........................................................55
File Format: .............................................................................................55
Header Info Syntax:.................................................................................56
Group Details Syntax: .............................................................................56
Rules: ......................................................................................................56
Tektronix Pattern Generator PPI ManualPage 4 of 56
Deprecated
Introduction
The Tektronix Pattern Generator Programmatic Interface (PPI) is based on Microsoft’s
Component Object Model (COM). It gives the Tektronix Pattern Generator the ability to be
controlled from a separate user program running on the Tektronix Pattern Generator or on a
remote host. PPI provides the ability to control the pattern generator modules to be controlled by
third party applications. The following diagram shows the different ways this can be achieved.
The Tektronix Pattern Generator application is called the server and the user program is called
the client.
• Case 1 shows the user program is running on the Tektronix Pattern Generator and
communicates with the Tektronix Pattern Generator application using Microsoft COM.
• Case 2 shows the user program running on another PC and communicating with the
Tektronix Pattern Generator via Microsoft DCOM (Distributed COM).
• Case 3 shows the user program is running on a UNIX workstation and communicates
with the Tektronix Pattern Generator application via DCOM provided by a third party
vendor. In either of these cases, the user program may talk to other instruments
using whatever means required.
The user program may be written in any language or programming environment that supports
COM. Some examples are Visual C++ and Visual Basic.
General Characteristics
Some general characteristics of the programmatic interface are as follows:
• All of the exported server interfaces are dual interfaces (they support static and dynamic
binding).
• The application must be fully initialized before a client attempts to connect to it. This
includes dismissing any diagnostic errors that occur at startup time.
• If a client attempts to connect to the application before it is fully initialized, it will receive an
error indicating result in an Error "access is denied".
• Local clients running on the TLA 700 will connect to an existing instance of the server, if
there is one. If the server is not already running, it will be launched automatically.
Tektronix Pattern Generator PPI Manual Page 5 of 56
Deprecated
Because of restrictions imposed by Microsoft Windows 98, remote clients can’t launch
the server automatically. The server needs to be explicitly started to initiate COM
connection.
• When a client connects to the Tektronix Pattern Generator server application, the main
window of the server application will be visible.
Remote clients can hide the server’s main window via PPI. If the window is visible, users
can directly interact with the Tektronix Pattern Generator server application. The main
window status will have indicator to shown that a client is connected.
• The Tektronix Pattern Generator server application will not be terminated at the end of a
client connection. The server window is always made visible when all clients have
disconnected.
• PPI will operate within the main thread of the application.
Tektronix Pattern Generator PPI ManualPage 6 of 56
Deprecated
Deliverables
You will be provided with the following:
• Tektronix Pattern Generator executable that exports COM interfaces
• PPI documentation in online help
• Type library
• Header files for interface and error codes
• Auxiliary scripts/programs/instructions to set up DCOM on a client machine
• Sample client applications using Visual C++, Visual Basic and perhaps other
languages.
Setting up PPI
Tektronix Pattern Generator Server. A separate installation program is not necessary to set up
PPI on the TLA 700.
The Tektronix PG application installation program will perform the necessary setup install and
configure the PPI.
Remote Clients. There will be a separate installation program to set up PPI on remote client
machines running Microsoft Windows NT/95/98 clients.
If customers are running clients on Microsoft Windows 95 machines, they must install DCOM for
Microsoft Windows 95 on their client machine. Please refer to Appendix A on instructions on
setting up remote Windows 95 clients.
Objects and Interfaces
The programmatic interface for the Tektronix Pattern Generator consists of three kinds of objects,
Application, System, and Module.
Application. The user creates an Application object to initially connect to the application and to
subsequently obtain a reference to a System object. The Application object exports a single
interface called IPGApplication.
System. The System object provides methods for configuration, run control and save and load
operations. Every client must obtain a reference to a System object before they can obtain
references to module objects. The System object exports a single interface called IPGSystem.
Module. The Module object provides methods for module configuration, and obtaining PG
statistics. Module object export a single interface called IPGModule.
Unless otherwise specified, all methods are synchronous and wait for the completion of the
operation before returning.
Tektronix Pattern Generator PPI Manual Page 7 of 56
Deprecated
Setting up PPI
This document describes the steps you need to take to set up PPI.
We will use install directory to refer to the directory where PPI client has been installed on your
client machine. This directory is C:\Program Files\ Tektronix Pattern Generator by default.
The type library to be used with PPI is Tlapg.tlb. After you have finished the following setup
procedure, this file will be located in C:\Program Files\ Tektronix Pattern Generator \System\PPI
on the TLA 700 and in install directory\System\PPI on your PPI client machine.
Client application on the TLA 700
No special setup is required if the Tektronix Pattern Generator application has already been
installed.
Do the following to demonstrate PPI:
1. Start the Tektronix Pattern Generator application on the TLA 700.
2. Run
C:\Program Files\ Tektronix Pattern Generator \Samples\PPI Samples\Vc++\test
client\testclient.exe.
Click the Connect button to see if the client can connect to the Tektronix Pattern Generator.
Client application across the network
Do the following steps:
1. Install and configure TCP/IP.
2. You may choose to have share-level or user-level access to the TLA 700 as provided
by Microsoft Windows 98. This is done in the Control Panel>Network>Access Control
page.
Share-level access allows a password to be assigned to each shared resource. User-level access
allows a group of users to have access to each shared resource. For Microsoft Windows 98 only
networks, share-level access is the only option.
Choose between share-level access and user-level access and perform the following steps:
NOTE: For PPI to work with share-level access, authentication is turned off and any COM client
can call into a COM server running on the Tektronix Pattern Generator.
Share level access
Do the following steps:
1. In Control Panel>Network>Access Control, choose share-level access.
2. Re-boot the machine.
3. Double-click
C:\Program Files\Tektronix Pattern Generator\System\PPI\Share Level Access Server.reg
4. Re-boot the machine.
Tektronix Pattern Generator PPI ManualPage 8 of 56
Deprecated
User level access
Do the following steps:
1. In Control Panel>Network>Access Control, choose user-level access control and
enter the name of the domain that will be used to validate user access.
2. Re-boot the machine.
3. Double-click C:\Program Files\Tektronix Pattern Generator\System\PPI\User Level
Access Server.reg
4. Re-boot the machine.
Start the Tektronix Pattern Generator application on the TLA.
You can switch between user-level and share-level access later by redoing the procedure from
Step 3 onwards.
Client machine using Microsoft Windows NT
Note: The user requires administrative privileges to perform this setup.
1. Install and configure TCP/IP.
2. Run the Tektronix PPI Client install program supplied with the Tektronix Pattern
Generator.
3. Depending on the type of access control you chose for the Tektronix Pattern
Generator, double-click install dir ectory\System\PPI\Share Level Access Client.reg or
User Level Access Client.reg
4. Re-boot the client machine.
5. Run dcomcnfg.
6. Double-click Tlapg in the Applications page.
7. In the Location page, check the Run application on the follow ing computer box. Enter
the name of the TLA 700 machine in the edit field.
To verify that setup is complete:
1. Run ins tall directory \Samples\PPI Samples\Vc++\test client\testclient.exe on the client
machine.
2. Click the Connect button to see if the client can connect to the TLAPG. (The first time
you connect it may take a few minutes.)
Client machine using Microsoft Windows 95
Do the following steps:
1. Install and configure TCP/IP.
2. Run the Tektronix PPI Client install program supplied with the Tektronix Pattern
Generator.
3. Download and install the following from Microsoft's web site. Re-boot after each
installation.
http://www.microsoft.com/com/dcom95/download-f.htm:
• Distributed COM for Microsoft Windows 95 (DCOM95)
Tektronix Pattern Generator PPI Manual Page 9 of 56
Deprecated
• Dcomcnfg (DCOM configuration utility)
The version of DCOM for Microsoft Windows 95 that was tested with PPI was 1.1
Dcomcnfg will run only if user-level access is enabled. See the following step.
You must use share-level or user-level access as chosen for the Tektronix Pattern Generator.
This is done in the Control Panel>Network>Access Control page.
Share-level access
1. In Control Panel>Network>Access Control, choose share-level access.
2. Re-boot the machine.
3. Double-click ins tall dir ec tor y \System\PPI\Share Level Access Client.reg
4. Re-boot the machine.
User-level access
1. In Control Panel>Network>Access Control, choose user-level access control and
enter the name of the domain that will be used to validate user access.
2. Re-boot the machine.
3. Double-click ins tall dir ec tor y \System\PPI\User Level Access Client.reg
4. Re-boot the machine.
Do the following steps if you have user-level access enabled:
1. Run dcomcnfg.
2. Double-click Tektronix Pattern Generator Application in the Applications page.
3. In the Location page, uncheck the Run application on this computer box and check
the R un application on the followin g computer box. Enter the name of the TLA 700
machine in the edit field.
Do the following steps if you have share-level access enabled:
1. Run regedit.
2. Click on the following registry key.
HKEY_CLASSES_ROOT\AppID\{ EF9B47D6-99AD-11d3-A413-0004ACAEB013 }
3. Using Edit>New>StringValue, add a named value RemoteServerName.
4. Click on the new value RemoteServerName and select Edit>Modify.
5. Enter the name of the TLA 700 machine as its value.
Do the following to verify that setup is complete:
1. Run install directory\Samples\PPI Samples\Vc++\test client\testclient.exe on the client
machine.
2. Click the Connect button to see if the client can connect to the TLAPG.
(The first time you connect it may take a few minutes.)
You can switch between user-level and share-level access later by uninstalling Tektronix PPI
Client and DCOM95 via the Control Panel and redoing the procedure from Step 2 onwards.
Tektronix Pattern Generator PPI ManualPage 10 of 56
Deprecated
Client machine using Microsoft Windows 98
Do the following steps if using Microsoft Windows 98:
1. Install and configure TCP/IP.
2. Run the Tektronix PPI Client install program supplied with the Tektronix Pattern
Generator.
3. You must use share-level or user-level access as chosen for the Tektronix Pattern
Generator. This is done in the Control Panel>Network>Access Control page.
Share-level access
Do the following steps if you have share access enables:
1. In Control Panel>Network>Access Control, choose share-level access.
2. Re-boot the machine.
3. Double-click ins tall dir ec tor y \System\PPI\Share Level Access Client.reg
4. Re-boot the machine.
User-level access
Do the following steps:
1. In Control Panel>Network>Access Control, choose user-level access control and
enter the name of the domain that will be used to validate user access.
2. Re-boot the machine.
3. Double-click ins tall dir ec tor y \System\PPI\User Level Access Client.reg
4. Re-boot the machine.
Do the following if you have user-level access enabled:
1. Run dcomcnfg.
2. Double-click Tektronix Pattern Generator Application in the Applications page.
3. In the Location page, uncheck the Run application on this computer box and check
the Run application on the following computer box. Enter the name of the TLA 700
machine in the edit field.
Do the following if you have share-level access enabled:
1. Run regedit.
2. Click on the following registry key
HKEY_CLASSES_ROOT\AppID\{ EF9B47D6-99AD-11d3-A413-0004ACAEB013 }
3. Using Edit>New>StringValue, add a named value RemoteServerName.
4. Click on the new value RemoteServerName and select Edit>Modify.
5. Enter the name of the TLA 700 machine as its value.
Do the following to verify that setup is complete:
1. Run install directory\Samples\PPI Samples\Vc++\test client\testclient.exe on the client
machine.
2. Click the Connect button to see if the client can connect to the TLAPG. (The first time
you connect it may take a few minutes.)
Tektronix Pattern Generator PPI Manual Page 11 of 56
Deprecated
You can switch between user-level and share-level access later by redoing the procedure from
Step 3 onwards.
Client machine using other platforms
If the client application requires use of the type library, it may be generated on your platform using
Tlapg.IDL in C:\Program Files\Tektronix Pattern Geneartor\System\PPI\src on the TLA 700.
Make sure you perform the following steps:
1. Ensure that DCOM is working on your platform.
2. Merge
C:\Program Files\ Tektronix Pattern Generator\System\PPI\Client.reg on the TLA 700
into your registry.
3. Depending on the type of access control you chose for the Tektronix Pattern
Generator, merge
C:\Program Files\ Tektronix Pattern Generator\System\PPI\Share Level Access
Client.reg or User Level Access Client.reg on the TLA 700 into your registry.
4. Add a string value named RemoteServerName to the key
HKEY_CLASSES_ROOT\AppID\{EF9B47D6-99AD-11d3-A413-0004ACAEB013 }
5. Enter the name of the TLA 700 machine as its value.
Registering/Unregistering PPI
Server side Registration/UnRegistration
The server side needs both tlapg server and tlapg proxy/stub dll has to be registered from
command line.
Do the following to register the server:
Tlapg /RegServer from command line of appropriate directory
Do the following to Unregister the server:
Tlapg /UnregServer from command line of appropriate directory
Do the following to register the proxy/stub dll:
Regsvr32 Tlapgproxy .dll
Do the following to Unregister the proxy/stub dll
Regsvr32 /u Tlapgproxy .dll
Client side Registration
Client side registration also needs both of the above command lines.
When the registration is complete open the DCOMCNFG tool from command line and select the
tlapg properties.
Tektronix Pattern Generator PPI ManualPage 12 of 56
Deprecated
To set the location of component running from "Run application from the following computer"
option. Also give the remote machine name. In identity page select "interactive user" option.
Other Issues with DCOM
If the server ( Tlapg ) is going to run in Windows 95/98 DCOM software should be installed prior
to run any DCOM application and also the Server part should be started first before any clients
get connected to it.
Also the Windows 95/98 registry needs two entries for DCOM enabling.
EnableDCOM ‘Y’
EnableRemoteClient ‘Y’
Both of these entries should be done in the following:
HKEY_LOCAL_MACHINE\Microsoft\Ole directory in registry
Tektronix Pattern Generator PPI Manual Page 13 of 56
Deprecated
Connecting to the Tektronix Pattern Generator Application (Server)
Client applications connect to the Tektronix Pattern Generator server by creating an Application
object. For example, in Visual Basic,
‘Establish connection to TLA PG.
Dim App As Object
Set App = CreateObject("Tlapg.Application")
Once the Application object has been created, the client can call methods on it to get references
to System and Module objects.
Disconnecting from the Tektronix Pattern Generator Server
A client application that has connected to the TLAPG server may disconnect by deleting the
reference to the Application object. For example, in Visual Basic,
‘Disconnect from TLA PG.
Set App = Nothing
Samples
As mentioned previously, all of the interfaces exported by the server are dual interfaces for
example, they support static and dynamic binding.
Click on one of the following buttons to show the use of dual binding. The rest of the code
samples in this document use the dispatch portion of each dual interface (dynamic binding).
Sample Visual Basic Client (Dispatch) on page 15
Sample Visual Basic Client (Vtable) on page 16
Other Samples on page 17
Tektronix Pattern Generator PPI ManualPage 14 of 56
Deprecated
Sample Visual Basic Client (Dispatch)
Run
End Sub
Private Sub Run()
‘Do pattern generation. Wait for it to complete.
System.Run
Do
Status = System.GetRunStatus
Loop While (Status = 0)
End Sub
Tektronix Pattern Generator PPI Manual Page 15 of 56
Deprecated
Sample Visual Basic Client (Vtable)
The above client sample has been repeated below, using the vtable part of the dual interfaces.
Dim App As IPGApplication
Dim System As IPGSystem
Dim LA As IPGModule
Dim Status As Long
Dim S As String
Dim Data As Variant
Private Sub Form_Load()
'Connect to server.
Set App = CreateObject("Tlapg.Application ")
'Get system pointer.
Set System = App.GetSystem
'NOTE: To load a system, fill in system path.
System.LoadSystem("<path>")
'Run pattern generation.
Run
End Sub
Private Sub Run()
'Do pattern generation. Wait for it to complete.
System.Run
Do
Status = System.GetRunStatus
Loop While (Status = 0)
End Sub
Tektronix Pattern Generator PPI ManualPage 16 of 56
Deprecated
Other Samples
For sample client programs, go to Start > Programs > Tektronix Pattern Generator > PPI
Samples.
Errors
All methods in all interfaces of PPI return an HRESULT (or SCODE). Refer to tlapgerror.h for
possible error codes.
Additional error information is communicated as follows:
• Objects that use the dispatch portion of the dual interface can use the exception
information argument of the Invoke method.
• Objects that use the Vtable portion of the dual interface can use error objects. When an
HRESULT indicates an error, the client can call the standard function GetErrorInfo() to get
more detailed information about the error.
When a method returns an error, output arguments are undefined and should not be used.
Refer to the sample programs for examples on handling errors.
Messages
Tektronix Pattern Generator Application has instances where the user is asked to confirm a
particular operation. For example, before loading a system, the user is asked whether the current
system should be saved before the load operation. Since it is not possible to ask questions
through the programmatic interface, the application will always proceed with the original operation
as though the question were never asked. In the previous example, the load operation would
proceed without saving the current system.
Slot Numbers and Expansion Mainframes
In PPI, the slot numbers for expansion mainframes are specified by extending the slot numbers
for the mainframe.
For example, consider a system configuration consisting of a TLA720 benchtop mainframe with 2
expansion frames each containing 13 slots. The slot numbers would be as follows:
Mainframe: Slots 0-12
Expansion 1: Slots 13-25
Expansion 2: Slots 26-38
Tektronix Pattern Generator PPI Manual Page 17 of 56
Loading...