TekVISA Programmer Manual - Tektronix

1 , , , TektronixTektronix, ,OR97077 USAF orproductinformation,sales,service,andte chnicalsupport:HInNorthAmerica, , of ,INSTRR esource,SOCKETR esource, ,Attributes, (vi,protocol) (vi,buf,count,retCount) (vi,buf,count,retCount) (vi) (vi) (vi,eventType,mechanism) (vi,eventType,mechanism) (vi,eventType,mechanism,context) (vi,eventType,context,userHandle) (findList,instrDesc) (sesn,expr,findList,retCount,instrDesc) (vi,mask) (vi,attribute,attrState) (vi,eventType,handler,userHandle) (vi,lockType,timeout,requestedKey,access Key) (sesn,rsrcName,accessMode,timeout,vi) (sesn) (sesn,rsrcName,intfType,intfNum) (vi,writeFmt,<arg1,arg2,..>) (vi,writeFmt,readFmt,<arg1,arg2,..>) (vi,buf,count,retCount) (vi,buf,count,jobId) (vi,status) (vi,fileName,count,retCount) (vi,readFmt,<arg1,arg2,..>) (vi,attribute,attrState) (vi,mask,size) (vi,buf,writeFmt,<arg1,arg2.)

2 >) (vi,buf,readFmt,<arg1,arg2,..>) (vi,status,desc) (vi,degree,jobId) (vi,eventType,handler,userHandle) (vi) (vi,bmRequestType,bRequest,wValue,wIndex ,wLength,buffer,retCount) (vi,bmRequestType,bRequest,wValue,wIndex ,wLength,buffer) (vi,writeFmt,params) (vi,writeFmt,readFmt,params) (vi,readFmt,params) (vi,buf,writeFmt,params) (vi,buf,readFmt,params) (vi,inEventType,timeout,outEventType,out Context) (vi,buf,count,retCount) (vi,buf,count,jobId) (vi,fileName,count,retCount) of FiguresFigure1--1 : : : : :C++ControlsToolbarandForm,Code, of : :viAssertTrigger() :viAssertTrigger() :viAssertTrigger() :viBufRead() :viBufRead() :viBufRead() :SpecialValueforretCountParameterwithviB ufRead() :viBufWrite() :viBufWrite() :viBufWrite() :SpecialValueforretCountParameterwithviB ufWrite() :viClear() :viClear() :viClear() :viClose() :viClose() :viClose().

3 ViDisableEvent() :viDisableEvent() :viDisableEvent() :SpecialValuesforeventTypeParameterwithv iDisableEvent() :SpecialValuesformechanismParameterwithv iDisableEvent() :viDiscardEvents() :viDiscardEvents() :viDiscardEvents() :SpecialValuesforeventTypeParameterwithv iDiscardEvents() :SpecialValuesformechanismParameterwithv iDiscardEvents() :viEnableEvent() :viEnableEvent() :viEnableEvent() :SpecialValuesforeventTypeParameterwithv iEnableEvent() :SpecialValuesformechanismParameterwithv iEnableEvent() :viEventHandler() :viEventHandler() :viFindNext() :viFindNext() :viFindNext() :viFindRsrc() :viFindRsrc() :viFindRsrc() :SpecialValueforretCountParameterwithviF indRsrc() :SpecialValueforfindListParameterwithviF indRsrc() :viFlush() :viFlush() :viFlush() :viFlush :viGetAttribute() :viGetAttribute() :viGetAttribute() :viInstallHandler() :viInstallHandler() :viInstallHandler() :viLock() :viLock() :viLock() :viOpen() :viOpen() :viOpen() :ResourceAddressStringGrammarandExamples withviOpen() :SpecialValuesforaccessModeParameterwith viOpen() :viOpenDefaultRM() :viOpenDefaultRM() :viOpenDefaultRM() :viParseRsrc() :viParseRsrc() :viParseRsrc() :viPrintf() :viPrintf() :viPrintf() :SpecialCharactersusedwithviPrintf() :ANSICS tandardModifiersusedwithviPrintf() :EnhancedModifierstoANSICS tandardsusedwithviPrintf() :ModifiersusedwithArgumentTypes%,c,anddw ithviPrintf() :ModifiersusedwithArgumentTypefwithviPri ntf() :ModifiersusedwithArgumentTypessandbwith viPrintf() :ModifiersusedwithArgumentTypesBandywith viPrintf() :viQueryf() :viQueryf() :viQueryf() :viRead() :viRead() :viRead() :SuccessCodeConditionsforGPIBI nterfaceswithViRead() :viReadAsync() :viReadAsync() :viReadAsync().

