Wednesday, June 3, 2009

LabVIEW Scripting Tip #1: The Power of Traverse

This blog post is the first in an as yet unknown number of posts detailing some useful tips I have on LabVIEW Scripting.

If you're ever examining VIs to find objects of a particular type, then you definitely want to check out the following utility VI:

[LabVIEW]\vi.lib\utility\traverseref.llb\TRef Traverse for

This VI will return references to all the objects of a given class that reside within the panel, diagram, or a user-defined object in a VI. The traversal is recursive, so it will find objects nested within other objects. Here's a simple example that finds all the Case Structures on a diagram:

We specify a target of "BD" (for Block Diagram) and a class name of "CaseStructure", and we're good to go. Note that you can also traverse the front panel for objects by specifying a target of "FP". And if you want to traverse a specific object (i.e. find all the clusters that reside within a particular Tab Control on the front panel), then specify a target of "Other" and pass in a reference to the Tab Control to the "Other Refnum" input.

You may wonder why I recommend using this VI, when there is already a scripting property called AllObjects[] for the Diagram class (and a similar property for the panel). Well, that AllObjects[] property does not recurse into container objects. So to completely search a diagram for objects, you would need to get the AllObjects[] property, figure out which objects are containers, separate those objects out, get the container diagrams, do an AllObjects[] on them, etc. etc. This is certainly doable, and I'm guessing people have already written VIs that do this...but in my experience, using the Traverse VI is much, much faster than trying to recurse the entire diagram with AllObjects[].

This traverse VI is used extensively in the VI Analyzer Toolkit, since we are often looking for specific objects on the diagram that we need to examine. And if you know the label of a specific object you are looking for, then you can use the TRef Find Object By in that same LLB, which is basically a wrapper for TRef Traverse for, but it goes an extra step and reads the labels of each found object until it finds the one you were looking for.

Just to give you an idea how useful this VI can be, TRef Traverse for originally shipped only with the VI Analyzer Toolkit 1.0 when LabVIEW 7.0 released. However, once it got to the point that about a dozen internal groups at NI had asked me for a copy of the Traverse VI so they could ship it with their products, I decided it would be best for all of us if a single copy of the VI shipped with core LabVIEW, which it has since LabVIEW 8.0.


  1. Hey Darren. Great post. Is there any chance that this VI's block diagram can be opened up (not pw protected), now that scripting is publicly accessible?

  2. Great info. I gather the Class Name control could become an enum now that scriping is released.

  3. This is a great tip!!
    I agree with David, an enum for Class Name would be nice ;)

  4. Jim: I wasn't able to remove the passwords in time for the LabVIEW 2009 release. However, I do plan on writing a detailed article for the NI Community website at some point soon that goes into much more detail on how exactly the Traverse VI works.

    David and Antoine: An enum, although more convenient than a string, would be a maintenance headache, as I would need to update it with every LabVIEW release with all the new class names that have been added to VI Server. I also considered creating an XNode that would take a refnum as input, and would traverse for the class of that refnum, and output the reference array with the same class as the constant that was wired in...but I never had time to do it. And considering the ubiquity of the Traverse for References VI in currently shipping NI products, I imagine it would be more trouble than it's worth at this point to change it.

  5. Darren: no problem, it's nice to hear that removing the pw is on your roadmap. Thanks.

  6. Darren, I was playing around with my own traversing. I was experimenting with three different techniques: All VIs in memory, By File Location), and VI-Server Calees properties. In addition I have excluding options for vi.lib, user.lib, instr.lib and OpenG.
    Can you give some recommendations on how to do it 'best', as I need to work on 7.1 so I don't have the

  7. Blackpearl: It sounds like you're trying to search through entire VI hierarchies. Are you looking for certain VIs in the hierarchy? That's not exactly what TRef Traverse for is for...this VI is for finding certain objects on the front panel or block diagram of a VI. Now if you're talking about searching through entire sets of VIs looking for objects, that's pretty much what the VI Analyzer framework is for, and why I wrote the Traverse VI in the first place.

    Also, I noticed you already found the Traverse LLB that I saved in 7.x format on the NI Community website. For everyone else, I posted a 7.x version of the Traverse LLB here:

  8. I'm actually exploring ways to search/traverse because I knew it was there but not in 7.1. FDS. It is really the reusable portion of code if doing any kind of 'scripting' (in this case including any sanity check for FP elements which was ever doable, not only the private stuff nor real scripting).
    I was trying to code it on my own, but this effort is dropped now that you made it public.
    BTW: I directly came to this blog post when I got the email that you released it for 7, so how it comes to know I found it? But thanks anyway...

  9. I got the email that you commented on my community post before I posted the comment above...that's how I knew. :)

  10. In between the time to figure out (for me) how to use the '5 star rating system' thst governs the new 'community'. Can't we have the kudos sytem everywhere? And can't I stop monitoring work related things when I'm off.

  11. Darren,
    Did you ever write that article on the internal workings of traversing? Many good applications of traversal involve processing the items as you traverse. ie, you don't know the objects ahead of time. That is why you are traversing.
    - Right now I am using a modified version of the diagram color changer Michael Aivaliotus posted on LAVA a while back.
    - If your traverse is more efficient it would be great to have access.
    Mike Ashe

  12. Hi Mike,

    The Traverse VI will be shipping without passwords, with documentation, and in the palettes in LabVIEW 2010. I think those changes will provide enough information on the internal workings of my Traverse VI and the Traverse method.

  13. Kudos for this post!
    Thanks a lot!