While many items in a script can be determined dynamically based on context and offered as a selection in a list, there are equally as many items that are tied to your specific environment or your business logic. There is simply no way we can foresee these items and offer them as you need them.

What we have done however, is to enable you to customize PrimalSense and create your own lists, based on your needs and your environment.

Basic lists and static data

Invoking these custom lists is really easy. Type the name of the list and press Ctrl + L, as in List and it will show up. Lists are stored in this folder: C:\ProgramData\SAPIEN\PrimalScript 2015\Lists. The file name designates the name of a list. To make this feature as flexible as possible, we have designed this with three different types of lists.

List Types

1. Static list.

The data for this list is stored in a CSV file or an XML file. For just a simple, single selection list only the data file is required.

2. Cached list.

A configuration file (.ini) contains a command to generate the data file for this list (CSV or XML). The command is only executed ONCE per PrimalScript session and the data file is kept around. If you exit PrimalScript and start it again, the command will be executed again. This is very helpful for data that is dynamic, but does not change very often, e.g. available PowerShell modules.

3. Dynamic list.

A dynamic list executes the command you specified each time you invoke that list. The data format once again is either CSV or XML. A good example for this type of list is the “file” example we provided. It lists the folder content of the directory the current file resides in. Since files get created, deleted or renamed all the time, this list has to always use current data.

Data Format

Ok, so how does the data part work? You can use a CSV file if your data is single line items.

If you have only simple strings, then you do not even need to use commas. Just list your items one per line. Sometimes you need to provide a little more information or translate some weird strings into something human readable. GUIDs used for DSC resources are a good example. I cannot remember that many numbers nor can I really distinguish them when I see them. So we show a translation that makes sense but insert the GUID when selected

The data file for this is also just a simple CSV file.

The first column contains the human readable string, the second column is an image index (we get to that later) and the third column is the data we want inserted when selected. You can use this translation for a lot of things to simplify selections, file names to full path names, weird SQL table names to more understandable terms e.g. “Customer Table” to “SQLQCust64527872NMA7657”. If you have seen some SQL databases you know what I mean.

An XML file can be used if the text you want to be inserted has more than one line. The functions.xml file is an example for this.

Selecting an item inserts the corresponding code into your script.

The XML format is very simple.

The root node is called <List>, each individual item is in an <item> tag. The “Name” attribute defines the string displayed in the list and the “image” attribute defines an index into the list’s images. The text to be inserted is contained within a CDATA section. Please note that you must use a CDATA section, regular text would be ignored.

So now you know how to create simple static lists to insert simple strings or even multi-line text.

Images and multiple selection

If your list has just a single type of items an image is not really necessary, but if you have different types, it would be nice to give these items a visual distinction.

Let’s take a look at the ‘machines’ example that gets installed with PrimalScript.

We have different icons for workstations and network servers in this example, so let’s see how this is done.
The data file, machines.csv, has the same basic setup with the strings and an image index for each item.

This time however we also have an additional configuration file, machines.ini. As you can probably guess the file’s base names (machines) tie them together.

The format of this is very simply, I am sure you can figure out what item controls what setting. The important part now is the ‘imagelist’ entry. It points to a file called icons.bmp.

As you can see index 0 and 4 are the icons we see in our example. These bitmap files contain image that are 16 by 16 pixels, that is what PrimalScript uses for PrimalSense lists.
They are bitmap files (BMP) because that is what Microsoft Windows wants for list control image lists. Last but not least, the background (RGB value 255,0,255) is what is mapped to transparent. You cannot use jpeg or png files here, sorry.

Another setting you can see in this sample ini file is that multiselect is set to 1. That is what makes the checkboxes show up. Normally PrimalSense lists are single select. You select and press Enter to insert the item chosen. If you have computer names, you may need more than one, so you can check the ones you want, press Enter and all items checked get inserted. The separator, which defaults to a space, is used to concatenate the items into a string.

It is all very simple. As an exercise, look at the functions.xml file we provided and make it multi-select. This way you can select the functions you want to insert into your code. With a little work you can make this into a poor man’s code wizard that inserts the standard functions you need for a new script. Think of it as a selective snippet.

Cached and dynamic data lists

Some of the information you want to display in a PrimalSense list is not static. It can change dynamically from day to day or even every second. In order to enable you to display such ever changing information we added a mechanism to create the data on the fly by an external process. While we will use Powershell in our examples here, this is not limited to PowerShell. You can use any programming or scripting language, command line or windows tool that you can make generate the previously described data files in either CSV or XML format.

Let us start with an example for a cached list. A cached list will only execute the associated process once per session. This is useful for data that may take a little longer to generate but does not change all the time. A list of available Powershell modules is a good example. The list can change, but usually changes will only occur upon installation system updates or additional software.

Most of the items in this INI file will be familiar from the last post.

Name is the identifier for the list.
Multiselect determines if the list is single select (0) or multi-select (1).
Imagelist provides a bitmap for a custom image list.
Type specifies the type of list. Possible values are “static”, “cached”  or “dynamic”.

Here are the new items that apply to this sample:

Timeout specifies the amount of time PrimalScript will wait for a process to finish in milliseconds. The default value is 2000 (2 seconds).
if a process does not finish within the specified amount of time, PrimalScript will use data from a previous session if available or simply do nothing if there is no data.
As PrimalScript has to wait for the process to finish make sure you understand that a long running task will block PrimalScript until the process ends or the timeout expires.

Process specifies the process to run to generate the data for the list.

Datafile is the name of the generated data file. If you just specify the file name, the file is assumed to be created either in the lists folder or in the folder the currently active script exists in. You can specify a fully qualified file name if the data has to be pulled from a central location.

The second example we show you today is for a dynamic list. The process associated with this will launch every single time you launch the list.

The file list shows the files contained in the same folder as the currently active script. Note the changed type to “dynamic” and of course the different process.

As a side note, if you need to run an elevated process you can use the “elevated” keyword instead of “process”. Since this usually prompts for confirmation the timeout may be getting in your way. It is usually best to avoid using elevated commands for generating dynamic lists.

As you can see, making dynamic lists is just as simple as static lists. As a little exercise, take the file list example and make a “script” list that only displays *.ps1 files.

If you have any questions, comments or suggestions, please feel free to go the PrimalScript forum and post what is on your mind.

• Prev
• Next