4 SpecialValueforjobId ParameterwithviReadAsync() :viReadSTB() :viReadSTB() :viReadSTB() :viReadToFile() :viReadToFile() :viReadToFile() :SpecialValuefortheretCountParameterwith viReadToFile() :viScanf() :viScanf() :viScanf() :ANSICS tandardModifiersusedwithviScanf() :EnhancedModifierstoANSICS tandardsusedwithviScanf() :ModifiersusedwithArgumentTypecwithviSca nf() :ModifiersusedwithArgumentTypedwithviSca nf() :ModifiersusedwithArgumentTypefwithviSca nf() :ModifiersusedwithArgumentTypeswithviSca nf() :ModifiersusedwithArgumentTypebwithviSca nf() :ModifiersusedwithArgumentTypetwithviSca nf() :ModifiersusedwithArgumentTypeTwithviSca nf() :ModifiersusedwithArgumentTypeywithviSca nf() :viSetAttribute() :viSetAttribute() :viSetAttribute() :viSetBuf() :viSetBuf() :viSetBuf() :FlagsusedwithMaskParameterwithviSetBuf( ) :viSPrintf() :viSPrintf() :viSPrintf() :viSScanf() :viSScanf() :viSScanf() :viStatusDesc() :viStatusDesc() :viTerminate() :viTerminate() :viTerminate() :viUninstallHandler() :viUninstallHandler() :viUninstallHandler() :SpecialValuesforhandlerParameterwithviU ninstallHandler() :viUnlock() :viUnlock() :viUnlock() :viUsbContrlIn() :viUsbContrlIn() :viUsbContrlIn() :viUsbContrlOut() :viUsbContrlOut() :viUsbContrlOut() :viVPrintf() :viVPrintf() :viVPrintf() :viVQueryf() :viVQueryf() :viVQueryf() :viVScanf() :viVScanf() :viVScanf() :viVSPrintf() :viVSPrintf() :viVSPrintf() :viVSScanf() :viVSScanf() :viVSScanf() :viWaitOnEvent() :viWaitOnEvent() :viWaitOnEvent() :SpecialValuesforinEventTypeParameterwit hviWaitOnEvents() :SpecialValuesfortimeoutParameterwithviW aitOnEvents() :SpecialValuesforoutEventTypeParameterwi thviWaitOnEvents().

5 SpecialValuesforoutContextParameterwithv iWaitOnEvents() :viWrite() :viWrite() :viWrite() :SpecialValueforretCountParameterwith viWrite() :viWriteAsync() :viWriteAsync() :viWriteAsync() :SpecialValueforjobIdParameterwithviWrit eAsync() :viWriteFromFile() :SpecialValueforretCountParameterwithviW riteFromFile() :VI_ATTR_TCPIP_HOSTNAME :VI_ATTR_USB_INTFC_NUM :VI_ATTR_USB_MAX_INTR_SIZE :VI_ATTR_USB_PROTOCOL :VI_ATTR_USB_RECV_INTR_DATA :VI_ATTR_USB_RECV_INTR_SIZE ,theTektroniximplementationoftheVirtualI nstrumentSoftwareArchitecture(VISA)Libra ry,aninterface-inde-pendentsoftwareinter faceendorsedbytheVXIplug& :HThePrefaceandGettingStartedsectionsbri eflycovertheaudienceandconventionsforthi sguide,presentoverviewconcepts,summarize TekVISA featuresandapplications, ,attributes, ,attributes, , common I/O library calledtheVirtualInstrumentSoftwareArchit ecture(VISA)TherequestedKeywill becopied into the user ()operationmatches an expressionagainst the resources avail-able for a particular this carefully.

