Add Item

Use this system function to add an item to the combo box if it is not displaying a list that is based on a UDC.

Parameters

ComboBox Control

Input, required. The combo box FC to affect.

Key

Input, required. The key of the item to add (string or math-numeric). Set the parameter to an alphanumeric constant (<Literal>) or applicable object from the object list.

Item

Input, required. The name of the item to add (string). Set the parameter to an alphanumeric constant (<Literal>) or applicable object from the object list.

Index

Input, optional. The zero-based index position where the item is to be added (integer). If you do not specify this parameter, runtime appends the item to the bottom of the list. The default -- Select One -- prompt always occupies index position zero. If an invalid index is specified, the addition of the new item fails and an error message is logged. Set the parameter to an alphanumeric constant (<Literal>) or applicable object from the object list.

Additional Notes

Use this system function to add an item to the combo box. Runtime verifies that the Key and Item parameter values are both specified. If either is missing, the addition of the new item fails and an error is logged. If you try to insert an item having a key value that already exists in the list, runtime will not add the item and will log an error. The combo box control must reside on the form (as opposed to being embedded in a grid). The control must have a valid data dictionary item associated with it.

If the key value of the key/description pair specified in the Add Item system function call to be added to the control corresponds to a valid key value in the associated UDC set and that key value is currently not loaded in the control (in other words, it was removed after the control was initialized), the runtime engine allows the item to be added back into the control. Runtime recognizes the fact that it currently does not exist in the control's item list and that it is a valid key value in the UDC's set. Otherwise, the attempt to add the new item will fail.