Syntax

You can identify the Data-Source currently attached to a buffer using the DATA-SOURCE attribute, as shown using this syntax:

buffer-handle:DATA-SOURCE

The GET-DATASET-BUFFER attribute on the Data-Source handle returns the buffer handle for the Data-Source's associated ProDataSet buffer. This is the syntax for the GET-DATASET-BUFFER attribute:

buffer-handle = data-source-handle:GET-DATASET-BUFFER.

The DATA-SOURCE-COMPLETE-MAP attribute returns a comma-separated 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. This list is formatted as a comma-separated list of field name pairs, qualified with the ProDataSet and Data-Source temp-table names, using the following syntax:

tt-buffer-name.tt-field-name,db-table-name.db-field-name[, ...]

If the ProDataSet temp-table buffer does not have an attached Data-Source object, this attribute returns the Unknown value (?).

You can get the source buffers from a Data-Source with the NUM-SOURCE-BUFFERS attribute and the GET-SOURCE-BUFFER method, as shown in the following syntax:

data-source-handle:NUM-SOURCE-BUFFERS
data-source-handle:GET-SOURCE-BUFFER [ (buffer-index) ]

Because a Data-Source most often has only one source buffer, the buffer-index argument is optional and defaults to 1.

You can get a comma-separated list of key fields defined in an associated KEYS clause for the specified buffer by using the KEYS attribute, as shown in the following syntax:

data-source-handle:KEYS( buffer-sequence-number )

If there are no defined key fields, this attribute returns a comma-separated list of key fields in the buffer's unique primary index (if any). If there are no defined key fields and no unique primary index, this attribute returns the string "ROWID".

You can retrieve the ROWID of the data source row at which the next FILL operation should start with the NEXT-ROWID attribute, as shown in the following syntax:

data-source-handle:NEXT-ROWID( buffer-sequence-number | buffer-name )

The AVM sets this attribute after each FILL operation in a series of FILL operations to retrieve data source rows in batches. You typically assign the value of this attribute to the RESTART-ROWID attribute before each FILL operation.

Note: This attribute is not marshalled between the client and the application server. You are responsible for retrieving, storing, and transporting this attribute value between the client and the application server.

You can retrieve the ROWID of the data source row at which a FILL operation will start with the RESTART-ROWID attribute. Set this attribute before each FILL operation in a series of FILL operations to retrieve data source rows in batches, as shown in the following syntax:

data-source-handle:RESTART-ROWID( buffer-sequence-number | buffer-name )

To position the FILL query to an absolute row number, use the RESTART-ROW attribute of the Data-Source object handle, as shown in the following syntax:

data-source-handle:RESTART-ROW

Similar to RESTART-ROWID, this attribute facilitates batching during a FILL on a ProDataSet temp-table. For example, setting this attribute is helpful when you are paging back and forth in a table and want to retrieve page 3. In this case you would set RESTART-ROW to (3-1) * BATCH-SIZE to fill the third group of records.

You can retrieve the current where-clause for a buffer's query, whether it has been set explicitly or derived automatically from the fields in its relation, using the FILL-WHERE-STRING attribute, as shown in the following syntax:

data-source-handle:FILL-WHERE-STRING
You might want to use the string to help you construct a query of your own to retrieve records that might require more filtering than the relation provides by default. The default is the Unknown value (?).
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 using the QUERY attribute.

As with other objects, you can get a handle to a static Data-Source. Precede the Data-Source name with the keyword DATA-SOURCE, as shown in the following syntax:

[ handle-var = ] DATA-SOURCE data-source-name:HANDLE

This block of code added to DynamicDataSet2.p retrieves the Data-Source for each of the ProDataSet's buffers and displays its database source buffer's name and the where-clause that the AVM generates automatically for the table based on the relation:

DO iEntry = 1 TO phDataSet:NUM-BUFFERS:
  hBuffer = phDataSet:GET-BUFFER-HANDLE(iEntry).
  MESSAGE "Data-Source: "
    hBuffer:DATA-SOURCE:GET-SOURCE-BUFFER:NAME SKIP
    "WHERE-STRING:" hBuffer:DATA-SOURCE:FILL-WHERE-STRING
    VIEW-AS ALERT-BOX.
  DELETE OBJECT hBuffer:DATA-SOURCE.
END.

The output for these MESSAGE statements follow:



The first database table for the ProDataSet is the Customer table. There is no default where-clause for it because it is the top-level table and has no parent. Even though you have defined a where-clause for this top-level table in the DynamicDataSet procedure, that is not assigned to the FILL-WHERE-STRING attribute. This attribute shows only the default selection the AVM generates for you:



The second Data-Source is the Order table. It does have a FILL-WHERE-STRING because it is the child of a relation. If you compare its FILL-WHERE-STRING attribute with the WHERE-STRING of its Data-Relation, you can see the difference between the job the Data-Source has to do during a FILL and the job the relation does after the FILL is complete and you are navigating the ProDataSet.

This FILL-WHERE-STRING retrieves Order records from the Order database table by matching the CustNum of the ttCustomer temp-table record that has just been retrieved from the database Customer table and created in the ProDataSet's temp-table.

The relation's WHERE-STRING compares the ttCustomer temp-table with the records already in the ttOrder temp-table, because it is used to navigate the filled ProDataSet:



Finally, you see the Data-Source for the SalesRep table. It also has no FILL-WHERE-STRING because it is not involved in a relation at all.

Standard object attributes that are valid for the Data-Source and accessible through its handle include:

  • ADM-DATA
  • FILL-WHERE-STRING
  • HANDLE
  • INSTANTIATING-PROCEDURE
  • KEYS
  • MERGE-BY-FIELD
  • NAME
  • NEXT-ROWID
  • NEXT-SIBLING
  • NUM-SOURCE-BUFFERS
  • PREFER-DATASET
  • PRIVATE-DATA
  • QUERY
  • RESTART-ROW
  • RESTART-ROWID
  • SAVE-WHERE-STRING
  • TYPE