Locates single or multiple specified search values in a dataset.

Syntax

  function ibec_ds_Locate(Dataset : variant; KeyFields : string;    
                          KeyValues : array of variant; Options : integer) :  Boolean;    

Description

ibec_ds_Locate locates single or multiple specified search values in a dataset. If KeyFields lists a single field, KeyValues specifies the value for that field on the desired record. To specify multiple search values, pass a variant array as KeyValues, or construct a variant array on the fly using the ibec_Array function.

Examples

    ibec_ds_Locate('Company;Contact;Phone', ibec_Array('Sight Diver', 'P', '408-431-1000'), __loPartialKey);

or

    Keys[0] = 'Sight Diver';
    Keys[1] = 'P';
    Keys[2] = '408-431-1000';
    ibec_ds_Locate('Company;Contact;Phone', Keys, __loPartialKey);

Options is a set of flags that optionally specifies additional search latitude when searching on string fields. If Options contains the __loCaseInsensitive flag, then ibec_ds_Locate ignores case when matching fields. If Options contains the __loPartialKey flag, then ibec_ds_Locate allows partial-string matching on strings in KeyValues. If Options is 0 or NULL or if the KeyFields property does not include any string fields, Options is ignored.

This function returns True if a record is found that matches the specified criteria and the cursor repositioned to that record. Otherwise it returns False.

Example

    execute ibeblock
    returns (FieldName varchar(100))
    as
    begin
      select * from rdb$relation_fields
      as dataset ds;
      try
        ibec_ds_Sort(ds, 'RDB$RELATION_NAME, RDB$FIELD_POSITION');
        res = ibec_ds_Locate(ds, 'RDB$RELATION_NAME', 'RDB$FIELDS', __loPartialKey);
        while (res) do
        begin
          FieldName = ibec_ds_GetField(ds, 'RDB$FIELD_NAME');
          FieldName = ibec_Trim(FieldName);
          suspend;
          ibec_ds_Next(ds);
          res = not ibec_ds_EOF(ds);
          if (res) then
          begin
            RelName = ibec_Trim(ibec_ds_GetField(ds, 'RDB$RELATION_NAME'));
            res = RelName = 'RDB$FIELDS';
          end;
        end;
      finally
        ibec_ds_Close(ds);
      end;
    end

See also:
ibec_ds_Sort

back to top of page
<< ibec_ds_LoadFromFile | IBEBlock | ibec_ds_Next >>