AddString Method (DATALIST)

PLBCMP GUI Only

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

Where:

label

Optional. A Program Execution Label.

object

Required. A DATALIST 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 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 {string} 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. When a tab character (0x9) is found in an item in the DATALIST, the next character displayed starts at the next tab position. See the DATALIST TABSTOPS property for details for tab stops.

Example:

Data INIT "abc", 0x9, "def", 0x7F: //Item 0 with 2 columns

            "lmn", 0x9, "opq", 0x7F: //Item 1 with 2 columns

            "rst", 0x9, "uvw" //Item 2 with 2 columns

     Expected Results:

          abc def

          lmn opq

          rst uvw

See Also: Method Syntax, DATALIST Methods