ddlRelate() - arrange hierarchical data

ddlRelate() - arrange hierarchical data

Prototype:

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

Permitted values in OptnStr: See Description

Form of ArgList:

<cx> <table-name-1> [<trans-1>] [<table-name-2>] [<trans-2>] ... OVER <column-name-1> [<column-name-2>] ...
[PRESENT BY [D] <pb-column-name-1> [[D] <pb-column-name-2> ...]

Description:

ddlRelate() combines the records in the specified collection and the specified tables into a hierarchical order. The hierarchy is defined by the order of the tables in ArgList.

The result of ddlRelate() is an ordered global collection. The result collection is addressed in subsequent functions by the <cx> name without a table name. The result collection persists until either:
       1) It is explicitly destroyed by ddlClear();
       2) It is implicitly destroyed by a function that re-defines the collection; for example:
             ddlFill(), ddlFind(), etc
       3) It is superceeded by another ddlRelate(), ddlRelateEx();

Values returned in Control Structure:

Control.Ans1	Number of records in final RELATed collection
Control.Ans2	Initial Number of records in unRELATed collection
Control.Ans3	Number of frames (logical records) in result