UpdateItem Method (DATASET)

10.8, PLBCMP GUI Only

 

The UpdateItem method finds a data item in a DATASET using a {key} or {index} and updates the data for the data item. This method only replaces the data for the data item. If the update data size is less than or equal to the current maximum data size of the data item, it's current data is simply overlayed. However, if the update data size is larger than the current maximum data size, the current data item is freed and reallocated for the update data. The data item {key} and {index} remain the same. This method does not perform any partial update for the data item data. The DATAFILTER property is not used by the UpdateItem method. This method uses the following format:

 

 

[label]

{object}.UpdateItem

[GIVING {return}] USING [*TEXT=]{text}[:

 

 

[*KEY=]{key}][:

 

 

[*INDEX=]{index}][:

 

 

 [*FLAGS=]{flags}]

 

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 that returns the key string for the data item. Otherwise, an error string formatted as "$ERROR$=errorinfo" is returned.

text

Required. A Character String Variable or literal that contains data to update a data item in the DATASET.

key

Optional. A Character String Variable or literal that contains a key string used to find a data item in the DATASET. If both the {key} and {index} keywords are specified, {key} is used to find the data item. If both the {key} and {index} are not specified, the last accessed DATASET data item is updated. Otherwise, an erro occurs.

index

Optional. A Numeric Variable, decimal number, or Numeric expression whose numeric value is used to find a data item.

flags

Optional. A Numeric Variable, decimal number, or Numeric expression that defines a bit mask value that is used to control the UpdateItem method 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 {flags} bit mask values found in plbmeth.inc are defined as follows:

    5.  

    Equate

    Value

    Description

    $DSF_UPDITEM_KEYCASE_SENSITIVE

    0x00000001

    Key string is case sensitive.

    $DSF_UPDITEM_GET_KEY_AND_DATA

    0x00000002

    Return both the key string and the index separated with a comma delimiter.

    $DSF_UPDITEM_ALLOW_NULL

    0x00000020

    Updated item can be a null string.

     

  5. When this method generates an error, the {return} variable contains an error code value as follows:

    6.  

    Error Code

    Description

    1

    The update text cannot be null.

    3

    Update data must be a valid JSON string.

    4

    Update key not found in DATASET.

    5

    The data item is not found using index.

    6

    Valid key or index required.

    7

    Can not update a ReadOnly data item.

    9

    Unable to allocate memory.

    99

    Internal error. Hash index table not created.

 

 

 

See Also: Method Syntax, DATASET Methods

 


PL/B Language Reference