i = setvalueset
function allows you to dynamically change an item's current value set. An item's current value set is used to determine whether or not inputted values are out of range. The current value set is also used to provide the value choices displayed in extended controls
. The change of value set is not permanent; it remains in effect only during the current execution of the program or until the next call to setvalueset
The item_name is the name of the item in the data dictionary whose value set is to be changed. The argument is usually an item name but, preceded by the @ symbol, it can also be a string expression that evaluates to the name of an item; for example:
In the standard form, the argument value_set_name is the name of an existing value set in the dictionary for the specified item. The function will replace the values of the current value set for the item with the values from the value set specified by value_set_name, which is either the name of a value set or a string expression that evaluates to a value set name.
With dynamic value sets, the second argument, codes_array, is an array of codes to use in the new value set and the third argument, labels_array, is an array of labels that correspond to the values in the codes array (the nth element of the labels array is the label for the nth element in the codes array). If the item is numeric, codes_array must be a numeric array. If the item is alphanumeric, codes_array must be a string array. The labels_array must always be a string array. The optional fourth argument, images_array, is a string array pointing to image filenames to be used as value set images.
When working with the codes_array
, to indicate the end of a numeric array, assign the special value notappl
to the position after the last valid code. To indicate the end of a string array, assign a blank value. This indicates when to stop loading values from the array.
In versions of CSPro earlier than 6.0, the value set labels and codes array needed to start at index position 0. Zero-based arrays are still permitted, but if a one-based array is passed to the function (and the zeroth element has never been assigned to), then CSPro will start processing the dynamic value set at array position 1.
In the standard form, the function returns a logical value of 1 (true) if the value set was changed successfully and 0 (false) otherwise (for example, if the value set name is invalid).
With dynamic value sets, the function returns the number of codes in the newly created value set.
) = 1
) = "District 1"
) = 2
) = "District 2"
) = 3
) = "District 3"
) = notappl
; // mark the end of the array