Package: Do By Tag

Author: HCA Central
Version: 3
Added to Library: 11-Nov-23
HCAVersion needed: 17
Keywords: Utility

Package Description:
This program enumerates devices that match a criterion and performs an action upon them. That action is expressed in another program - called the "Target Program" - that is started for each device.

The enumeration can be for all devices, or only devices with a named tag, or with a named tag and named value. The "Target Program", whose name is supplied as an argument, if then started for each device found.

The "Target Program" has one parameter which is the name of the device, performs any action it wants using that device. This program must "return a value". If that value is zero, then the next device is found, and the program started again for that new device. If a non-zero value is returned, then the device enumeration ends.

Program: Do By Tag

Program Description:
This program enumerates devices that match a criterion to perform an action upon them. That action is expressed in another program - called the "Target Program" - that is started for each device.

The enumeration can be for all devices, or only devices with a named tag, or with a named tag and named value. The "Target Program", whose name is supplied as an argument, if then started for each device found.

The "Target Program" has four parameter which is the name of the device, name of the tag, value of the tag, and any user data supplied to this program when started. The "handler program" the performs any action it wants using that device. This program must "return a value". If that value is zero, then the next device is found, and the program started again for that new device. If a non-zero value is returned, then the device enumeration ends.

Return value: Returns 0 if all worked, non-zero if it didn't

Parameters:

Name Type Description Default
ProgramName Value Name of program to start for each device  
TagName Value Optional: Name of tag to match  
TagValue Value Optional: Name of tag value to match  
UserData Value Optional: Data supplied to this program and given to handler program. Can be anything needed.  

Program: Example Do By Tag Handler

Program Description:
Example handler program that is provided each device that matches the criterion established by the "Example Do By Tag Starter" program and either suspended or resumes it depending upon how "Example Do By Tag Starter" is started.

Parameters:

Name Type Description Default
DeviceName Object Device object found by Do-By-Tag program  
TagName Value Name of tag in device that matches Do-By-Tag criterion  
TagValue Value Value of tag in device that matches Do-By-Tag criterion  
UserData Value Data item given to Do-By-Tag. Can be used for any purpose wanted  

Program: Example Do By Tag Starter

Program Description:
Example program that uses Do-By-Tag to locate all devices that have a "Color" tag whose value is "Blue". If this program is "started by ON" then those devices are resumed. If "Started by Off" then those devices are suspended.