ListOfDevices Function

 

The ListOfDevices function is used to request a list of objects and their key fields from the Simulator Automation Server. The function can return all devices of a particular type, or can return only a list of devices of a particular type based on an advanced filter defined for the loaded case. This function is best used in conjunction with a looping procedure and the ChangeParameters or GetParametersSingleElement functions to process a group of devices.

 

Function Prototype

ListOfDevices(ObjType, filterName)

 

Parameter Definitions

ObjType : String The type of object for which you are acquiring the list of devices.

Filter : String The name of an advanced filter, a device filter, or a single-condition filter. If no filter is desired, simply pass an empty string. An error will be returned if a named filter cannot be found, device cannot be found for a device filter, or a single-condition filter is in the wrong format.

 

Output

The output is a variant array:

Output(0) — error string

Output(1) — set of nested arrays containing the key field values for the device type requested. The number of arrays of values returned depends on the object type selected. For instance, buses have only one key field (the bus number) so calling ListOfDevices for buses will return only one array of values—the bus numbers. On the other hand, calling ListOfDevices for branches will return three arrays of values—the "From" bus, "To" bus, and ID—for each branch in the case meeting the specified filter.

 

Output Structure

The arrays containing the key field values for each device are arranged as shown in the following figure:

 

As you can see, to access the first key field value for the first device, Output[1][0][0] would be the correct array index. For example, the bus number (which is the bus key field) for the first bus would be stored at Output[1][0][0] after calling Output = ListOfDevices('Bus', '').

One unique limitation of the ListOfDevices function from other SimAuto functions is that this is the only function that returns the output as strongly typed variables. The bus numbers are always returned as Long Integers, and the Circuit ID values are returned as strings. This was actually an oversight during the design of SimAuto. In all other SimAuto functions, the values are returned as Variant types, with each value within the variant being a string. This was the intended operation for this function as well. Since the Automation Server interface was released with the errant inclusion of the ListOfDevices function, it could not be modified. Therefore, another function, ListOfDevicesAsVariantStrings, has been created. This function returns all values in variant variables, with each as a string within the variant type.