GetItem Method (DATASET)
10.8, PLBCMP GUI Only
The GetItem method finds a data item in a DATASET using a {key} or {index} and retrieves the associated data string. The return data can be plain text, formatted data like JSON, XML, binary data, ...etc. Also, if the DATAFILTER property is set for the DATASET, this method uses the filter when the data item(s) have a JSON data type. 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 that returns the data string for the data item. Otherwise, an error string formatted as "$ERROR$=errorinfo" is returned.
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, the {key} is used to find the data item. If both the {key} and {index} are not specified, the last accessed DATASET data item is used. Otherwise, an error occurs.
index
Optional. A Numeric Variable, decimal number, or Numeric expression whose numeric value is used to find a data item.
delimiter
Optional. A Character String Variable or literal that contains a delimiter character used by the GetItem method. If the method keyword is not used, the GetItem method uses a default ',' comma character as the delimiter.
flags
Optional. A Numeric Variable, decimal number, or Numeric expression that defines a bit mask value that is used to control the GetItem method behaviors.
Flags Affected: EOS, OVER, ZERO
Notes:
The EOS flag is set if the returned data is truncated because the {return} variable is too small.
The ZERO flag is always set TRUE.
The OVER flag is always cleared.
The {flags} bit mask values found in plbmeth.inc are defined as follows:
|
Equate |
Value |
Description |
|
$DSF_ITEM_KEYCASE_SENSITIVE |
0x00000001 |
Key string is case sensitive. |
|
$DSF_ITEM_GET_KEY_AND_DATA |
0x00000002 |
Reserved for internal use. |
|
$DSF_ITEM_GET_ITEM_INFO |
0x00000004 |
Return both the key string and index for the data item when found. Also, if the DATAFILTER is being used, the current filte state flag ( 0 or 1 ) is returned. |
|
$DSF_ITEM_GET_NEXT_ITEM |
0x00000008 |
Start searching for a data item that matches the DATAFILTER with data item after following data item found using the key/index. |
|
$DSF_ITEM_GET_PRIOR_ITEM |
0x00000010 |
Do not use the DATAFILTER property for the DATASET for the FindItem method. |
|
$DSF_ITEM_GET_FILTER_SEARCH |
0x00000020 |
Continue searching until a data item matches the DATAFILTER being used. |
When this method generates an error, the {return} variable contains an error code value as follows
|
Error Code |
Description |
|
1 |
The item data size is too large for DATASET output buffer! Sunbelt internal error. |
|
2 |
The data item could not be found! |
|
3 |
DataSet data item is NOT JSON data type. |
|
4 |
DATAFILTER expression does not find a match. |
|
5 |
End of DATASET encountered before DATAFILTER match. |
:
See Also: Method Syntax, DATASET Methods
|