Package: CSV List Utilities

Author: Mark Stayton
Version: 2
Added to Library: 11-Nov-23
HCAVersion needed: 16
Keywords: Utility

Package Description:
This package includes supporting functions for working with CSV Lists.

WHAT IS A CSV LIST?

A CSV List is a comma-separated set of values (text or numeric), stored in a global variable.

WHY USE A CSV LIST?

1. CSV Lists can be more easily and quickly traversed versus using the _DesignOpen functions to iterate through the entire HCA design. This can be beneficial for HCA designs containing large numbers of devices and programs.

2. You can create a CSV list of objects associated with a particular function, for example, a list of garage door devices or a list of motion sensors.

3. Your programs can dynamically determine which objects they act upon, by looping through a CSV list. This can reduce re-programming as your design changes.

4. If you use the _choose() function with the same set of choices in more than one program, you can put the choice values in a CSV list, and use the _TextPiece() function to retrieve the value you want. This eliminates coding the same set of choices twice, as well as the need for reprogramming if you add or delete items from the list of choices.

HOW TO FIND ITEMS IN A CSV LIST:

There are several ways to find items in a CSV list:

1. Call the"fn_FindInCSVList" function program from within your own programs, or

2. If you know the position of the item you are looking for within a CSV list, use the _TextPiece() function, or

3. If you want to take some action on all items in a CSV list, create a loop and use the _TextPiece() function to index through each item in the list, or

4. To find a matching string in a CSV list, use the _InStr() function, or use a loop with _TextPiece() to index through the list.

THIS PACKAGE CONTAINS:

(1) function program ( fn_CreateCSVList ) to create a CSV List of items

(1) function program ( fn_FindInCSVList ) to retrieve an item from a CSV List.

(1) utility program ( Create HCA Object CSV Lists ) to generate CSV Lists of HCA devices, programs, groups, rooms, and variables

(1) utility program ( Create HCA Device Types CSV List ) to generate a CSV list of HCA device types (Manufacturer + Model)

(1) utility program ( Create Object Subset CSV List ) to generate a CSV List of a subset of HCA objects, based on a search string that you specify.

(1) utility program ( Create Text CSV List ) to generate a CSV List of text items, based on criteria you enter.

Program: Create HCA Device Types CSV List

