Citect.ini Parameter Buffer

Requirements
Citect v5 - v7

Description
Cicode functions often need to read Citect.ini parameters using ParameterGet(). This is very quick for a single read, but can become a problem with many Cicode tasks reading many parameters, or reading them often in a loop. This is even more of a consideration if the hard drive is already busy, such as on a trend server.

One way to avoid this is to read the parameter value once and store it in a Cicode variable. However, to better support online changes it can be good to be able to change parameter values during the runtime. This would require recording the time the parameter was read, and re-reading it when that time elapses. If this needs to be done for multiple parameters, this adds a lot of custom code.

The ParameterGetBuf() Cicode function in this download acts like the built-in ParameterGet() function. However, it stores each parameter it reads in an array. Until the timeout has elapsed, any more requests for the same parameter will be serviced from memory. You can specify the cache timeout when calling ParameterGetBuf() or it will default to 1 minute. You can also specify min and max limits for the value and out of range values will be clamped to the limit.

To make it work as fast as possible, the Binary Search function from Knowledge Base article Q5713 is used to search the parameter array for the requested parameter. Instead of having to search up to 64 array elements for the parameter, Binary Search only has to check a maximum of 6 elements to find what it's looking for, as long as the array is alphabetical. This version of Binary Search was modified to use an index array so the parameter name, value, and time arrays do not all have to be re-ordered every time a new parameter is added. The ShellSortIdx() function from Q3750 is used to make the index of the parameter names. Another optimization is that it remembers the last requested parameter and does a quick check to see if it is being requested again. That way, if a Cicode loop is constantly requesting the same parameter, it can be returned without even searching the array. These optimizations allow it to return parameter values in approximately 1/15 of the time of ParameterGet().

By default up to 64 parameters are buffered in memory. This can be increased, but will increase the search time slightly, and shouldn't be necessary. If more than 64 parameters are requested, the ones in memory that were read the longest time ago will be dropped to make room for new parameters. This keeps the most often requested parameters in memory. Parameters that are rarely requested would likely need to be re-read from disk anyway because their cache time would likely have expired.

Updates
v1.02 Fixed text or blank parameter values being returned as "0". Added missing ValueLimit() function
v1.01 Added optional min/max limits
v1.00 Original Release

Author
Eric Black

Submitter
Eric Black