PROTECTiconworkshop

LabVIEWTMDataPluginSDKUserManualLabVIEWDataPluginSDKJuly2012372601D-01SupportWorldwideTechnicalSupportandProductInformationni.
comWorldwideOfficesVisitni.
com/niglobaltoaccessthebranchofficeWebsites,whichprovideup-to-datecontactinformation,supportphonenumbers,emailaddresses,andcurrentevents.
NationalInstrumentsCorporateHeadquarters11500NorthMopacExpresswayAustin,Texas78759-3504USATel:5126830100Forfurthersupportinformation,refertotheTechnicalSupportandProfessionalServicesappendix.
TocommentonNationalInstrumentsdocumentation,refertotheNationalInstrumentsWebsiteatni.
com/infoandentertheInfoCodefeedback.
2008–2012NationalInstruments.
Allrightsreserved.
ImportantInformationWarrantyThemediaonwhichyoureceiveNationalInstrumentssoftwarearewarrantednottofailtoexecuteprogramminginstructions,duetodefectsinmaterialsandworkmanship,foraperiodof90daysfromdateofshipment,asevidencedbyreceiptsorotherdocumentation.
NationalInstrumentswill,atitsoption,repairorreplacesoftwaremediathatdonotexecuteprogramminginstructionsifNationalInstrumentsreceivesnoticeofsuchdefectsduringthewarrantyperiod.
NationalInstrumentsdoesnotwarrantthattheoperationofthesoftwareshallbeuninterruptedorerrorfree.
AReturnMaterialAuthorization(RMA)numbermustbeobtainedfromthefactoryandclearlymarkedontheoutsideofthepackagebeforeanyequipmentwillbeacceptedforwarrantywork.
NationalInstrumentswillpaytheshippingcostsofreturningtotheownerpartswhicharecoveredbywarranty.
NationalInstrumentsbelievesthattheinformationinthisdocumentisaccurate.
Thedocumenthasbeencarefullyreviewedfortechnicalaccuracy.
Intheeventthattechnicalortypographicalerrorsexist,NationalInstrumentsreservestherighttomakechangestosubsequenteditionsofthisdocumentwithoutpriornoticetoholdersofthisedition.
ThereadershouldconsultNationalInstrumentsiferrorsaresuspected.
InnoeventshallNationalInstrumentsbeliableforanydamagesarisingoutoforrelatedtothisdocumentortheinformationcontainedinit.
EXCEPTASSPECIFIEDHEREIN,NATIONALINSTRUMENTSMAKESNOWARRANTIES,EXPRESSORIMPLIED,ANDSPECIFICALLYDISCLAIMSANYWARRANTYOFMERCHANTABILITYORFITNESSFORAPARTICULARPURPOSE.
CUSTOMER'SRIGHTTORECOVERDAMAGESCAUSEDBYFAULTORNEGLIGENCEONTHEPARTOFNATIONALINSTRUMENTSSHALLBELIMITEDTOTHEAMOUNTTHERETOFOREPAIDBYTHECUSTOMER.
NATIONALINSTRUMENTSWILLNOTBELIABLEFORDAMAGESRESULTINGFROMLOSSOFDATA,PROFITS,USEOFPRODUCTS,ORINCIDENTALORCONSEQUENTIALDAMAGES,EVENIFADVISEDOFTHEPOSSIBILITYTHEREOF.
ThislimitationoftheliabilityofNationalInstrumentswillapplyregardlessoftheformofaction,whetherincontractortort,includingnegligence.
AnyactionagainstNationalInstrumentsmustbebroughtwithinoneyearafterthecauseofactionaccrues.
NationalInstrumentsshallnotbeliableforanydelayinperformanceduetocausesbeyonditsreasonablecontrol.
Thewarrantyprovidedhereindoesnotcoverdamages,defects,malfunctions,orservicefailurescausedbyowner'sfailuretofollowtheNationalInstrumentsinstallation,operation,ormaintenanceinstructions;owner'smodificationoftheproduct;owner'sabuse,misuse,ornegligentacts;andpowerfailureorsurges,fire,flood,accident,actionsofthirdparties,orothereventsoutsidereasonablecontrol.
CopyrightUnderthecopyrightlaws,thispublicationmaynotbereproducedortransmittedinanyform,electronicormechanical,includingphotocopying,recording,storinginaninformationretrievalsystem,ortranslating,inwholeorinpart,withoutthepriorwrittenconsentofNationalInstrumentsCorporation.
NationalInstrumentsrespectstheintellectualpropertyofothers,andweaskouruserstodothesame.
NIsoftwareisprotectedbycopyrightandotherintellectualpropertylaws.
WhereNIsoftwaremaybeusedtoreproducesoftwareorothermaterialsbelongingtoothers,youmayuseNIsoftwareonlytoreproducematerialsthatyoumayreproduceinaccordancewiththetermsofanyapplicablelicenseorotherlegalrestriction.
End-UserLicenseAgreementsandThird-PartyLegalNoticesYoucanfindend-userlicenseagreements(EULAs)andthird-partylegalnoticesinthefollowinglocations:Noticesarelocatedinthe\_LegalInformationanddirectories.
EULAsarelocatedinthe\Shared\MDF\Legal\licensedirectory.
Review\_LegalInformation.
txtformoreinformationonincludinglegalinformationininstallersbuiltwithNIproducts.
TrademarksDIAdem,LabVIEW,NationalInstruments,NI,ni.
com,theNationalInstrumentscorporatelogo,andtheEaglelogoaretrademarksofNationalInstrumentsCorporation.
RefertotheTrademarkInformationatni.
com/trademarksforotherNationalInstrumentstrademarks.
Otherproductandcompanynamesmentionedhereinaretrademarksortradenamesoftheirrespectivecompanies.
MembersoftheNationalInstrumentsAlliancePartnerProgramarebusinessentitiesindependentfromNationalInstrumentsandhavenoagency,partnership,orjoint-venturerelationshipwithNationalInstruments.
PatentsForpatentscoveringNationalInstrumentsproducts/technology,refertotheappropriatelocation:HelpPatentsinyoursoftware,thepatents.
txtfileonyourmedia,ortheNationalInstrumentsPatentNoticeatni.
com/patents.
ExportComplianceInformationRefertotheExportComplianceInformationatni.
com/legal/export-compliancefortheNationalInstrumentsglobaltradecompliancepolicyandhowtoobtainrelevantHTScodes,ECCNs,andotherimport/exportdata.
WARNINGREGARDINGUSEOFNATIONALINSTRUMENTSPRODUCTS(1)NATIONALINSTRUMENTSPRODUCTSARENOTDESIGNEDWITHCOMPONENTSANDTESTINGFORALEVELOFRELIABILITYSUITABLEFORUSEINORINCONNECTIONWITHSURGICALIMPLANTSORASCRITICALCOMPONENTSINANYLIFESUPPORTSYSTEMSWHOSEFAILURETOPERFORMCANREASONABLYBEEXPECTEDTOCAUSESIGNIFICANTINJURYTOAHUMAN.
(2)INANYAPPLICATION,INCLUDINGTHEABOVE,RELIABILITYOFOPERATIONOFTHESOFTWAREPRODUCTSCANBEIMPAIREDBYADVERSEFACTORS,INCLUDINGBUTNOTLIMITEDTOFLUCTUATIONSINELECTRICALPOWERSUPPLY,COMPUTERHARDWAREMALFUNCTIONS,COMPUTEROPERATINGSYSTEMSOFTWAREFITNESS,FITNESSOFCOMPILERSANDDEVELOPMENTSOFTWAREUSEDTODEVELOPANAPPLICATION,INSTALLATIONERRORS,SOFTWAREANDHARDWARECOMPATIBILITYPROBLEMS,MALFUNCTIONSORFAILURESOFELECTRONICMONITORINGORCONTROLDEVICES,TRANSIENTFAILURESOFELECTRONICSYSTEMS(HARDWAREAND/ORSOFTWARE),UNANTICIPATEDUSESORMISUSES,ORERRORSONTHEPARTOFTHEUSERORAPPLICATIONSDESIGNER(ADVERSEFACTORSSUCHASTHESEAREHEREAFTERCOLLECTIVELYTERMED"SYSTEMFAILURES").
ANYAPPLICATIONWHEREASYSTEMFAILUREWOULDCREATEARISKOFHARMTOPROPERTYORPERSONS(INCLUDINGTHERISKOFBODILYINJURYANDDEATH)SHOULDNOTBERELIANTSOLELYUPONONEFORMOFELECTRONICSYSTEMDUETOTHERISKOFSYSTEMFAILURE.
TOAVOIDDAMAGE,INJURY,ORDEATH,THEUSERORAPPLICATIONDESIGNERMUSTTAKEREASONABLYPRUDENTSTEPSTOPROTECTAGAINSTSYSTEMFAILURES,INCLUDINGBUTNOTLIMITEDTOBACK-UPORSHUTDOWNMECHANISMS.
BECAUSEEACHEND-USERSYSTEMISCUSTOMIZEDANDDIFFERSFROMNATIONALINSTRUMENTS'TESTINGPLATFORMSANDBECAUSEAUSERORAPPLICATIONDESIGNERMAYUSENATIONALINSTRUMENTSPRODUCTSINCOMBINATIONWITHOTHERPRODUCTSINAMANNERNOTEVALUATEDORCONTEMPLATEDBYNATIONALINSTRUMENTS,THEUSERORAPPLICATIONDESIGNERISULTIMATELYRESPONSIBLEFORVERIFYINGANDVALIDATINGTHESUITABILITYOFNATIONALINSTRUMENTSPRODUCTSWHENEVERNATIONALINSTRUMENTSPRODUCTSAREINCORPORATEDINASYSTEMORAPPLICATION,INCLUDING,WITHOUTLIMITATION,THEAPPROPRIATEDESIGN,PROCESSANDSAFETYLEVELOFSUCHSYSTEMORAPPLICATION.
NationalInstruments|vContentsConventionsChapter1AnIntroductiontotheLabVIEWDataPluginSDKDataPluginOverview1-2LabVIEWDataPluginTypes.
1-4One-ShotDataPlugins1-4On-DemandDataPlugins.
1-4One-ShotversusOn-DemandDataPlugins1-4Chapter2CreatingDataPluginswithLabVIEWLabVIEWProjectFolders2-1DebuggingandTestingYourLabVIEWDataPlugin.
2-2AdaptingtheLabVIEWProjectBuild.
2-3DataPluginParameterization2-3BuildConfiguration.
2-4Chapter3ConstraintsChannelLengthLimitation.
3-1SupportedDataTypesandConversions.
3-1NameConventions3-2SupportedLabVIEWVersions.
3-3AppendixATechnicalSupportandProfessionalServicesNationalInstruments|viiConventionsThefollowingconventionsareusedinthismanual:Anglebracketsthatcontainnumbersseparatedbyanellipsisrepresentarangeofvaluesassociatedwithabitorsignalname—forexample,AO.
Thesymbolleadsyouthroughnestedmenuitemsanddialogboxoptionstoafinalaction.
ThesequenceOptionsSettingsGeneraldirectsyoutopulldowntheOptionsmenu,selecttheSettingsitem,andselectGeneralfromthelastdialogbox.
Thisicondenotesatip,whichalertsyoutoadvisoryinformation.
Thisicondenotesanote,whichalertsyoutoimportantinformation.
boldBoldtextdenotesitemsthatyoumustselectorclickinthesoftware,suchasmenuitemsanddialogboxoptions.
Boldtextalsodenotesparameternames.
italicItalictextdenotesvariables,emphasis,cross-references,oranintroductiontoimportantconcepts.
monospaceTextinthisfontdenotestextorcharactersthatyoushouldenterfromthekeyboard,suchassectionsofcode,programmingexamples,andsyntaxexamples.
Thisfontisalsousedforthepropernamesofdiskdrives,paths,folders,programs,subprograms,subroutines,devicenames,functions,operations,commands,variables,controls,events,methods,filenamesandextensions,andcodeexcerpts.
NationalInstruments|1-11AnIntroductiontotheLabVIEWDataPluginSDKTheLabVIEWDataPluginSDKenablesyoutocreateDataPluginsfromscratchusing100%LabVIEWG-code.
TheSDKalsoenablesyoutocreateaninstallerinordertoinstallthenewDataPluginonanyWindowscomputer.
Refertothereadme_DataPlugin_SDK.
htmlforsystemandsoftwarerequirements.
Visitwww.
ni.
com/datapluginsforthelistofallfreelydownloadableDataPluginsandformoreinformationaboutDataPlugins.
Visitwww.
ni.
com/tdmformoreinformationabouttheTDMdatamodel,theTDMfileformat,andassociatedTDMtools.
Visitthefollowingwebsitesformoreinformationabouttheserelatedsoftwarepackages:LabVIEW:www.
ni.
com/labviewDIAdem:www.
ni.
com/diademDataFinderServerEdition:www.
ni.
com/datafinder1-2|ni.
comChapter1AnIntroductiontotheLabVIEWDataPluginSDKDataPluginOverviewADataPluginisencapsulatedcodethatunderstandshowtoreadandtointerpretthedatacontainedinaspecificdatafileformatbymappingittotheTDMdatamodel.
TheTDMdatamodelarrangesthedatainrootelement,channelgroups,andchannels.
TheTDMdatamodelhasthefollowingstructure:Figure1-1.
TDMDataModelInitiallyDataPluginscouldonlybecreatedbyusingC++orVBScriptprogramminglanguages,buttheLabVIEWDataPluginSDKgivesyou,theLabVIEWprogrammer,theabilitytocreateDataPluginsusingLabVIEW.
DataPluginscreatedwiththeLabVIEWDataPluginSDKcanonlyreaddata.
ThisisthecaseformostDataPluginspubliclypostedatwww.
ni.
com/dataplugins.
DataPlugins"pluginto"asoftwarelayercalledUSI(UniversalStorageInterface),whichinstallswithLabVIEW,DIAdem,andDataFinderServerEdition.
OnceanewDataPluginisregisteredonacomputer,anyinstalledLabVIEW,DIAdem,orDataFinderapplicationonthatcomputerisabletousethatnewlyregisteredDataPlugintoloaddatafilesinthefileformatthenewDataPluginsupports.
InLabVIEWthishappensviaasetofExpressVIscalledthe"StorageVIs".
InDIAdemtheDataPlugincanbeusedbysimplyinteractivelydraggingadatafileofthesupportedfileformatfromtheNAVIGATORwindowintotheDataPortal,oralternatively,byusingcommandslikeDataFileLoad()inaDIAdemscript.
TheDataFinderusestheDataPluginforindexingthefilesofthisspecificfileformat.
NationalInstruments|1-3LabVIEWDataPluginSDKThemainadvantageofcreatingaDataPluginwiththeLabVIEWDataPluginSDKistoleverageLabVIEWG-codetogivenewfileformatreadingcapabilitytoDIAdemand/ortheDataFinder.
WhentheLabVIEWDataPlugininstallerruns,norecordofitappearsin"AddandRemovePrograms",insteadtheDataPluginisregisteredwiththeUSIlayerit"plugsinto".
YoumayruntheLabVIEWDataPlugininstallerasmanytimesasyouwant,andeachtimetheDataPluginregisteredwithUSIissimplyupdated.
SotoinstallanewerversionoftheDataPluginontopofanolderversion,youjustrunthenewerLabVIEWDataPlugininstalleronthatcomputer.
TogetanoverviewoftheinstalledDataPluginsusethe"DataPluginSettings"dialogboxinDIAdemorDataFinderServerEdition.
UsethesamedialogboxtouninstallLabVIEWDataPlugins.
InLabVIEWyoucanusetheStorageVIstoenumerate,register,orderegisterDataPlugins.
Figure1-2.
OverviewofInstalledDataPluginsNoteTheLabVIEWDataPluginexampleprojectscontainaFortestingprojectfolderwithaVIyoucanusetodebugyourLabVIEWDataPluginfromwithinLabVIEW,withoutneedingtofirstbuildtheDataPluginDLLandinstaller.
RefertoLabVIEWProjectFoldersinChapter2,CreatingDataPluginswithLabVIEWforfurtherinformationonDataPlugins.
1-4|ni.
comChapter1AnIntroductiontotheLabVIEWDataPluginSDKLabVIEWDataPluginTypesTherearetwotypesofLabVIEWDataPlugins,One-ShotandOn-Demand.
YouneedtochoosebetweenimplementingaOne-ShotoranOn-DemandDataPluginbasedonthestructureofthedatafileandyourlevelofLabVIEWprogrammingexperience,asdescribedbelow.
One-ShotDataPluginsTheone-shotDataPlugin,isthesimplest.
Theone-shotDataPluginhasonecallbackVIthatyouprogram,yourCodeHere.
vi.
ThisVIiscalledexactlyonceanytimetheDataPluginisused.
Theone-shotDataPluginpassesallthedescriptiveinformation(meta-data,groupandchannelhierarchy)aswellasallthedatavaluesforallthechannels.
ThistypeofDataPluginagreeswellwiththewayLabVIEWprogrammersareusedtooperating,becausetheVIrunsexactlyoncewhenloadingdatawiththeDataPlugin.
On-DemandDataPluginsTheon-demandDataPluginismorecomplicatedandlesscomfortablefortheLabVIEWprogrammer,butingeneralthisisstilltherightchoiceforverylargedatafiles.
Theon-demandDataPluginhastwocallbacks,theyourCodeHere_meta.
viwhichiscalledexactlyonceanytimetheDataPluginruns,andtheyourCodeHere_raw.
viwhichcanbecalledoneormoretimesbutisonlycalledwhendatavaluesarerequested.
TheyourCodeHere_meta.
videclareson-demanddatachannelswhichspecify,forexample,thedatatype,name,length,descriptiveproperties,butwhichcontainnodatavalues.
ThentheyourCodeHere_raw.
viiscalledindividuallyforeachon-demanddatachannel.
One-ShotversusOn-DemandDataPluginsTheadvantagesoftheone-shotDataPluginarethatitissimpletoprogramandoftenloadsallthevaluesfromallthechannelsfasterthananon-demandDataPlugin.
Theone-shotDataPluginisanexcellentchoicewhenthedatafilesyouneedtoloadarealwayssmallenoughtofitinRAM.
Ifitonlytakesafewsecondstoloadallthevaluesofallthechannels,thisisthewaytogo.
If,though,youknowthatsomeormostofyourdatafileswillbetoobigtoloadintoRAM,thenyoushouldseriouslyconsiderthemorecomplicatedon-demandDataPlugin.
NotethatwhenloadingdatavaluesintoDIAdem,thevaluesarealwaysconvertedtoDBLsinDIAdem'sinternalmemory(notthecaseforLabVIEW),sointhatcaseyoushouldestimateyourfile'seffectivesizeinDBLswhendeterminingifitfitsinRAM.
Thedownsidetotheone-shotDataPluginisthatyouloadallthedatavaluesanytimetheDataPluginiscalled.
IftheDataPluginisbeingcalledbytheDataFinderinordertoindexthefile(whichneedsonlythedescriptiveinformation),thistakesmuchlongerthannecessarybecausetheone-shotDataPluginloadsallthedatavalueseventhoughtheyarenotneededinthatcase.
Incaseoftheon-demandDataPluginwhentheDataFinderisindexingthefile,theon-demandDataPluginonlyreturnsthedescriptiveinformation—itdoesnotwasteunnecessarytimereadingallthedatavalues.
NationalInstruments|1-5LabVIEWDataPluginSDKIftheOne-ShotDataPluginisbeingcalledbyDIAdemtoloadonly1outof200channels,itloadsthedatamuchslower,becauseitisloadingallthedatavaluesforall200channels,eventhoughonlythedatavaluesfor1channelwererequested.
Similarly,ifonlythefirst100valuesfroma100millionvaluelongdatachannelarebeingrequested,theone-shotDataPluginloadsall100millionvaluesanywayandthenonlyreturnsthefirst100ofthem.
Ontheotherhand,ifyourdatafilecontains20channels,andanon-demandDataPluginiscalledtoloadallthedatavaluesfromall20channels,theyourCodeHere_raw.
viiscalled20times,onceforeachseparateon-demandchannel.
Ifyouaredealingwithabinaryfilethathasexcellentrandomaccess,andyouknowexactlyatwhichbytepositioneachchannelstarts,thisdoesnotslowyoudownatall.
If,however,youhaveadatalogfilewithanarrayofclusterswhereeachclusterhas20elements,thiscausesyoutoreadthefile20timesinordertoloadallthedatavaluesfromallthechannels.
Thisishowtheone-shotDataPlugincanbefasterifyoucanfityourdatafileintoRAM(includingLabVIEWcopiesandDataPlugincopies).
Atthatpointyouhavetoweighhowmuchvirtualmemorywillslowyoudownversustheinefficiencyofloadingthefilemultipletimes.
Anotherdistinctionofon-demandDataPluginsandon-demandchannelsisthatthedatavaluesareingeneralloadedinbuffers.
Whenanon-demandDataPluginiscalledtoloadallthedatafromagivenon-demandchannel,theDataPluginengineusuallycallstheyourCodeHere_raw.
vimultipletimestoloadthedatavaluesbufferbybufferforthatchannel.
TheDataPluginenginedecideswhatbuffersizetouseandhowmanytimestocalltheyourCodeHere_raw.
vi,soyouneitherhavetoworryaboutthatnorcanyouaffectthebuffersizeyourself.
ThisiswhytheyourCodeHere_raw.
vihas"Offset"and"Count"inputs,sothattheDataPluginenginecantellyouwhichdatabuffertoloadfromtherequestedchannel.
Thisalsomeansthatwhentheon-demandDataPluginiscalledtoloadthefirst100valuesfroma100,000valueon-demandchannel,thattheDataPlugincanveryefficientlyjustloadtheneededvaluesandnothavetoprocessall100,000unnecessarily.
Again,forverylargefileswithadatafileformatthatoffersexcellentrandomaccess,thisisanidealfit.
ASCIIfiles,however,areparticularlybadfortheon-demandDataPlugins,becauseinordertoforwardthefilecursortothecorrect"Offset"position,youhavetoparsealltheendlinecharactersinthefileuptothatpoint,andthisyoumustdoalloveragainforeverysuccessivebufferread.
InthisparticularcaseyoumightwanttothinkofusingVBSDataPluginsastheyprovidebuilt-inoptimizedon-demandASCII(andbinary)readers.
Onemorescenariowhereon-demandDataPluginsshine(providedafileformatwithreasonablerandomaccess)iswhentheDataPluginiscalledtoloadallthevaluesfromonlyonechanneloutof,forexample,200.
InthiscaseyoucanreadthewholefilemuchfasterandonlystoredatainLabVIEWmemoryfromonechannelinsteadofall200.
Furthermorethereistheadvantagethatyoudonotunnecessarilyloaddatavalueswhenonlydescriptiveinformationisbeingrequested.
Insummary,thetypeofDataPluginyouchoosedependspartlyonyourfileformat,partlyonyouraveragefilesizerelativetoRAM,andpartlyonyourtypicalloading/indexingusecases.
NationalInstruments|2-12CreatingDataPluginswithLabVIEWInthischapteryouwilllearnhowtoadaptpredefinedLabVIEWprojects,howtotestyourDataPlugin,andhowtosettheDataPluginparameters.
LabVIEWProjectFoldersLabVIEWDataPluginsarebuiltbyadaptingpredefinedLabVIEWprojectstoyourspecificneeds.
UsetheProjectExplorertoloadsuchapredefinedproject.
Youcanalsoaccesstheseexamplesbybrowsingtothefolderlabviewexamplesfiledataplugin.
Figure2-1.
LabVIEWProjectLayoutforOn-DemandDataPluginsTheLabVIEWprojectfolderAdaptthistoyourfileformatcontainsyouractualfile-format-specificsourcecodetoreadthedatafromtheparticulardatafilethatyourDataPluginsupports.
Intheone-shotcasethisistheyourCodeHere.
vi,whileintheon-demandcasethisisboththeyourCodeHere_meta.
viandthe2-2|ni.
comChapter2CreatingDataPluginswithLabVIEWyourCodeHere_raw.
vi.
YoushouldadaptthecodeinthisprojectfolderfromoneoftheLabVIEWDataPluginexamples,sincetheinputandoutputterminalsoftheseVIsmustremainthesamefortherestoftheDataPluginarchitecturetocallyourVIscorrectly.
RefertoLabVIEWDataPluginTypesinChapter1,AnIntroductiontotheLabVIEWDataPluginSDKforinformationaboutthecorrectDataPlugintype,andthusthecorrectexampleprojecttostartwith.
ThisprojectfolderalsoincludesarequiredRegisterLabVIEWDataPlugin.
inifile,whichyouneedtoeditinordertomatchtheexpectedfileextension,programmingnameoftheDataPlugin,associatedDataPluginiconfile,andsoon.
Theoptional.
icofilethatisassociatedwiththeDataPluginisthelastresourcefileinthisprojectfolder.
RefertoAdaptingtheLabVIEWProjectBuildinthischapterforfurtherinformation.
TheLabVIEWprojectfolderDon'tchangethiscontainsseveralfileswhichcomprisetheheartoftheLabVIEWDataPluginarchitectureandshouldneverbeeditednordeletedinyourDataPluginproject.
TheLabVIEWprojectfolderFortestingcontainsseveralcompletelyoptionalfileswhichshouldbeusefultoyouindebuggingandtestingyourDataPlugin.
RefertoDebuggingandTestingYourLabVIEWDataPlugininthischapterforfurtherinformation.
TheLabVIEWprojectfolderDependenciescontainsfilesorfilereferenceswhichneedtobeincludedinthebuiltsourcedistributionthatgoesintheinstaller—ingeneralyoushouldnotneedtochangeanythingbyhandhere.
ThelistofincludedVIsbeginswithallthevi.
libfilesusedinyourproject.
AnyadditionallyincludedsubVIscanshowuphere,andanyincludedDLLs,suchasthelvStorage.
dll(always)orthelvanlsis.
dllalsoappearhere.
TheLabVIEWprojectfolderBuildSpecificationscontainstheconfigurationsforcreatingtheDataPluginDLLandforbuildingtheLabVIEWDataPlugininstaller.
AlltheLabVIEWcodeintheDataPluginisbuiltintotheDataPluginDLL,andtheinstallerorchestratestheinstallationoftheDataPluginDLLandafewotherresourcefiles,aswellasthesubsequentregistrationoftheDataPluginwiththehostcomputer.
IngeneralyoushouldnotneedtochangeanythingintheDataPluginDLLconfiguration,exceptperhapsthetargetnameoftheDLL.
TheDataPlugininstallerisanothermatter.
RefertoAdaptingtheLabVIEWProjectBuildinthischapterforfurtherinformation.
DebuggingandTestingYourLabVIEWDataPluginTheLabVIEWprojectfolderFortestingcontainsseveralcompletelyoptionalfileswhichshouldbeusefultoyouintestingyourDataPlugin.
ThefirstoftheseisanexampleTestDataFile.
xxxxxforyoutotrytoloadwiththeDataPlugincode.
ThisisusefultoyouonlyifyouaregettingfamiliarwithLabVIEWDataPluginarchitectureandusingoneoftheexampleswithoutanyedits.
Itisagoodpractice,though,toaddasampledatafiletothisprojectfoldersothatyouorothershaveaneasywaytotest/editthesourcecodelateron.
NationalInstruments|2-3LabVIEWDataPluginSDKThesecondfileisaCreateTestDataFile.
viwithwhichyoucancreateadditionaltestdatafileswithdifferenttypesofdataand/ordifferentfilesizes.
Again,thisisonlyusefulintheuneditedexamples,andhereyoushouldonlyincludeoneforyourDataPluginifyouhappentohaveithandy.
ThethirdfileisaCreateDataPluginOutputFile.
vi,whichenablesyoutotestyourDataPlugincode,priortobuildingandrunningtheDataPlugininstallerandwhilestillinLabVIEW.
ThisVIsimulatesthewaytheDataPluginarchitecturecallstheyourCodeHere…viyouedited,andthendisplaystheresultingloadeddatainapop-up,interactiveVI.
YoushouldusethisVItodebugyourcode,priortobuildingtheinstaller,sothatyoucanuseLabVIEWdebuggingtoidentifythesourceofanyerrorsorincorrectdataloading.
FeelfreetolookatthisVI'sblockdiagramtogainaclearerunderstandingofwhattheDataPluginarchitectureisdoingwithyourcode.
UsetheDataFileViewer.
viintheFileI/OStorageVIs/DataPluginspalettetotestthebuiltandinstalledDataPluginfromwithinLabVIEW.
AdaptingtheLabVIEWProjectBuildInthissectionyouwilllearnhowtosettheDataPluginparameterssuchastheDataPluginnameandthesupportedfileextensions.
Additionallyyouwilllearnhowtochangethebuildconfiguration.
DataPluginParameterizationTopersonalizeyourLabVIEWDataPlugin,youneedtoeditthecontentoftheRegisterLabVIEWDataPlugin.
inifromtheAdaptthistoyourfileformatprojectfolder.
BelowisthecontentoftheRegisterLabVIEWDataPlugin.
inifileintheLabVIEWDataPluginexample"DatalogDataPluginondemand":[LVDataPluginDatalog]Name=LVDataPluginDatalogFileExtension=*.
lvlogPluginFileName=LabVIEWDataPluginDatalog.
dllIconFileName=Datalog.
icoThefirstlinesetstheNameoftheDataPlugin,asitislistedintheUSIconfigurationfileandhowitshowsupintheuserdialogboxesinDIAdemandtheDataFinder.
ItisalsotheprogrammaticnameoftheDataPluginforLabVIEWVIsandDIAdemscripts.
Youjustneedtomakesureyoupickauser-friendlynamethatisdifferentfromallotherDataPluginswhichmightbeonyourtargethostcomputers.
TheFileExtensionoftheDataPluginisthedefaultfileextensionorextensionsthatareassociatedwiththisDataPlugininDIAdemandtheDataFinder.
Multipleextensionscanbespecifiedbyusingsemicolonasaseparatorbetweeneachextension.
2-4|ni.
comChapter2CreatingDataPluginswithLabVIEWNotePleasenotethatDataPluginswithwildcardsasextensions,forexample*.
*or*.
lvog,arenotusedbyDataFinderforindexing.
ThePluginFileNameoftheDataPluginisthenameoftheDataPluginDLL–makesureitmatchesthenamelistedintheDataPluginDLLconfigurationdialogboxaswellasthenameintheinstallerconfigurationdialogbox.
TheIconFileNameoftheDataPluginisthe.
icofilewhichisassociatedwithyourDataPlugin—makesurethismatchestheactualnameoftheiconfileintheAdaptthistoyourfileformatprojectfolder.
IfyouchoosetotakethedefaultDataPluginicon,youcanendthislinewiththe"="sign.
Youalsoneedtochangethenameoftheassociated.
icofileintheSourceFilesDestinationViewtomatchyouractualiconfile,orelsedeletetheiconfilefromtheSourceFilesDestinationViewifyouchoosenottohaveone.
NoteTocreateyourowniconfilesyoumustuseanappropriategraphicsprogram,forexampleyoucouldbuyAxialisIconWorkshop(www.
axialis.
com).
Theiconsizeshouldbe16*16pixels.
BuildConfigurationTheDataPluginDLLconfigurationdoesnotrequirechanges,becauseitalwaysbuildstheDLLstartingwiththeDataPluginarchitecturecodeintheDon'tchangethisprojectfolder,whichyouneverneedtoedit.
Youwill,however,probablychoosetochangethetargetnameoftheDataPluginDLLtobetterreflectthenameofyourparticularDataPlugin.
YoushouldsimilarlychangetheProductInformationProductNameintheinstallerconfiguration.
TheDataPlugininstallerincludestheresultingDataPluginDLLaswellastheRegisterLabVIEWDataPlugin.
exefromtheDon'tchangethisprojectfolderandtheRegisterLabVIEWDataPlugin.
iniplusanyassociatediconfilefromtheAdaptthistoyourfileformatprojectfolder.
IfyouchangethenameoftheDataPluginDLLintheDLLbuildconfiguration,youhavetomakecorrespondingnamechangestotheresulting.
dll,.
h,.
ini,.
libfilesintheSourceFilesDestinationView.
Youmaywanttoremovethe"NILabVIEWRun-TimeEngine"fromthe"AdditionalInstallers"sectiontoreducethesizeoftheresultinginstaller.
Ifyoudothis,youareassumingthatalltheclientsthatwilleverinstallyourDataPluginwillpreviouslyandseparatelyhaveinstalledthesameLabVIEWRun-TimeEngineversionthattheDataPluginisusing.
IngeneralitissafertoincludetheLabVIEWRun-TimeEngineintheDataPlugininstaller.
Somethingelseyoudonotneedtochangebutshouldbeawareof,isthatthelaststepofyourDataPlugininstallerkicksoffanadditionalinstallercalledRegisterLabVIEWDataPlugin.
exe,whichislocatedintheDon'tchangethisprojectfolder.
Thisadditionalinstallermustbeselectedtoruninthe"Advanced"sectionoftheinstallerconfiguration,becausethisiswhatregisterstheDataPluginwiththehostcomputeraftertheDataPluginhassuccessfullyinstalledontothehostcomputer.
NationalInstruments|3-13ConstraintsInthischapteryouwilllearnwhichdatatypesDataPluginssupport,andwhichchannellengthlimitationandnameconventionsyouhavetoconsider.
ChannelLengthLimitationDataPluginscurrentlycanonlydeclarechannelstohavealengthfrom0to231.
Ifyoupassmorethan231valuestoaDataPluginchannel,theDataPluginthrowsanerror.
SupportedDataTypesandConversionsYoucanimportthefollowingdatatypeswithaDataPlugin:Time,U8,I8,I16,U16,I32,U32,I64,U64,SGL,DBLOnlythefollowingdatatypesarenativelysupportedbyDataPlugins:Time,U8,I16,I32,SGL,DBLAllotherdatatypesaretypeconvertedwhenpassedtotheDataPlugin.
ThefinalconvertedtypecandependonwhichVIyouusetopassthedatatotheDataPlugin.
IfyouusethestandardWriteData.
viexpressVIfromtheStorageVIpalette,thefollowingtypeconversionsautomaticallyoccur:I8I16U16I32U32I32I64DBLWaveformU64DBLWaveform3-2|ni.
comChapter3ConstraintsIfyouarereadingU32,U64,orI64data,youshouldusetheWriteChannelValues.
viinstead(seebelow).
IfyouuseinsteadtheWriteChannelValues.
vi(whichyoucanfindintheDatalogexampleproject),thefollowingtypeconversionsautomaticallyoccur:NoteEvenherethe64bitintegerconversionsstillinsomecasesresultinlossofdata,soifyouaredealingwithdigitalports,forexample,youmightwanttomapaU64intofourseparateU16DataPluginchannels(whichwouldautomaticallybeconvertedtoI32internally).
NoteNoneofthefollowingdatatypesaresupportedatallinDataPlugins:Booleans,Clusters,extendeddatatypes,orarraysofgreaterdimensionalitythan1D.
NameConventionsAllchannelgroupswithinaLabVIEWDataPluginandallchannelswithinaspecificchannelgroupshouldhaveauniquename.
Thesameappliestocustompropertiesaddedtothefile,channelgrouporchannellevel.
Additionallysomecharactersmaynotbeusedinnames.
Pleasefindbelowatablelistingthosespecialcharacters.
ThefollowingpropertynamesforfilehaveaspecialmeaningintheTDMdatamodel:author,datestring,datetime,description,name,mime_type,registertxt1,registertxt2,registertxt3,timestring,title,wf_create_time.
I8I16U16I32U32DBLI64DBLU64DBLAreaofUsageForbiddenCharactersFilenames(Datasetnames)ChannelgroupnamesChannelnamesPropertynamesandaspaceNationalInstruments|3-3LabVIEWDataPluginSDKThefollowingpropertynamesforfilearereservedforinternaluse:channelgroups,children,environment,external_references,id,instance_attributes,objecttype,parent,registercomments,version,version_date.
ThefollowingpropertynamesforchannelgroupshaveaspecialmeaningintheTDMdatamodel:description,measurement_begin,measurement_end,mime_type,name,registertxt1,registertxt2,registertxt3.
Thefollowingpropertynamesforchannelgroupsarereservedforinternaluse:channels,children,equipments,external_references,id,index,instance_attributes,measurement_quantities,objecttype,parent,root,sequences,submatrices,test,units_under_test,version,version_date.
ThefollowingpropertynamesforchannelshaveaspecialmeaningintheTDMdatamodel:description,displaytype,maximum,mime_type,minimum,monotony,name,novaluekey,registerint1,registerint2,registerint3,registerint4,registerint5,registerint6,registertxt1,registertxt2,registertxt3,registerval1,registerval2,registerval3,registerval4,registerval5,registerval6,unit_string,wf_increment,wf_samples,wf_start_offset,wf_start_time,wf_xnametype,wf_xunit_string.
Thefollowingpropertynamesforchannelsarereservedforinternaluse:average,channel,children,datatype,deletebehaviour,dimension,empty,external_references,flagkey,group,groupindex,id,implicit_increment,implicit_start,instance_attributes,internal_params,internal_res1,internal_res2,interpolation,is_scaled_by,length,lengthmax,local_columns,measurement,number,objecttype,parent,quantity,rank,representation,scales,sourcedatafilename,sourcedatafilepath,sourcegenparam1,sourcegenparam2,sourcehandle,sourceinstancekey,sourcename,sourceparentname,sourcerepresentation,sourcetype,sourcevalue,standard_deviation,status,type_size,unit,valuetype,version,version_date,waveform,writeprotection.
SupportedLabVIEWVersionsDataPluginshavebeensupportedinLabVIEWStorageVIssinceLabVIEW2010.
InearlierversionsDataPluginscouldbeusedbyaworkaround.
NoteUseaDataPluginbuiltwiththeLabVIEWDataPluginSDKonlywiththesameLabVIEWversionwithwhichyoucreatedthisDataPlugin.
ThesameappliesifthisDataPluginisusedtogetherwiththeLabVIEWDataFinderToolkit.
NationalInstruments|A-1ATechnicalSupportandProfessionalServicesLogintoyourNationalInstrumentsni.
comUserProfiletogetpersonalizedaccesstoyourservices.
Visitthefollowingsectionsofni.
comfortechnicalsupportandprofessionalservices:Support—Technicalsupportatni.
com/supportincludesthefollowingresources:–Self-HelpTechnicalResources—Foranswersandsolutions,visitni.
com/supportforsoftwaredriversandupdates,asearchableKnowledgeBase,productmanuals,step-by-steptroubleshootingwizards,thousandsofexampleprograms,tutorials,applicationnotes,instrumentdrivers,andsoon.
RegisteredusersalsoreceiveaccesstotheNIDiscussionForumsatni.
com/forums.
NIApplicationsEngineersmakesureeveryquestionsubmittedonlinereceivesananswer.
–StandardServiceProgramMembership—ThisprogramentitlesmemberstodirectaccesstoNIApplicationsEngineersviaphoneandemailforone-to-onetechnicalsupport,aswellasexclusiveaccesstoeLearningtrainingmodulesatni.
com/elearning.
Allcustomersautomaticallyreceiveaone-yearmembershipintheStandardServiceProgram(SSP)withthepurchaseofmostsoftwareproductsandbundlesincludingNIDeveloperSuite.
NIalsooffersflexibleextendedcontractoptionsthatguaranteeyourSSPbenefitsareavailablewithoutinterruptionforaslongasyouneedthem.
Visitni.
com/sspformoreinformation.
Forinformationaboutothertechnicalsupportoptionsinyourarea,visitni.
com/services,orcontactyourlocalofficeatni.
com/contact.
TrainingandCertification—Visitni.
com/trainingfortrainingandcertificationprograminformation.
Youcanalsoregisterforinstructor-led,hands-oncoursesatlocationsaroundtheworld.
SystemIntegration—Ifyouhavetimeconstraints,limitedin-housetechnicalresources,orotherprojectchallenges,NationalInstrumentsAlliancePartnermemberscanhelp.
Tolearnmore,callyourlocalNIofficeorvisitni.
com/alliance.
YoualsocanvisittheWorldwideOfficessectionofni.
com/niglobaltoaccessthebranchofficeWebsites,whichprovideup-to-datecontactinformation,supportphonenumbers,emailaddresses,andcurrentevents.