Progress
ADM 2 Guide
Compatibility Checking
When you instantiate a static SmartDataBrowser or a SmartDataViewer in a Progress application, the AppBuilder must be able to check whether the fields to be browsed or displayed in the SmartObject match (are compatible with) those of the SmartDataObject to which you will link it. Depending on the SmartObject type, the AppBuilder uses either signatures or field lists to perform this check. (Compatibility checking is not required for dynamic SmartDataBrowsers.)
Signature and Field-list Checking at Design Time
The AppBuilder performs a compatibility check in the following circumstances:
- When you instantiate a SmartDataBrowser or SmartDataViewer in a SmartContainer. The AppBuilder checks all SmartDataObjects in the SmartContainer to see whether their signatures and field lists match those of the new SmartDataBrowser or SmartDataViewer, respectively. If any matches occur, the Progress Advisor asks which, if any, SmartDataObjects to link to the SmartDataBrowser or SmartDataViewer. If there are no matches, the Advisor does not appear.
- When you instantiate a SmartDataObject in a SmartContainer. The AppBuilder checks all existing SmartDataBrowsers and SmartDataViewers in the SmartContainer to see whether their signatures and field lists, respectively, match those of the new SmartDataObject. If any matches occur, the Progress Advisor asks which, if any, SmartDataBrowsers or SmartDataViewers to link to the SmartDataObject. If there are no matches, the Advisor does not appear.
- When you modify a SmartDataObject. The AppBuilder checks all objects linked to that SmartDataObject for compatibility, and the Progress Advisor notes any incompatibilities.
- When you modify a SmartDataBrowser or SmartDataViewer that is linked to a SmartDataObject. The AppBuilder checks for compatibility, and the Progress Advisor notes any incompatibilities.
You can verify the validity of the signatures of linked objects by clicking on the Check Links button in the SmartLinks window. (See the Progress AppBuilder Developer’s Guide for details.)
Checking SmartDataBrowser Compatibility
Compatibility checking is not required for dynamic SmartDataBrowsers. A dynamic SmartDataBrowser simply attaches to the query of its SmartDataObject and generates a column list at run time, thus avoiding the necessity for a compatibility check.
Compatibility checking for static SmartDataBrowsers uses signatures. As in the case of a SmartDataObject, the temp–table definition of a SmartDataBrowser gives it a unique signature that identifies the order, number, and data types of its fields. The exact use of the signature differs depending on what action is attempted and against which objects the action occurs.
In a compatibility check, the getDataSignature function for both the SmartDataObject and static SmartDataBrowser returns a character string with a representation of the object’s signature. The signature of the SmartDataObject is compared to the signature of the static SmartDataBrowser to see whether they are compatible. If so, the static SmartDataBrowser can browse the SmartDataObject’s query when the objects are linked at run time.
Checking SmartDataViewer Compatibility
The field-matching relationship of a SmartDataViewer with a SmartDataObject against which it is built is different from that of a SmartDataBrowser with a SmartDataObject. The AppBuilder uses the SmartDataViewer’s displayed field list, rather than a signature, to determine compatibility with the SmartDataObject. This displayed field list is defined by the SmartDataViewer’s displayed fields and accessed with the getDisplayedFields function. If a SmartDataViewer’s displayed fields are the same as or a subset of a SmartDataObject’s fields, the objects are considered to have a matching displayed field signature. A SmartDataViewer can successfully retrieve data from a SmartDataObject only if the SmartDataObject can provide all of the fields that the SmartDataViewer needs.
Similarly, a SmartDataViewer has an enabled field list that is defined by its enabled fields and accessed with the getEnabledFields function. If a SmartDataViewer’s enabled fields are the same as or a subset of a SmartDataObject’s updateable fields, the objects are considered to match, according to this enabled field list. A SmartDataViewer can successfully send data to a SmartDataObject only if the SmartDataObject can update all of the fields that the SmartDataViewer provides.
Example: SmartDataObject and SmartDataViewer. The SmartDataObject
dcust.w
generates the following include file:
The updateable fields in this file are the Name, Address, and City fields.
Suppose that a SmartDataViewer built against
dcust.w
enables the Name and Address fields. In this case:Now, suppose that the SmartDataViewer is built against
dcust.w
enables the Name and Postal-Code fields. In this case:Example: SmartDataObjects with Contrasting Signatures. The SmartDataObject
dcust.w
generates the following include file:
In contrast, the SmartDataObject
d-custreverse.w
generates the following include file:
In this example:
- A SmartDataBrowser built against the
dcust.w
SmartDataObject will not match thed-custreverse.w
SmartDataObject. This is because the temp–table signature is used to determine compatibility and the order of the fields is different.- A SmartDataViewer built against the
dcust.w
SmartDataObject will match thed-custreverse.w
SmartDataObject. This is because the displayed field list is used to determine compatibility and the order of the fields does not matter, only their names and data types.Using Data SmartLinks
Data in the form of field values is passed from one SmartObject to another using a Data SmartLink. A SmartDataObject can be a Data–Source for another object. It can also be a Data–Target, receiving a key value from another query object to use in opening a query. Visual objects such as SmartDataViewers and SmartDataBrowsers can also be Data–Targets. A SmartDataViewer as a Data–Target receives formatted column values from a SmartDataObject for display. A SmartDataBrowser as a Data–Target browses its Data–Source’s query and displays column values in its browse.
At design time, when you drop a SmartObject into an application, the AppBuilder’s Link Advisor assesses each SmartObject already in the application to determine whether it is suitable for a Data link connection with the new SmartObject and, if it is, it recommends the connection. It makes its assessment by examining the properties of each object to determine what columns it defines: a query object can be a Data–Source for another object only if it can supply one or more columns that the object could use as a key to open its own query.
In particular:
- A query object can be a Data–Source for a visual object such as a SmartDataViewer if all of the fields displayed by the SmartDataViewer are in the query object and all fields that are enabled in the SmartDataViewer are updateable in the Data–Source.
- A SmartDataBrowser can be a Data–Target only for a SmartDataObject that has the same signature.
NOTE: Because of the flexibility of SmartObject combinations and the dynamic nature of queries, the Link Advisor might suggest possible links that are not desirable for your application. Always examine Link Advisor recommendations before accepting them. One way to avoid problems is to drop Data–Sources onto the design window before Data–Targets. When two objects can be linked in either direction, the Link Advisor assumes that the first object dropped into the application should be the Data–Source.
Copyright © 2004 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095 |