Fills a ProDataSet object, recursively, based on its defined data sources, data relations, and queries. You can fill a ProDataSet object completely by running FILL on the ProDataSet handle itself, or partially by starting at the level of one of its member Buffer objects.

Return type: LOGICAL

Applies to: ProDataSet object handle, Buffer object handle

Syntax

FILL( )

You can define a query for the data source of a ProDataSet member buffer at any level of the ProDataSet object to select the records to fill in one FILL operation. You can also use the FILL-WHERE-STRING attribute to override the WHERE clause in the query for the data source during a FILL operation.

Note: The FILL-WHERE-STRING attribute of the data source object only applies to the default data source query. It does not apply when a named query is specified for the data source using the FOR QUERY syntax of the DEFINE DATA-SOURCE statement or the QUERY attribute on the DATA-SOURCE object.

You can perform a FILL operation on a ProDataSet object or one of its member buffer objects any number of times. You might do this, for example, to load data in a ProDataSet object or buffer after you have modified a data-source object query or attached to a different data-source object.

You can specify the FILL mode to direct the FILL operation for a ProDataSet member buffer using the FILL-MODE attribute. The default FILL-MODE is MERGE. When FILL-MODE is REPLACE, the BEFORE-ROW-FILL event handler is run after the original ProDataSet row is copied into the ProDataSet buffer.

A number of built-in events fire automatically at different points during the FILL process, for example before the FILL, after a record is created in the temp-table, and so on. For more information about ProDataSet events, see the ProDataSet events.

You can recursively fill a ProDataSet with self-referencing elements, for example, bill-of-materials parent/child tables or organization chart manager/employee tables. For a static ProDataSet, use the RECURSIVE option of the data-relation object. For a dynamic ProDataSet, use the ADD-RELATION( ) method of the ProDataSet object handle where there is a recursive argument.

If successful, this method returns TRUE. Otherwise, it returns FALSE.

If the AVM encounters an error, it sets the value of the ERROR attribute to TRUE for the associated ProDataSet object handle and Temp-table object handle.

Note: When executing the method, there is no guarantee as to the contents of the buffers involved after the method finishes executing.

For more information about filling a ProDataSet object, see Use ProDataSets.

See also

ADD-RELATION( ) method, ATTACH-DATA-SOURCE( ) method, BATCH-SIZE attribute, CREATE DATASET statement, CREATE DATA-SOURCE statement, DEFINE DATASET statement, DEFINE DATA-SOURCE statement, FILL events, FILL-MODE attribute, FILL-WHERE-STRING attribute, LAST-BATCH attribute, NEXT-ROWID attribute, RECURSIVE attribute, RESTART-ROWID attribute, SET-CALLBACK-PROCEDURE( ) method