Shape Append Command

The Shape APPEND command assigns a child Recordset to the Value property of Field objects in a parent Recordset.

Syntax

"SHAPE {parent-command} [AS] table-alias

APPEND {child-command}

RELATE(parent-column TO child-column)"

Description of parts

The parts of this command are:

• parent-command, child-commandùA query command that returns a Recordset object. The command is issued to the underlying data provider, and its syntax depends on the requirements of that provider. This will typically be Structured Query Language (SQL), although ADO doesn't require any particular query language.
  
  
• parent-columnùA column in the Recordset returned by the parent-command.
  
  
• child-columnùA column in the Recordset returned by the child-command.
  
  
• table-aliasùAn alias used to refer to the Recordset returned by the parent-command.

Operation

The Client Cursor Engine will issue the parent-command to the provider, which will return a parent Recordset. Then the child-command will be issued, which will return a child Recordset.

For example, the parent-command could return a Recordset of customers for a company from a Customers database, and the child-command could return a Recordset of orders for all customers from an Orders database.

The parent and child Recordset objects must have a column in common. The columns are named in the RELATE clause, parent-column first, then child-column. The columns may have different names in their respective Recordset objects, but must refer to the same information in order to specify a meaningful relation.

For example, the Customers and Orders recordsets could have CustomerID and BuyerID fields in common.

The Client Cursor Engine internally creates a new column and literally appends it to the parent Recordset. The values of the fields in the new column are references to rows in the child recordset which satisfy the RELATE clause.

The appended column will be automatically named "chapter" and be of data type adChapter. If you wish to navigate through the child Recordset, specify the appended column in the Recordset object Fields collection and retrieve the Recordset from the Field object Value property. Assign the retrieved Recordset to an empty Recordset object, then navigate through that Recordset as you would any other.