Application
Note
How to use Aeroflex PXI 3000 Series
COM interfaces in place of
ActiveX controls
The software architecture chosen for the Aeroflex PXI 3000
Series was originally based on ActiveX controls. As of October
2006 the software architecture changed to COM.
This application note describes the merits of COM versus
ActiveX and provides practical guidance on how to convert
applications written in LabView and VB from ActiveX controls
to COM objects.
For the very latest specifications visit
www.aeroflex.com
Introduction
The software architecture chosen for the Aeroflex PXI 3000
series was originally based on ActiveX controls. As of October
2006 the software architecture changed to COM.
This application note describes the merits of COM versus ActiveX
and provides practical guidance on how to convert applications
written in LabView and VB from ActiveX controls to COM objects.
Why move to the COM libraries instead of the ActiveX
OCX's?
•
ActiveX is in itself a particular type of COM.
•
In general, ActiveX components are not easy to use from
C/C++ programming environments whereas COM components provide a dual personality one of which is easy to use
from environments like VB and LabView and the other is
easier to use from C/C++ environments.
•
The COM components can address all of the programming
environments that the ActiveX components address and in
addition, they can be used in some environments within
which the OCX's cannot be used (NI TestStand is one such
case).
•
Moving to the COM components has made it possible to
rectify a number of problems present in the OCX that could
not have fixed without breaking binary compatibility with
existing applications.
•
The COM components are implemented as a lightweight
wrapper around an underlying DLL. The practical differences
between programming in environments like VB and LabView
between the ActiveX components and the COM components are very small. For new projects, productivity is not
effected to any significant degree. For existing projects the
port from using the ActiveX components to the COM components is fairly straight forward, although some time will
have to be invested in the port.
How to convert a LabVIEW program from using the
SigGen OCX to the SigGen COM object:
1) Open .vi
4) Disconnect the afSigGen OCX and connect the Automation
refnum output of 'Automation open'
5) Now for every SigGen property or method node, you will need
to 'reselect' the property/method for each node in the block
diragram. Also look for broken wires, these will indicate where
data types may have changed.
2) View block diagram
3) Add an Automation Open, a constant refnum and select the
afComSigGen type library
Please refer to the Getting Started with the afSigGen manual
(46892/678) for futher details.
Here we can see that the property of the IafCoSigGen has not
been selected - in this case it should be set to 'RF' (right-click,
properties/RF)
6) Once you have selected 'RF', you will need to re-select the
properties/methods connected to it.
9) If you have an input or output that was originally a boolean with
the OCX, you may need to add some code to convert it
7) After re-selecting the properties/methods, you should have no
broken wires.
8) Some OCX methods had optional parameters, with COM they
are no longer optional.
10) You should add a 'Automation Close' for the SigGen refnum
in the code where the program stops/exits.
In this case, loIsPlugin has to have a constant wired to it.
For the very latest specifications visit
www.aeroflex.com
Creating the object
The new afCoXXX object needs to be created explicitly (whereas
the OCX was implicitly created for you). The best place to do this
is in the MainPanel for the application, in Form_Load().
We also need to enable the event handling for errors, warnings
and IQProgress:
Private Sub Form_Load()
…
' Create the object here
Set <mySigGen> = New afCoSigGen
11) Once you have fixed all property/methods, then you can
delete the OCX container on the front panel.
' Enable the event handling here
<mySigGen>.EventOnError
= True
<mySigGen>.EventOnWarning
= True
<mySigGen>.EventOnIQProgress
= True
…
End Sub
Data Types
Visual Basic applications and COM objects How-to port
from OCX Components
The original ocxs defined data types and enums such as
mtModuleType and mtAF3010.
The purpose of this section is to assist in porting Visual Basic
applications that are using the OCX components to use the COM
objects instead.
Each of these needs to be replaced with the type defined in the
COM object, retaining as much of the original name as possible.
The general rule for data types is:
It will focus on general issues first, then specifics regarding the
use of afComSigGen and afComDigitizer.
General issues
All references to the previously used OCXs must be removed
from the Visual Basic Project. These will usually be found on the
main panel and may be hidden.
The COM objects then need to be added to the project. This is
done using the 'References' dialogue in Visual Basic (From the
menu select 'Project'->'References') and then making sure that
the 'afComCombiner', 'afComSigGen' or 'afComDigitiser' type
libraries are checked in the list of available references.
<ocx type> becomes AFCOMXXXXLib.afxxxxDll_<ocx type>_t
where <ocx type> is the original data type, XXXX is the name of
the components in use in upper case (SigGen, or Digitizer or
Combiner) , and xxxx is the same name, but as defined in the dll.
Hence:
Object
OCX Data Type COM Data Type
SigGen MtModuleType AFCOMSIGGENLib.afSigGenDll_mtModuleType_t
Digitizer MtModuleType AFCOMDIGITIZERLib.afDigitizerDll_mtModuleType_t
Combiner MtModuleType AFCOMCOMBINERLib.afCombinerDll_mtModuleType_t
Enumerated types change in a similar manner:
Defining the new component
In the definition section of the Main Panel Code, the object needs
to be defined (to replace the graphical ocx instance).
So in the case of the SigGen, we would have:
(where <mySigGen> is the name used by the original OCX component)
Public WithEvents <mySigGen> As afCoSigGen
We also need to tell VB that there is no help associated with this
component:
Attribute <mySigGen>.VB_VarHelpID = -1
<ocx enum> becomes AFCOMXXXXLib.afxxxxDll_<ocx enum>
So using the SigGen mtModuleType as an example:
OCX Enum
mtAF3010
mtAF3020
MtAFSIGGEN
MtAFPlugin
COM Enum
AFCOMSIGGENLib.afSigGenDll_mtAF3010
AFCOMSIGGENLib.afSigGenDll_mtAF3020
AFCOMSIGGENLib.afSigGenDll_mtAFSIGGEN
AFCOMSIGGENLib.afSigGenDll_mtPlugin
All other data types and enumerated types change in the same
way. Note that there may be the occasional inconsistency, but
these are easy to find as they will show up during the build
process. The correct values may then be identified using the
relevant help file.
Common changes to the OCX interface
Specific afDigitizer Issues
In all three components, the CheckFitted method has changed.
It no longer returns the state. This must be passed in as a reference parameter:
There are some changes to the afDigitizer API between the OCX
and COM versions:
Dim Fitted As Long
Call
mainPanel.<myObject>.RF.Options.CheckFitted(<option>,Fitted)
If (Fitted) Then
…
End If
All of the event handling callbacks need to be re-created using
the VB tools. The original code can then be copied into the new
code.
Capture Subsystem:
OCX API
COM API
ADCOverload
IQ ADCOverload.
IF. ADCOverload
IQ.Resolution
IQ.CaptComplete
IF.CaptComplete
IQ.CapturedSampleCount
IF.CapturedSampleCount
IQ.ListAddrCount
IF.ListAddrCount
IF.CaptMem
No longer supported
No longer supported
IQ.CaptMem
No longer supported
No longer supported
IQ.Abort
IF.Abort
IQ.GetAbsSampleTime
IF.GetAbsSampleTime
IQResolution
CaptComplete
CapturedSampleCount
ListAddrCount
CaptMemIF
CaptAscFileIF
CaptBinFileIF
CaptMemIQ
CaptAscFileIQ
CaptBinFileIQ
Abort
Other implementation pitfalls
Visual Basic defines Booleans as follows:
False = 0
True = -1
The COM objects define Booleans as follows:
GetAbsSampleTime
False = 0
True <> 0
Consequently, comparing BOOL values against 'False' is valid
because 'False' is unambiguous but comparing against 'True' is
not valid because there are many values that can be used to represent 'True'. In general it is better programming practice to check
against "not false" anyway.
In addition, various other methods and properties have been
copied to the capture subsystem, in both IQ and IF subsystems,
for a more coherent and intuitive interface:
OCX API
COM API
Trigger.Count
Capture.IQ.TriggerCount
Capture.IF.TriggerCount
Here is a sample of code illustrating the issue ( taken from the
afSigGen Soft Front Panel code)
Trigger.Detected
Example:
Trigger.GetTrigger
SampleNumber
Capture.IQ.GetTrigger
SampleNumber
Trigger.Arm
Capture.IF.GetTrigger
SampleNumber
Capture.IQ.TriggerArm
Capture.IF.TriggerArm
Capture.IF.TriggerDetected
Incorrect Code:
Dim Fitted As Long
Call mainPanel.afSigGen1.LO.Options.CheckFitted(99, Fitted)
If Fitted = True Then
get301xModelName = "AF3011 (LO)"
Else
get301xModelName = "AF3010 (LO)"
End If
Capture.IQ.TriggerDetected
The original methods/properties are still available in their original
structures and locations but are deprecated. It is prefered, especially for new applications, to use the new interface elements.
Correct implementation:
Dim Fitted As Long
Call mainPanel.afSigGen1.LO.Options.CheckFitted(99, Fitted)
If Fitted <> False Then
get301xModelName = "AF3011 (LO)"
Else
get301xModelName = "AF3010 (LO)"
End If
For the very latest specifications visit
www.aeroflex.com
Specific afCombiner issues
The API for the COM object differs considerably from that implemented in the OCX. When the decision to migrate to C DLL/COM
interfaces was made, it was decided to re-work the afCombiner
API to bring it in line with the afSigGen and afDigitizer interfaces.
This provides the customer with a unified API across all
components.
The following table identifies the differences between the OCX
and COM interfaces.
OCX API
COM API Equivalent
Boot()
EventOnError
EventOnWarning
Loss.AtoB
Loss.AtoD
Loss.AtoSum
Loss.BtoC
Loss.BtoSum
Loss.CtoD
Loss.CtoSum
Loss.Frequency
Loss.MeasureLosses
Loss.Optimize
TemperatureCorrection
Mode
ModelCode
Resource
BootInstrument
EventOnError
EventOnWarning
Loss.AToB
Loss.AToD
Loss.AToSum
Loss.BToC
Loss.BToSum
Loss.CToD
Loss.CToSum
Loss.Frequency
Loss.MeasureLosses
OptimizeTemperature
Correction
Mode
Resource.ModelCode
No equivalent for write
Resource.ResourceString for read
SerialNumber
Status
Comments
Different parameters
Different parameters
Passed as parameter to BootInstrument
Resource.SerialNumber
Value returned directly by BootInstrument
ClearErrors
CloseInstrument
ErrorCode
ErrorMessage
ErrorSource
EventOnError
EventOnWarning
OnError
OnWarning
Options.AvailableCount
Options.CheckFitted
Options.Disable
Options.Enable
Options.Information
Resource.IsActive
Resource.SessionId
New interface, same behaviour as afSigGen and afDigitizer
OCX vs COM API
For further information refer to the library help.
C++ Applications
For applications written in C++ using the OCX it is
recommended to port to com using the C++ wrapper provided.
For the very latest specifications visit
www.aeroflex.com
CHINA Beijing
Tel: [+86] (10) 6539 1166
Fax: [+86] (10) 6539 1778
GERMANY
Tel: [+49] 8131 2926-0
Fax: [+49] 8131 2926-130
SCANDINAVIA
Tel: [+45] 9614 0045
Fax: [+45] 9614 0047
CHINA Shanghai
Tel: [+86] (21) 5109 5128
Fax: [+86] (21) 5150 6112
HONG KONG
Tel: [+852] 2832 7988
Fax: [+852] 2834 5364
SPAIN
Tel: [+34] (91) 640 11 34
Fax: [+34] (91) 640 06 40
FINLAND
Tel: [+358] (9) 2709 5541
Fax: [+358] (9) 804 2441
INDIA
Tel: [+91] 80 5115 4501
Fax: [+91] 80 5115 4502
UK Burnham
Tel: [+44] (0) 1628 604455
Fax: [+44] (0) 1628 662017
FRANCE
Tel: [+33] 1 60 79 96 00
Fax: [+33] 1 60 77 69 22
KOREA
Tel: [+82] (2) 3424 2719
Fax: [+82] (2) 3424 8620
UK Cambridge
Tel: [+44] (0) 1763 262277
Fax: [+44] (0) 1763 285353
As we are always seeking to improve our products,
the information in this document gives only a general
indication of the product capacity, performance and
suitability, none of which shall form part of any contract. We reserve the right to make design changes
without notice. All trademarks are acknowledged.
Parent company Aeroflex, Inc. ©Aeroflex 2006.
UK Stevenage
Tel: [+44] (0) 1438 742200
Fax: [+44] (0) 1438 727601
Freephone: 0800 282388
USA
Tel: [+1] (316) 522 4981
Fax: [+1] (316) 522 1360
Toll Free: 800 835 2352
w w w.aeroflex.com
[email protected]
Part No. 46891/960, Issue 1, 11/06