ddlMatch() - isolate additional records into collection

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

Prototype:

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

Permitted values in OptnStr:

   /N - force non-keyed query

Form of ArgList:

	<cx> [FROM] <SourceTable> [THRU] <SourceColumn> [WITH] <TargetTable> [[ON] <TargetColumn>]
	<cx> [FROM] <SourceTable> [THRU] <SourceColumn> [WITH] <TargetTable> <relation> <TargetColumn>
	<cx> [FROM] <SourceTable> [THRU] <SourceColumn> [WITH] <TargetTable> [[ON] <TargetColumn>] [REVERSE <cxReverse>]

Description:

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

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 TargetColumn can be either a keyed or non-keyed column 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 TargetColumn is a key.

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

In the second form, <relation> is one of the relational operators:
      >          [Greater Than]
      >=        [Greater Than or Equal]
      <          [Less Than]
      <=        [Less Than or Equal
      <>        [Not Equal]
      LK       [Like]
      NLK    [Not Like]
This form isolates all records in <TargetTable> such that
       <SourceTable>.<SourceColumn> <relation> <TargetTable>.<TargetColumn>

In the third form, <cxReverse> is a collection [different than <cx>] into which the backwards MATCH will be automatically created and stored.

At present, the third form is not supported for cases where the <SourceTable> is the same as the <TargetTable>.

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 third 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 third 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 SourceColumn 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