6 <item1,item2,..> (vi, readFmt,<arg1, arg2, ..>)CodeThisfontisusedtodesignateblocksofco de.*result = m_ViStatus;Menu> :fromtheFilemenu, > ,manuals, (071-0245-XX) (VISA)areavailablefromthewebsiteoftheVXI plug& StartedTektronixTekVISAP rogrammerManual1-1 Getting ,theVXIplug&playSystemsAlliancedeveloped acommonI/OlibrarycalledtheVirtualInstrum entSoftwareArchitecture(VISA).VISA providesacommonstandardforsoftwaredevelo perssothatsoftwarefrommultiplevendors,su chasinstrumentdrivers, ,theTektroniximplementationoftheVISAA pplicationProgrammingInterface(API).TekV ISA isindustry-compliantsoftware,availablewi thselectedTektronixinstrumentmodels,forw ritinginteroperableinstrumentdriversinav arietyofApplicationDevelopmentEnvironmen ts(ADEs). ,USB,andserial(RS-232) :HUsingvirtualGPIB softwarerunninglocallyonWindows-basedins trument-sationHUsingphysicalGPIB controllerhardwareHUsingasynchronousseri alcontrollerhardwareHOveraLocalAreaNetwo rk(LAN)thatusesVXI-11protocol,TCP/IPSock et,andoneofthefollowing:HAnAD007 LAN-to-GPIB adaptertoGPIB controllerhardwareHAnEthernetconnectiont ogetherwith VXI-11serverrunningonWindows-basedinstru mentssuchastheTDS7000andTDS/CSA8000 SeriesOscilloscopesHAnEthernetconnection togetherwithSocketserverrunningonWindows --basedinstrumentssuchastheDPO/DSA7000 SeriesOscilloscopesGettingStarted1-2 TektronixTekVISAP rogrammerManualHUsingaUSBconnectionforUS BinstrumentssuchastheTDS1000 BandTDS2000 BseriesHUsingTekLinkhardwaretoTekLink-en abledinstrumentsTekVISA offersthefollowingfeaturesandbenefits.

7 HImproveseaseofuseforendusersbyproviding aconsistentmethodologyforusinginstrument driversfromavarietyofvendorsHProvideslan guageinterfacelibrariesforprogrammersusi ngmultipleApplicationDevelopmentEnvironm entsasshowninFigure1--1,including:HMicro softC/C++ , ,VXI-11server, ,USB,orserial(RS232)connectionlocally, and BenefitsApplications andConnectivity Supportedby TekVISAG ettingStartedTektronixTekVISAP rogrammerManual1-3 Figures1--1and1--2illustratethevarietyof software,localhardware, (ADE)C,C++ProgramVisualBasicProgramLabVI EWandLabWindowsMATLABIVI--COMVXI plug&playTVCTekVISAI nput/OutputLibraryAPIV irtualGPIB(GPIB8)GPIB(GPIB0--GPIB3)ASRL( RS232 COM1,COM2)LAN(VXI--11,Socket)TestandMeas urementInstrumentsTekLinkUSBC,C++Program VisualBasicProgramLabVIEWandLabWindowsMA TLABT estandMeasurementInstrumentsFigure1-1:Te kVISAS upportsMultipleDevelopmentEnvironmentsGe ttingStarted1-4 TektronixTekVISAP rogrammerManualRemoteWindows-basedContro llerUserApplicationASRLGPIBV irtualGPIBE mbeddedSoftwaresideofInstrumentVXI--11 ClientsoftwareGPIB connectionEthernetLANVXI--11 ServerLocalWindows-basedControllerUserAp plicationUserApplicationNonWindows-based InstrumentsWindows-basedOscilloscopeWind ows--sideofInstrumentASRLR emoteUNIX-basedControllerEthernetLANUser ApplicationVXI--11 ClientVISAL ibraryVISAL ibraryUSBVISAL ibraryGPIBTekLinkGPIB--LANA dapterw/VXI--11/EthernetLanUSBH ardwaveRS--232 HardwaveGPIBH ardwaveSocketServerVXI--11 ClientSocketClientClientSocketClientSock etFigure1-2 , , ,resourcemorespecificallyreferstoapartic ularimplementationorinstance,inobject-or ientedterms,ofaresourceclass, (INSTR)resourceclass, (reading,writing,triggering,andsoon).

