Extended Frame Information

Extended Frame Information
Extended Frame Information

The result of the Thunderbolt API function ddlRelate() is a hierarchy of records from the subject tables. For example, with ArgString

      A CUSTOMERS (SALES thru CUST# (INVENTORY thru ITEM#)) over CUST#

the hierarchy may look like this:

    Rec TableName          LastName     Cust#  Description  Item#
    --- ----------------   ------------ ------ ------------ ------
       3 CUSTOMERS         Smith        A00173
     609    SALES                       A00173              I20981
      20       INVENTORY                       Boat         I20981
     610    SALES                       A00173              I00798
      22       INVENTORY                       Car          I00798
     611    SALES                       A00173              I00161
      21       INVENTORY                       Trailer      I00161
       1 CUSTOMERS         Jones        A05072
       1    SALES                       A05072              I01001
       1       INVENTORY                       Airplane     I01001
       6    SALES                       A05072              I00029
      19       INVENTORY                       Luggage      I00029
      10    SALES                       A05072              I01280
       3       INVENTORY                       Camera       I01280
     553    SALES                       A05072              I00798
      22       INVENTORY                       Kayak        I00798
     639    SALES                       A05072              I01001
      22       INVENTORY                       Airplane     I01001

We assign a numeric hierarchy level, beginning at 1, to each level of the hierarchy. In the example above, the hierarchy and the hierarchy level are defined as:

      CUSTOMERS      1   [highest]
      SALES          2
      INVENTORY      3   [lowest]

[Unfortunately, this is a bit confusing when we discuss relative hierarchy levels. When we speak of the hierarchy itself, the first member is deemed the highest; and the last member is deemed the lowest. But in terms of the numeric hierarchy level, the first (highest) is 1; and the last (lowest) is N (in this case 3).]

There are three characteristics of a hierarchy to note:
1) At the higher levels of the hierarchy (in this case CUSTOMERS), the record occurs only when a new value occurs;
2) At the lower levels of the hierarchy, (in this case SALES and INVENTORY), the record occurs even if it is repeated;
3) In the general case, one or more levels may be missing;

It is common for an application to flatten this hierarchy into a set of virtual records.

    LastName     Cust#  Description  Item#
    ------------ ------ ------------ ------
    Smith        A00173 Boat         I20981
    Smith        A00173 Car          I00798
    Smith        A00173 Trailer      I00161
    Jones        A05072 Airplane     I01001
    Jones        A05072 Luggage      I00029
    Jones        A05072 Camera       I01280
    Jones        A05072 Kayak        I00798
    Jones        A05072 Airplane     I01001

The simplistic algorithm for this process is to read records from the result file as long as the hierarchy level is increasing; that is, as long as the hierarchy level of the impending record [let us call it iNextLevel] is greater than the hierarchy level of the current record [let us call it iCurrentLevel]. Each iteration of this process produces one virtual record.

The other part of this algorithm is that when the hieratchy level stops increasing, and before we begin constructing a new virtual record, we must clear the lower levels of the hierarchy; while retaining the higher levels; that is, clear iLevel >= iNextLevel.

The information required to perform this process [i.e., iNextLevel] is obtained from the Thunderbolt API function ddlLookRec().

With the added capability of Right Outer Joins to the ddlRelate() command, the algorithm for processing a hierarchy becomes a bit more complicated. In particular, the occurence of incomplete hierarchies means that we can no longer assume that a hierarchy boundary is delimited strictly by non-increasing hierarchy levels. For example, in the following fragment, the last two records are the result of a Right Outer Join; it is not a part of the previous CUSTOMERS hierarchy.

    Rec TableName          LastName     Cust#  Description  Item#
    --- ----------------   ------------ ------ ------------ ------
       3 CUSTOMERS         Smith        A00173
     609    SALES                       A00173              I20981
      20       INVENTORY                       Boat         I20981
     610    SALES                       A00173              I00798
      22       INVENTORY                       Car          I00798
     611    SALES                       A00173              I00161
      21       INVENTORY                       Trailer      I00161
       1 CUSTOMERS         Jones        A05072
       1    SALES                       A05072              I01001
       1       INVENTORY                       Airplane     I01001
       6    SALES                       A05072              I00029
      19       INVENTORY                       Luggage      I00029
      10    SALES                       A05072              I01280
       3       INVENTORY                       Camera       I01280
     553    SALES                       A05072              I00798
      22       INVENTORY                       Kayak        I00798
     639    SALES                       A05072              I01001
      22       INVENTORY                       Airplane     I01001
      32    SALES                       AX9012              I00029
      19       INVENTORY                       Luggage      I00029

For this reason, beginning with Thunderbolt API Version 8.0.40, additional hierarchy information is returned by the ddlLookRec() function in the 32 bit integer response cell ctl->Ans3. Actually, four items of information are return in the 32 bit integer. The information is decoded by using symbolic constants that are included in the Thunderbolt API header files ddl_incl.h/ddl_defs.h.

The definitions of the symbolic constants and the values associated with them are:

ddlLookRecFlFrameInfo = 0x00010000	The presence of this bit indicates the presence of the extended information. The absence of this bit indicates that the TB API version is prior to 8.0.40; or that the hierarchy was created by a means other than ddlRelate() [e.g., a global ddlSort()].
ddlLookRecFlFrameStart = 0x00020000	The presence of this bit indicates that the impending record is the first record of a frame.
ddlLookRecFlFrameEnd = 0x00040000	The presence of this bit indicates that the impending record is the last record of a frame.
ddlLookRecFlMask = 0x0000FFFF	The value (ctl->Ans3 & ddlLookRecFlMask) produces a 16 bit integer that has meaning only if the ddlLookRecFlFrameStart bit is present. This value is the level of the highest valid hierarchy level. It can be used to determine how many hierarchy levels to discard when starting a new frame.

These values can be viewed with the /H option of the ddlRpr() API function.