Program Description:
This program creates CSV lists of HCA Device Types (a concatenation of the device's Manufacturer and Model names) and Device Protocols. The lists are stored in global variables named "sys_DeviceTypes" and "sys_DeviceProtocols", and the counts of each are stored in global variable "stats_num_DeviceTypes" and "stats_num_DeviceProtocols".

WHAT IS A CSV LIST?

A CSV List is a comma-delimited set of values (text or numeric), stored in a global variable.

WHY USE A CSV LIST?

1. CSV Lists can be more easily and quickly traversed versus using the _DesignOpen functions to iterate through the entire database. This can be beneficial for HCA designs containing large numbers of devices and programs.

2. You can create a CSV list of objects associated with a particular function, for example, a list of garage door devices or a list of motion sensors.

3. Your programs can dynamically determine which objects they act upon, by looping through a CSV list. This can reduce re-programming as your design changes.

4. If you use the _choose() function with the same set of choices in more than one program, you can put the choice values in a CSV list, and use the _TextPiece() function to retrieve the value you want. This eliminates coding the same set of choices twice, as well as the need for reprogramming if you add or delete items from the list of choices.

HOW TO FIND ITEMS IN A CSV LIST

There are several ways to find items in a CSV list:

1. Call the"fn_FindInCSVList" function program from within your own programs, or

2. If you know the position of the item you are looking for within a CSV list, use the _TextPiece() function, or

3. If you want to take some action on all items in a CSV list, create a loop and use the _TextPiece() function to index through each item in the list, or

4. To find a matching string in a CSV list, use the _InStr() function, or use a loop with _TextPiece() to index through the list.

Written by Mark Stayton (mark@thestaytons.net) | Version 1 | 07-Jul-2018

Example:
Keep the system collections up to date by running this program when objects are added to or removed from the HCA design.

Return value: This program does not return a result

Global Variable Use:

Name Description
stats_num_DeviceProtocols Number of device protocols currently in your design.
stats_num_DeviceTypes Number of unique device types currently in your design.
sys_DeviceProtocols DO NOT EDIT! List of all device protocols currently in your design. Update by running the "Create HCA Device Types CSV Lists" program.
sys_DeviceTypes DO NOT EDIT! List of all device types currently in your design. Update by running the "Create HCA Device Types CSV Lists" program.

Program: Create HCA Object CSV Lists

Program Description:
This program creates CSV lists of five types of HCA database objects. Each list is stored in a global variable prefixed with "sys_". The user is prompted to select the object type for the list. A CSV List can be created for any of the following:

Devices

Programs

Groups

Rooms

Variables

WHAT IS A CSV LIST?

A CSV List is a comma-delimited set of values (text or numeric), stored in a global variable.

WHY USE A CSV LIST?

1. CSV Lists can be more easily and quickly traversed versus using the _DesignOpen functions to iterate through the entire database. This can be beneficial for HCA designs containing large numbers of devices and programs.

2. You can create a CSV list of objects associated with a particular function, for example, a list of garage door devices or a list of motion sensors.

3. Your programs can dynamically determine which objects they act upon, by looping through a CSV list. This can reduce re-programming as your design changes.

4. If you use the _choose() function with the same set of choices in more than one program, you can put the choice values in a CSV list, and use the _TextPiece() function to retrieve the value you want. This eliminates coding the same set of choices twice, as well as the need for reprogramming if you add or delete items from the list of choices.

HOW TO FIND ITEMS IN A CSV LIST

There are several ways to find items in a CSV list:

1. Call the"fn_FindInCSVList" function program from within your own programs, or

2. If you know the position of the item you are looking for within a CSV list, use the _TextPiece() function, or

3. If you want to take some action on all items in a CSV list, create a loop and use the _TextPiece() function to index through each item in the list, or

4. To find a matching string in a CSV list, use the _InStr() function, or use a loop with _TextPiece() to index through the list.

Written by Mark Stayton (mark@thestaytons.net) | Version 1 | 07-Jul-2018

Example:
Keep the system collections up to date by running this program when objects are added to or removed from the HCA design.

Return value: This program does not return a result

Global Variable Use:

Name Description
fn_input User input during fn_* programs

Program: Create Object Subset CSV List

Program Description:
This program creates a CSV List of object names in the HCA design that match a string you specify, and stores them in a dynamically-created global variable.

WHAT IS A CSV LIST?

A CSV List is a comma-delimited set of values (text or numeric), stored in a global variable.

WHY USE A CSV LIST?

1. CSV Lists can be more easily and quickly traversed versus using the _DesignOpen functions to iterate through the entire database. This can be beneficial for HCA designs containing large numbers of devices and programs.

2. You can create a CSV list of objects associated with a particular function, for example, a list of garage door devices or a list of motion sensors.

3. Your programs can dynamically determine which objects they act upon, by looping through a CSV list. This can reduce re-programming as your design changes.

4. If you use the _choose() function with the same set of choices in more than one program, you can put the choice values in a CSV list, and use the _TextPiece() function to retrieve the value you want. This eliminates coding the same set of choices twice, as well as the need for reprogramming if you add or delete items from the list of choices.

HOW TO FIND ITEMS IN A CSV LIST

There are several ways to find items in a CSV list:

1. Call the"fn_FindInCSVList" function program from within your own programs, or

2. If you know the position of the item you are looking for within a CSV list, use the _TextPiece() function, or

3. If you want to take some action on all items in a CSV list, create a loop and use the _TextPiece() function to index through each item in the list, or

4. To find a matching string in a CSV list, use the _InStr() function, or use a loop with _TextPiece() to index through the list.

Written by Mark Stayton (mark@thestaytons.net) | Version 1 | 07-Jul-2018

Example:
Start the program and enter the prompts

Global Variable Use:

Name Description
fn_input User input during fn_* programs

Program: Create Text CSV List

Program Description:
This program creates a CSV List of user-entered strings and stores them in a global variable that you specify.

WHAT IS A CSV LIST?

A CSV List is a comma-delimited set of values (text or numeric), stored in a global variable.

WHY USE A CSV LIST?

1. CSV Lists can be more easily and quickly traversed versus using the _DesignOpen functions to iterate through the entire database. This can be beneficial for HCA designs containing large numbers of devices and programs.

2. You can create a CSV list of objects associated with a particular function, for example, a list of garage door devices or a list of motion sensors.

3. Your programs can dynamically determine which objects they act upon, by looping through a CSV list. This can reduce re-programming as your design changes.

4. If you use the _choose() function with the same set of choices in more than one program, you can put the choice values in a CSV list, and use the _TextPiece() function to retrieve the value you want. This eliminates coding the same set of choices twice, as well as the need for reprogramming if you add or delete items from the list of choices.

HOW TO FIND ITEMS IN A CSV LIST

There are several ways to find items in a CSV list:

1. Call the"fn_FindInCSVList" function program from within your own programs, or

2. If you know the position of the item you are looking for within a CSV list, use the _TextPiece() function, or

3. If you want to take some action on all items in a CSV list, create a loop and use the _TextPiece() function to index through each item in the list, or

4. To find a matching string in a CSV list, use the _InStr() function, or use a loop with _TextPiece() to index through the list.

Written by Mark Stayton (mark@thestaytons.net) | Version 1 | 07-Jul-2018

Example:
Start the program and enter the prompts

Return value: This program does not return a result.

Global Variable Use:

Name Description
fn_input User input during fn_* programs

Program: fn_CreateCSVList

Program Description:
This program creates a CSV List of objects whose names contain a string that you specify. The list can be stored as a comma-delimited list in a dynamically-created global variable, or passed back to the calliing program.

The program takes five parameters:

SearchText - the text to match in an object name

ObjectType - type of object to match (1=devices, 2=programs, 3=groups, 4=rooms, 5=variable)

ListName - name of the global variable to contain the CSV List. The variable does not need to already exist; if it does not it will be dynamically created. Leave blank if no global variable is to be created.

CaseSensitive - should search matches be case sensitive, Yes or No

OmitRoom - Omit the room or folder name from the search

WHAT IS A CSV LIST?

A CSV List is a comma-delimited set of values (text or numeric), stored in a global variable.

WHY USE A CSV LIST?

1. CSV Lists can be more easily and quickly traversed versus using the _DesignOpen functions to iterate through the entire database. This can be beneficial for HCA designs containing large numbers of devices and programs.

2. You can create a CSV list of objects associated with a particular function, for example, a list of garage door devices or a list of motion sensors.

3. Your programs can dynamically determine which objects they act upon, by looping through a CSV list. This can reduce re-programming as your design changes.

4. If you use the _choose() function with the same set of choices in more than one program, you can put the choice values in a CSV list, and use the _TextPiece() function to retrieve the value you want. This eliminates coding the same set of choices twice, as well as the need for reprogramming if you add or delete items from the list of choices.

HOW TO FIND ITEMS IN A CSV LIST

There are several ways to find items in a CSV list:

1. Call the"fn_FindInCSVList" function program from within your own programs, or

2. If you know the position of the item you are looking for within a CSV list, use the _TextPiece() function, or

3. If you want to take some action on all items in a CSV list, create a loop and use the _TextPiece() function to index through each item in the list, or

4. To find a matching string in a CSV list, use the _InStr() function, or use a loop with _TextPiece() to index through the list.

Written by Mark Stayton (mark@thestaytons.net) | Version 1 | 07-Jul-2018

Example:
Call this program using a Start Program element in your own program. Specify the parameters, and optionally select a local variable in your program to receive the result.

This program must be called from within another program. It does nothing if run directly by the user.

Return value: The contents of the list may be returned to the calling program.

Parameters:

Name Type Description Default
SearchText Value Text to match for an object to be included in the CSV list  
ObjectType Value Type of objects in the CSV list (1=devices, 2=programs, 3=groups, 4=rooms, 5=variables)  
ListName Value Name of global variable to store the CSV List. Leave blank if no global var is desired.  
CaseSensitive Value Whether or not $SearchText is case sensitive. Boolean (Yes or No) No
OmitRoom Value Omit Room/Folder Name from search (Yes or No) No

Program: fn_FindInCSVList

Program Description:
This program searches the contents of a global variable containing a CSV List of items. It can return the nth item in the collection, or it can return the first element that matches a string that you provide.

This program takes four parameters:

ListName - the name of the global variable containing the CSV list of items

Key - if a number is specified, returns the Key-th item in the list. If a string is specified, return the first object in the list containing the search string.

CaseSensitive - should search matches be case sensitive, Yes or No

OmitRoom - Omit the room or folder name from the search, Yes or No

WHAT IS A CSV LIST?

A CSV List is a comma-delimited set of values (text or numeric), stored in a global variable.

WHY USE A CSV LIST?

1. CSV Lists can be more easily and quickly traversed versus using the _DesignOpen functions to iterate through the entire database. This can be beneficial for HCA designs containing large numbers of devices and programs.

2. You can create a CSV list of objects associated with a particular function, for example, a list of garage door devices or a list of motion sensors.

3. Your programs can dynamically determine which objects they act upon, by looping through a CSV list. This can reduce re-programming as your design changes.

4. If you use the _choose() function with the same set of choices in more than one program, you can put the choice values in a CSV list, and use the _TextPiece() function to retrieve the value you want. This eliminates coding the same set of choices twice, as well as the need for reprogramming if you add or delete items from the list of choices.

HOW TO FIND ITEMS IN A CSV LIST

There are several ways to find items in a CSV list:

1. Call the"fn_FindInCSVList" function program from within your own programs, or

2. If you know the position of the item you are looking for within a CSV list, use the _TextPiece() function, or

3. If you want to take some action on all items in a CSV list, create a loop and use the _TextPiece() function to index through each item in the list, or

4. To find a matching string in a CSV list, use the _InStr() function, or use a loop with _TextPiece() to index through the list.

Written by Mark Stayton (mark@thestaytons.net) | Version 1 | 07-Jul-2018

Example:
Call this program using a Start Program element in your own program. Specify the parameters, and select a local variable in your program to receive the result.

This program must be called from within another program. It does nothing if run directly by the user.

Return value: This program returns the name of the found item. If nothing was found, 'No' is returned.

Parameters:

Name Type Description Default
ListName Value Global variable containing comma-delimited list of items  
Key Value Index number to retrieve from the collection, or text to search  
CaseSensitive Value Whether the search is case sensitive (Yes or No) No
OmitRoom Value Omit Room/Folder Name from search (Yes or No) Yes