8 GPIB,ASRL(serial)devices,USB,TCPIP/LAN, (SOCKET) , , ,closing,andfindingresources;settingandr etrievingresourceattributes;generatingev entsonresources; , INSTRR esource, SOCKETR esource, and SessionsOperations, Attributes,and EventsThe Resource , ,findingavailableresources, (VirtualInstruments)performOperationshav eAttributesEventsSessionsDefaultResource Managerprovidesaccesstooperatewithinrais e/respondtoFigure1-3:KeyVISAT erminologyforINSTRR esourceGettingStartedTektronixTekVISAP rogrammerManual1-7 SOCKETR esources(VirtualInstruments)performOpera tionshaveAttributesSessionsDefaultResour ceManagerprovidesaccesstooperatewithinFi gure1-4 () (VISA resourceswithanyassociatedorrequiredhard ware) , ,ASRL(serial)andGPIB virtualinstruments,whichworkwithaccompan yingUSBTMC, , ,orrunningonaremotePCconnectedbyLANtosuc haninstrument,canaccesstheembeddedinstru mentsoftwarebyusingavirtualGPIB softwareconnection, Instruments andVirtual GPIBG ettingStarted1-8 TektronixTekVISAP rogrammerManualWhatYouNeedtoGetStartedVI SA applicationsthatcommunicatewithTektronix instrumentationshoulduseTekVISA, ,GPIB,andserial(ASRL)resourceassignments ,andtoaddorremoveremotehosts(suchasVXI-1 1orSocketclientsconnectedbyEthernetLANor byanAD007adapterandassociatedGPIB hardware).

9 , , : InstallingTekVISAS oftwareonaPCAlternativeLocationsforFindi ngTekVISAS oftwareInstructionsforInstallingTekVISAS oftwareonaPCTheproductsoftwareCDforyourM S-WindowsoscilloscopeInyourMS-Windowscom puter,selectStart>Run,browsetheCDtotheTe kVISA folder, KitCDClickontheDevelopers ,youshoulduninstallthatversionfirst, InstallationGettingStartedTektronixTekVI SAP rogrammerManual1-9 IncludedwiththeTekVISA installationistheTekVISAI nstrumentManagerutility,whichletsyoufind resourceassignmentsandaddorremovenetwork hosts(instruments).Onceaninstrumentisadd edtotheTekVISA configuration, , ,youcanselect,Start>Programs> TekVISA > :SystemTrayThe TekVISAC onfiguration UtilityGettingStarted1-10 TektronixTekVISAP rogrammerManualReferenceTektronixTekVISA P rogrammerManual2-1 Operations :TableofVISAO perationsbyCategoryOperationDescriptionP ageOpeningandClosingSessions,Events,andF indListsviOpenDefaultRMReturnasessiontot heDefaultResourceManager2--44viOpenOpena sessiontothespecifiedresource2--41viClos eClosethespecifiedsession,event,orfindli st2--12 FindingResourcesviFindRsrcFindalistofres ourcesassociatedwithaspecifiedinterface2 --25viFindNextReturnthenextresourcefromt hefindlist2--23viParseRsrcParsesaresourc estringtogettheinterfaceinformation2--41 SettingandRetrievingAttributesviGetAttri buteRetrievethestateofanattributeforthes pecifiedsession,event,orfindlist2--33viS etAttributeSetthestateofanattributeforth especifiedsession,event.

10 Orfindlist2--78viStatusDescRetrieveauser --readabledescriptionofthespecifiedstatu scode2--86 ReadingandWritingBasicDataviWriteWriteda tasynchronouslytoadevicefromthespecified buffer2--110viWriteAsyncWritedataasynchr onouslytoadevicefromthespecifiedbuffer2- -112viWriteFromFileTakedatafromafileandw riteittoadevicesynchronously2--116viRead Readdatasynchronouslyfromadeviceintothes pecifiedbuffer2--57viReadAsyncReaddataas ynchronouslyfromadeviceintothespecifiedb uffer2--61viReadToFileReaddatasynchronou slyfromadeviceandstorethetransferreddata inafile2--67viTerminateTerminatenormalex ecutionofanasynchronousreadorwriteoperat ion2--87 OtherBasicI/OOperationsviClearClearadevi ce2--10 OperationsSummary2-2 TektronixTekVISAP rogrammerManualTable2-1:TableofVISAO