Syntax

Before you can populate a ProDataSet from a database, you must define a Data-Source object for each of its member temp-table buffers. A Data-Source names either a database buffer that supplies fields for a ProDataSet temp-table or a query name, which in turn references one or more buffers as well as defines a specific set of retrieval criteria. If you simply name the buffer, then the AVM determines the query when a FILL occurs by examining the Data-Relation between the ProDataSet member buffer for the Data-Source and its parent. If it has no parent and there is no query definition, then all records from the database table are retrieved. If the Data-Source involves a join between two or more database tables, the user-written query is required to describe the relationship between the database tables.

The Data-Source is defined independently of any ProDataSet. This is the syntax for the DEFINE DATA-SOURCE statement:

DEFINE DATA-SOURCE dsource-name FOR
  [ QUERY query-name ] [ source-buffer-phrase [, source-buffer-phrase ] … ].

In this statement:

  • dsource-name is the name you are giving to the Data-Source, as you would for any other static object.
  • query-name is the name of a query you have defined separately, before the Data-Source definition.

This is the syntax for the source-buffer-phrase: 

buffer-name [ KEYS ( { field [,field ]… | ROWID } ) ].

In this phrase:

  • buffer-name is a buffer name for a database table.
  • field is a field name in that table.
  • ROWID can occur exactly once in place of a field list to use the ROWID of the database record as the key. If you do this, you must define a field in the ProDataSet temp-table to hold the value of the ROWID and map the ROWID to that field when you attach the Data-Source to the ProDataSet temp-table buffer.

Note that the QUERY phrase and the source-buffer-phrase are not mutually exclusive. If you specify a query, then the query definition itself names the buffer or buffers it uses. However, you might still want to include a source-buffer-phrase in the Data-Source definition in order to define the fields that make up the unique key the AVM should use to eliminate duplicate records when it is filling the table from the Data-Source, or to locate the database records for a temp-table record when you have updated the record.

If you specify a source-buffer-phrase without the QUERY phrase and the Data-Source is for a child of a Data-Relation, then the AVM can generate the correct query when you fill the ProDataSet to load children of each of the parent records. Otherwise, the default is to load all records from the database table. If there is no QUERY phrase, then you can have only one source-buffer-phrase if you intend to use the Data-Source to fill a ProDataSet. The AVM cannot automatically join multiple tables without a query definition.

Note that if you use the Data-Source solely to write changes back to the database using the Data-Source definition, then there is no need for a query at all.