AddString Method (COMBOBOX)

PLBCMP GUI Only

The AddString method inserts a new string into a COMBOBOX object. The method uses the following format:

Where:

label

Optional. A Program Execution Label.

object

Required. A COMBOBOX object to which a string is added.

return

Optional. A Numeric Variable that returns the zero-based position of the string within the list.

string

Required. A Character String Variable or literal that specifies the string that is added.

flags

Optional. A Numeric Variable or decimal number whose value is a bit mask that defines behavior for this method. (9.6)

Delimiter

Optional. A Character String Variable or literal whose form pointed character defines a delimiter character that separates the combobox text data from an application data value. (9.6)

Flags Affected: EOS, OVER, ZERO

Note the following:

1. If the SORTED property of {object} is true, the string is inserted and the list is sorted. Otherwise, the string is added to the end of the list.

2. Multiple logical records may be loaded into an object in a single operation. An embedded 0x7F character in {data} is identified as a logical record terminator. The detection of the 0x7F is a default action by the runtime for the INSERTITEM and SETITEM instructions and the AddString and InsertString methods. These operations provide improved load times when using the PL/B Application Server. The feature may be enabled or disabled by using the SETMODE *USE7F instruction.

3. If the method is successful, the zero-based position of the new string in the list is returned. If the method is not successful, {return} will contain a -1.

4. If the value returned is zero, the ZERO Condition Flag is set.

5. If {return} is too small to contain the new string position, the OVER Condition Flag is set.

6. The EOS Condition Flag is always cleared.

7. For improved performance in the Application Server environment, do not specify the optional return value unless needed.

8. The {flags} bit mask definitions are defined as follows: (9.6)

 

0x1 - The input {string} data stream is processed to allow an application data value to be specified for a Combobox data item. The expected format of the data stream allows the application data value to be appended to the data item text using a delimiter character. By default, the tab character (0x09) is the delimiter unless the {delimiter} method parameter is specified.

 

Example {string} with item data value:

Data INIT "abc",0x09,"123",0x7F,"rst",0x09,"456",0x7F,"xyz",0x09,"999"

 

9. The {delimiter} method parameter is only valid when the {flags} bit is 0x1. The character at the form pointer is used as the delimiter character when processing application data values that are assigned to a specified data item in a COMBOBOX. If the {delimiter} parameter is not specified, the default delimiter character is a tab (0x09) character. (9.6)

See Also: Method Syntax, COMBOBOX Methods