Release 10.1A: OpenEdge Development:
ProDataSets

> ## Using Data-Source attributes and methods

> You can identify the `DATA-SOURCE` currently attached to a buffer using this attribute:

> 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:

> Syntax
>     buffer-handle = datasource-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 attributes 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:

> Syntax
>     datasource-handle:NUM-SOURCE-BUFFERS
>     datasource-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:

> 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:

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

> Progress 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 AppServer. You are responsible for retrieving, storing, and transporting this attribute value between the client and the AppServer.

> 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. For example

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

> 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 read-only `FILL-WHERE-STRING` attribute, as shown:

> Syntax
>      datasource-handle:FILL-WHERE-STRING

> You cannot set this attribute, but you might want to use the string to help you construct a query of your own to retrieve records that perhaps require more filtering than the relation provides by default.

> 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:

> 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 Progress 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’s no default where-clause for it because it’s 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’s not assigned to the `FILL-WHERE-STRING` attribute. This attribute shows only the default selection Progress 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’re 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’s 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`

> - `HANDLE`

> - `INSTANTIATING-PROCEDURE`

> - `NAME`

> - `NEXT-SIBLING`

> - `PRIVATE-DATA`

> - `TYPE`

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095