FindItem Method (DATASET)

10.8, PLBCMP GUI Only

 

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:

 

 

[label]

{object}.FindItem

[GIVING {return}] [USING [[*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 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:

  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_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.

     

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

 

Error Code

Description

2

The data item could not be found!

 

 

 

See Also: Method Syntax, DATASET Methods


PL/B Language Reference