ddlMatchEx() - isolate additional records into collection

ddlMatchEx() - isolate additional records into collection ddlMatchEx() - isolate additional records into collection

Prototype:

   void ddlMatchEx(
      CONTROL *ctl,
      char *OptnStr,
      char *ArgList);

Permitted values in OptnStr:

   /N - force non-keyed query

Form of ArgList:

<cx> [FROM] <SourceTable> [THRU] <SourceField-1> <SourceField-2> ...[WITH] <TargetTable> [[ON] <TargetField-1> <TargetField-2> ...]

Description:

The ddlMatchEx() API function is, in effect, a batch FIND on all values of <cx> <SourceTable> <SourceField>. The target of the FINDs is <TargetTable> <TargetField>; if <TargetField> is not specified, is is assumed to be the same as <SourceField>.

MATCH does not clear the target collection, <cx> <TargetTable>. Thus, it is necessary to perform an explicit CLEAR on the target collection unless it is specifically necessary to retain its contents. [An example of the later case is a scenario where the <TargetTable> is identical to the <SourceTable>.]

The TargetField can be either a keyed or non-keyed field in the TargetTable. However, in almost all cases, the performance of the keyed MATCH is superior to that of the non-keyed MATCH.

The /N option will force a non-key MATCH, even though the TargetField is a key.

The purpose of the ON clause is to allow TargetField to be different from SourceField. However, TargetField and SourceField must be the same data type and size; or their respective data types must be contained in the list of permitted cross data types.

Notes:

1) The default behavior of MATCH contains two distinct steps. The first step reads all records of the source collection and creates a list of unique values. The second step performs a query on each of the resulting values.

The purpose of the first step is to eliminate searches of duplicate values in the second step. However, if it is known that the values in the source collection have few or no duplicates, the first step can be skipped by using the /R option.

If SourceField is a Primary Key in SourceTable, the /R option is automatically invoked. The /T option will override this behavior and cause the first step to be performed unconditionally.

2) There is a difference between Control.Ans1 and Control.Ans2 if some of the additional records isolated were already present in the collection. In particular, if all of the additional records isolated were already there before the MATCH, then Control.Ans1 will be zero, but that does not mean that the MATCH didn't find anything; it just means that it didn't add anything that wasn't already there.

Values returned in Control Structure:

Control.Ans1	Total number of records added to the collection
Control.Ans2	Total number of records in the target collection

MATCH Examples