ATTACH-DATA-SOURCE method syntax

A major part of the reason for a distinct Data-Source object is that the ProDataSet itself needs to be defined without dependence on its Data-Sources. When the ProDataSet is passed to another session, for example, the Data-Sources do not and really cannot go along as part of its definition because they have no meaning on another session. Also, it might be necessary to associate different Data-Sources with a ProDataSet at different times. For example, a ProDataSet might want to switch from one Data-Source to another, depending on application logic, to fill from or update tables in different databases.

The AVM provides methods to attach and detach Data-Sources for the Data-Source buffers that use them. There is no static statement equivalent for these methods. For static objects, you can always obtain the handle through the object's HANDLE attribute.

The ATTACH-DATA-SOURCE method on a ProDataSet buffer handle associates a Data-Source with that ProDataSet buffer.

This the syntax for the ATTACH-DATA-SOURCE method:

[logical-var = ] buffer-handle:ATTACH-DATA-SOURCE
 (data-source-hdl [ , field-mapping [, except-fields [, include-fields ]]]).

Where:

  • logical-var is an optional variable of type LOGICAL. The ATTACH-DATA-SOURCE method returns a logical value that is true if it succeeded and false if it failed. The method could fail if any of its other parameters is found to be invalid at run time, for example, if the field-mapping names fields in the ProDataSet temp-table or the Data-Source table that do not exist. It could also fail if the buffer-handle is not part of a ProDataSet.
  • buffer-handle is the handle of a temp-table buffer in the ProDataSet.
  • data-source-hdl is the handle of a Data-Source object.
  • field-mapping is an optional character expression that evaluates to a comma-separated list of field pairs with different names in the source database buffer and the ProDataSet buffer. The list is in the form source-field, dset-field1[, source-field2, dset-field2][,…]. A field can be an array element as well as a simple scalar field reference. Be sure the list does not contain embedded spaces between names, as the AVM does not trim white space from around the elements in the list.
  • except-fields is an optional character expression that evaluates to a comma-separated list of fields that are in the ProDataSet buffer, but that are excluded from being populated with data from the Data-Source. This is useful to be able to reuse a ProDataSet in situations where not all the fields are needed and it is expensive to load them all and ship the data around.
  • include-fields is an optional character expression that evaluates to a comma-separated list of fields to copy into the buffer, as an alternative to the except-fields when it is easier to specify those to include rather than those to exclude. You can specify except-fields or include-fields, but not both. If you specify the except-fields, you can simply omit the optional include-fields argument, which otherwise must have the Unknown value (?). If you specify the include-fields argument, then the except-fields argument, which precedes it in the argument list, must have the Unknown value (?).

The fields in the Data-Source's buffers are mapped to the fields in the target buffer of the ProDataSet in the same way that fields in a source buffer are mapped to fields in a target buffer during the BUFFER-COPY method. That is, the AVM uses name matching to associate target and source fields. The except-fields are skipped if specified, or only the include-fields are copied. Otherwise, all fields with matching names are copied. The AVM uses the field-mapping to make specific assignments where the field name is different in the ProDataSet buffer. As with a BUFFER-COPY, any fields in the Data-Source whose names do not match any field in the target temp-table and which are not in the field-mapping list are simply skipped without error.

Since there is the possibility of a joined set of tables mapping to the target table, the except-fields, include-fields, and field-mapping arguments of the BUFFER-COPY method have been enhanced to take buffer name qualifiers such as Customer.CustNum.

In addition, it is legal to use a ROWID reference in the field-mapping, such as ROWID(SalesRep), ttSalesRowid. When used in this context, the ROWID function should have a source query buffer name as its argument. You do this when you want to use the ROWID of the database record as the key for the AVM to uniquely identify the record. In this case, you would also use the phrase KEYS(ROWID) in the Data-Source definition. The following example shows how to use this pattern to attach a data-source by mapping a database table ROWID to a ROWID field in a ProDataSet temp-table:
DEFINE TEMP-TABLE ttSalesRep NO-UNDO
  FIELD RepName      AS CHARACTER
  FIELD Region       AS CHARACTER
  FIELD ttSalesRowid AS ROWID.
DEFINE DATASET dsSalesRep FOR ttSalesRep.
DEFINE DATA-SOURCE srcSalesRep FOR SalesRep KEYS(ROWID).

/* Map the database ROWID to the temp-table ROWID field */
BUFFER ttSalesRep:ATTACH-DATA-SOURCE(
  DATA-SOURCE srcSalesRep:HANDLE,
  "ROWID(SalesRep),ttSalesRowid").

DATASET dsSalesRep:FILL().
BUFFER ttSalesRep:DETACH-DATA-SOURCE().

Using the ATTACHED-PAIRLIST attribute, you can get a comma-separated list of field name pairs for fields in a ProDataSet temp-table buffer that are mapped to corresponding fields in an attached Data-Source object. This list includes only the field name pairs you specified with the most recently attached Data-Source object.

This list is formatted as a comma-separated list of field name pairs using the following syntax:

source-field1,dset-field1 [,source-fieldn,dset-fieldn ] ...

If the buffer is not part of a ProDataSet object, or if the buffer does not have an attached Data-Source object, or if you did not specify a field name pair list when you attached the Data-Source object, this attribute returns the Unknown value (?).

Use the DATA-SOURCE-COMPLETE-MAP attribute to retrieve a list of field name pairs for all fields in a ProDataSet temp-table buffer that are mapped to corresponding fields in an attached Data-Source object. Here is a simple example of using the attribute:

DEFINE VARIABLE cFieldMapping      AS CHARACTER NO-UNDO.
DEFINE VARIABLE cDataBaseFieldName AS CHARACTER NO-UNDO.
DEFINE VARIABLE cLocalFieldName    AS CHARACTER NO-UNDO.
DEFINE VARIABLE httMember          AS HANDLE    NO-UNDO.
. . . 
ASSIGN
  cLocalFieldName    = "ttMember.ID"
  httMember          = DATASET dset:GET-BUFFER-HANDLE("ttMember")
  cFieldMapping      = httMember:DATA-SOURCE-COMPLETE-MAP
  cDatabaseFieldName = ENTRY(LOOKUP(cLocalFieldName, cFieldMapping) + 1, 
                           cFieldMapping).
. . .

Here are ATTACH-DATA-SOURCE methods you can use to associate database tables with each of the three temp-table buffers in the dsOrder ProDataSet:

BUFFER ttOrder:ATTACH-DATA-SOURCE(DATA-SOURCE srcOrder:HANDLE,
                                  "Customer.Name,CustName").
BUFFER ttOline:ATTACH-DATA-SOURCE(DATA-SOURCE srcOline:HANDLE).
BUFFER ttItem:ATTACH-DATA-SOURCE(DATA-SOURCE srcItem:HANDLE).

The first of these maps the Name field in the Customer table to the field CustName in the ttOrder temp-table.

This syntax detaches the Data-Source from the buffer it is currently attached to:

[ logical-var = ] buffer-handle:DETACH-DATA-SOURCE().

Generally, it is good practice to detach Data-Sources as soon as you are done using them, unless you know that the same ProDataSet instance will again be used for another FILL or UPDATE operation.