ddlMatch() - isolate additional records into
a collection
Prototype:
void ddlMatchM(
CONTROL *ctl,
char *OptnStr,
char *ArgList);
Permitted values in OptnStr:
/B - do backwards MATCH after each MATCH step
Form of ArgList:
|
<cx> [FROM] <SourceTable> [THRU] <SourceField> [WITH] <TargetTable> [[ON] <TargetField>]
|
Description:
The ddlMatchM() 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 |
