AddItem Method (DATASET)

10.8, PLBCMP GUI Only

The AddItem method adds a data item to a DATASET. This method uses the following format:

Where:

label

Optional. A Program Execution Label.

object

Required. A DATASET object to which a data item is being added.

return

Optional. A Character String Variable can contain key, index, or error data being returned by the add item method.

text

Required. A Character String Variable or literal that contains data to be added to the DATASET.

keystr

Optional. A Character String Variable or literal that contains a unique key used to access the {text} data in the DATASET. If this {keystr} is not provided, the DATASET creates a unique internal key used to access the {text} data.

flags

Optional. A Numeric Variable, decimal number, or Numeric expression that defines a bit mask value that is used to control AddItem behaviors.

Flags Affected: EOS, OVER, ZERO

Notes:

1. The EOS flag is set if the returned data is truncated because the {return} variable is too small.

2. The ZERO flag is always set TRUE.

3. The OVER flag is always cleared.

4. The {key} has a maximum key size of 64 characters. If the {key} is not specified, the AddItem method automatically creates a unique key formatted as follows:

 

Key Format:

 

nnnnnnnnnn - Coordinated Universal Time in seconds. Continually incrementing. (10 digits max)

tttttttttt - Current runtime thread id. (up to 10 digits)

ssssssssss - Sequential incrementing counter for number of of items in the DATASET. Increments to a 32-bit value and rolls over to zero. (10 digits)

 

Example Key for DATASET items:

 

1753113209-24392-1 - First {key}

1753113209-24392-2 - Second {key}

 

 

1753113nnn-24392-sss - Incrementing {key} format

 

5. The {flags} bit mask values found in plbmeth.inc are defined as follows:

 

Equate	Value	Description
$DSF_ADDITEM_KEYCASE_SENSITIVE	0x00000001	Key string is case sensitive.
$DSF_ADDITEM_GET_KEY_AND_DATA	0x00000002	Reserved for future use.
$DSF_ADDITEM_RETURN_ITEM_INFO	0x00000004	Reserved for future use.
$DSF_ADDITEM_GET_KEY_AND_INDEX	0x00000008	Return both the key string and index for the added data item.
$DSF_ADDITEM_PUSH	0x00000010	Used only for internal use by Push.
$DSF_ADDITEM_ALLOW_NULL	0x00000020	Added item can be a null string.
$DSF_ADDITEM_READONLY	0x00000040	Data item being added is read only.

 

6. When this method generates an error, the {return} variable contains the error string formatted as follows:

 

$ERROR$=nnn

 

Where the 'nnn' error value as follows:

 

Error Code	Description
1	Text parameter must contain input data Null is not allowed!
2	Maximum items have been stored in DataSet.
3	Item data must be valid JSON object syntax.
4	Duplicate key found which is not allowed.
9	Unable to allocate memory.
99	Internal error. Hash index table not created.

 

 

See Also: Method Syntax, DATASET Methods