FindItem Method (DATASET)
The FindItem method finds a data item in a DATASET using a {key} or {index}. 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.
return
Optional. A Character String Variable that returns the key and/or index. 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.
index
Optional. A Numeric Variable, decimal number, or Numeric expression whose numeric value is used to find an item.
{flags}
Optional. A Numeric Variable, decimal number, or Numeric expression that defines a bit mask value that is used to control the FindItem 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 and OVER flags are always cleared.
The {flags} bit mask values found in plbmeth.inc are defined as follows:
|
Equate |
Value |
Description |
|
$DSF_FIND_KEY_CASE_SENSITIVE |
0x00000001 |
Key string is case sensitive. |
|
$DSF_FIND_FIFO |
0x00000002 |
Process from bottom to top as a FIFO. |
|
$DSF_FIND_KEY_AND_INDEX |
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_FIND_NEXT_ITEM |
0x00000008 |
Start searching for a data item that matches the DATAFILTER with data item following after the data item found using the key/index. |
|
$DSF_FIND_NO_FILTER |
0x00000010 |
Do not use the DATAFILTER property for the DATASET for the FindItem method. |
|
$DSF_FIND_FILTER_SEARCH |
0x00000020 |
Continue searching until a data item matches the DATAFILTER being used. |
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 |
|
2 |
The data item could not be found! |
See Also: Method Syntax
|