Session Overview. Session Overview. ProDataSet Definition. Climb Aboard the ProDataSet Train. Paul Guggenheim. Paul Guggenheim & Associates.

Transcription

1 Climb Aboard the ProDataSets Train Paul Guggenheim About PGA Working in Progress since 1984 and training Progress programmers since 1986 Designed seven comprehensive Progress courses covering all levels of expertise including - The Keys to OpenEdge Author of the Sharp Menu System, a database driven, GUI pull-down menu system. White Star Software Strategic Partner TailorPro Consultant and Reseller Tools4Progress Partner Major consulting clients in manufacturing, distribution, gaming, financial services, government and non-profit industries Head of the Chicago Area Progress Users Group Session Overview ProDataSets Overview Definition Uses Features ProDataSet Programming Define DataSet Statement DataSet Components Temp-Tables Data-Relations Data-Sources Eight Programming Steps Examples Session Overview Single Table Populate Dataset Single Table Fill Button Load Additional Data Multiple Tables Data Relations Multiple Tables XML Schema Write Multiple Tables XML Schema Read Multiple Tables Callback Procedures Calculated Fields Multiple Tables Reject Changes BEFORE-TABLE Multiple Tables Accept Changes SAVE-ROW-CHANGES ProDataSet Definition ProDataSet Definition What is a ProDataSet? A ProDataSetis collection of one or more temptables that optionally contain a collection of data relations among the member temp-tables. Each member temp-table can attach to a Data- Source object in order to receive data from the database or write data to the database. The term for a ProDataSetreceiving data from the database is called filling.

2 ProDataSet Definition In addition, ABL procedures may be assigned to the many ProDataSetnamed events in order to customize the behavior, perform validation, and execute different kinds of business logic. ProDataSets Uses Isolating business logic into one object. Minimizing network traffic in distributed applications. Easily read and write data to and from an XML file. Use the ABL to develop applications using the.net user interface. Provide a convenient, powerful and consistent way to separate application data access from how the underlying data is stored in the database. ProDataSet Features Define complex business logic between many levels of related data. Define a data mapping between the ProDataSet and the database. Records changes to ProDataSettemp-table records for updating the database. ProDataSet Features Associate hooks to custom event procedures. Can pass the DataSetas a single parameter with a single handle from one procedure to another, within a single Progress session or between sessions. Can be either a static or dynamic object, consistent with other objects such as temp-tables. Provides automatic rollback features for temptables independent of transactions. Simplifies populating data in related temp-tables. ProDataSet Programming DEFINE DATASET Statement: DEFINE [ NEW [ SHARED ] ] [ PRIVATE PROTECTED ] DATASET dataset-name FOR buffer-name [, buffer-name ]... [ DATA-RELATION [ data-rel-name ] data-rel-spec ]... ProDataSet Components Temp-Tables: Temp-tables must be defined before ProDataSetis defined. The ProDataSetreferences the temp-table in the ProDataSetdefinition by referring to a buffer name of the temp-table. By default, the buffer name is the temp-table name.

3 ProDataSet Components Data Relations: Data-Relations are optional, dependent components defined in the ProDataSet. Typically, Data-Relations are commonly used to define how a parent and child buffer are linked together in a ProDataSet. If only one buffer is defined for a ProDataSet, then a Data-Relation doesn t need to be defined. ProDataSet Components Data Sources: A Data-Source is an independent object that is used to transfer data between the database and a ProDataSet. Typically, there is one Data-Source defined for each defined temp-table buffer in a ProDataSet. However, the Data-Source may represent more than one database buffer (table) if there are fields in the temp-table buffer that come from different database tables. ProDataSet Components Data Sources: The Data-Source definition identifies the unique key in the database table for the Data-Source. How it maps to the temptable buffer of the ProDataSet is defined in the attach-datasource method. The Data-Source definition may specify either a query phrase or a source-buffer phrase or both. Typically, a query is defined for the top-level ProDataSet buffer. The purpose is to only read a subset of the parent records when the ProDataSet is filled. Typically, a source-buffer phrase is used for a child ProDataSetbuffer. This populates the child buffer with related records from the parent ProDataSets Eight Steps 1. Define the temp-table(s) used in the ProDataSet. 2. Define the ProDataSet. 3. Define a Database Query used in the top-level Data-Source. 4. Define the Data-Source referencing the Database Query in the top-level Data-Source. 5. Execute the QUERY-PREPAREmethod on the query associated with the top-level data source. 6. Execute the ATTACH-DATA-SOURCE method for the Data- Sources. 7. Execute the FILL method on the ProDataSet 8. Execute the DETACH-DATA-SOURCE method for the Data- Source. ProDataSets Single Table ProDataSets Single Table Here are the 8 steps for the Single Table example: Define the temp-tables used: define temp-table tstudent no-undo like student. Define the ProDataSet: define dataset dsstudent for tstudent. Define a Database Query used in the top-level Data-Source: define query qstudent for student.

4 ProDataSets Single Table Define the Data-Source referencing the Database Query in the top-level Data-Source. define data-source srcstudent for query qstudent student keys (studentid). Execute the QUERY-PREPARE method on the query associated with the top-level data source. query qstudent:query-prepare("for each student NO-LOCK where stcode = 'IL' and syear = 2007"). ProDataSets Single Table Execute the ATTACH-DATA-SOURCE method for the Data-Source. buffer tstudent:attach-data-source(datasource srcstudent:handle). Execute the FILL method on the ProDataSet dataset dsstudent:fill(). Execute the DETACH-DATA-SOURCE method for the Data-Source. buffer tstudent:detach-data-source(). Load Additional Data Load Additional Data The FILL method is executed as many times as the user desires to populate the DataSetwith a particular group of records. When the FILL method executes, Progress checks the FILL-MODE attribute for each buffer and acts according to the FILL-MODE specified. The four fill-modes are: Empty No-Fill Append Merge Load Additional Data The user may press the Fill button and select query conditions stcode(state) and syear(graduation year) for the FILL method. In addition, the user may select either EMPTY or MERGE for the FILLMODE. If EMPTY is selected, the current data in the tstudent temp-table is removed and replaced with the new records based upon the current query conditions. If MERGE mode is selected, new records are added to the existing set of records.

5 Three temp-tables are used to represent three database tables: tstudent for student tstuchrg for stuchrg(student charge) tcharge for charge(charge type) One studentrecord may have many stuchrg records, with the studentidfield being the foreign key in the stuchrg table. One charge type record may have many sturchrg records, with the chargecodefield being the foreign key in the stuchrg table. The tstudent temp-table is the top-level temptable in the dsstuchrg prodataset. Inside the dataset definition, the first data relation is for tstudentand tstuchrgand the relation fields for both records is studentid. The second data relation is for tstuchrgand tchargeand the relation fields for both records is chargecode. Specifying a data-relation name is optional. By default, Progress names these relation1and relation2. Before the DataSetcan be filled all defined Data- Sources for the ProDataSetmust be attached; otherwise a run-time error occurs. By default, the FILL method on the ProDataSet retrieves records from all Data-Sources into all temp-tables. The FILL method starts by reading the first record in the top-level query, then proceeds down through the Data-Relation relationships recursively. In this example, the tchargetemp-table will only contain charge types that occur with the tstuchrg temp-table during the FILL method. To have all tchargerecords to be included in the DataSet, yet still be directly related to the tstuchrg temp-table, then the REPOSITION keyword should be added to the charge Data-Relation. Multiple Tables XML Schema Write After filling the prodatasetin the previous example to populate the tstudent, tstuchrg and tcharge temp-tables, the WRITE-XML and WRITE-XML- SCHEMAmethods are used to dump the records and the definitions to xml files in example dsstuchrgwritexml.p. Multiple Tables XML Schema Read dataset dsstuchrg:write-xml ("file","dsstuchrg.xml",true /* formatted */). dataset dsstuchrg:write-xmlschema ("file","dsstuchrgschema.xml",true /* formatted */).

6 Multiple Tables XML Schema Read In dsstuchrgxmlread.p, a dynamic prodatasetis created and the xml-schema definitions and xml data are loaded into it. dshand:read-xml("file","dsstuchrg.xml","merge","dsstuchrgschema.xml",false). Next, each of the temp-table buffers are created by getting the buffer handle for each of the defined buffers of the ProDataSet. The data for each temp-table buffer is displayed using dynamic data methods. Multiple Tables Callback Procedures The SET-CALLBACK-PROCEDURE method associates a named event with an internal procedure to run when the event occurs, and the persistent procedure handle indicating where to run the internal procedure. Callback-name is the event for which the internal procedure executes Internal-procedure is the name of the internal procedure Procedure-context is the persistent procedure handle where the internal procedure will be executed Multiple Tables Callback Procedures The following are the Progress supplied DataSet events: BEFORE-FILL AFTER-FILL BEFORE-ROW-FILL AFTER-ROW-FILL The top two of these events may be used on both the DataSetand the DataSettemp-table buffer handle. The latter two may only be used for the DataSet temp-table buffer handle. Multiple Tables Callback Procedures Notice that total charges is now calculated. Multiple Tables Callback Procedures The following callback procedure was set: buffer tstuchrg:set-callback-procedure ("after-fill", "poststuchrgfill", THIS-PROCEDURE). PostStuchrgFill internal procedure is below: procedure poststuchrgfill: define input parameter dataset for dsstuchrg. for each tstuchrg of tstudent: accumulate chargeamt (total). end. assign chargetot = accum total chargeamt. Maintaining ProDataSet Changes Progress provides many tools that make it easy to undo individual temp-table records or the entire dataset. The following attributes and methods are used to undo changes to temptable records: Name TRACKING-CHANGES ROW-STATE BEFORE-ROWID AFTER-ROWID BEFORE-TABLE AFTER-TABLE REJECT-CHANGES Type Method End. REJECT-ROW-CHANGES Method

7 Maintaining ProDataSet Changes The before-table phrase is required for each temptable in a ProDataSetfor changes to be tracked. define temp-table tstuchrg no-undo like stuchrg before-table tstuchrgb4. The BEFORE-TABLE phrase allows the developer access to the original values in the table before the records were changed, and before the new values are accepted. The name of the after-image table is simply the name defined for the temp-table. Maintaining ProDataSet Changes Both the before-image table and the after-image table contain a field called the ROW-STATE. The ROW-STATE values are as follows: 0 ROW-UNMODIFIED 1 ROW-DELETED 2 ROW-MODIFIED 3 ROW-CREATED The above four keywords are actually functions that return the corresponding integers. Maintaining ProDataSet Changes The tracking-changes attribute for a particular temp-table must be set to yes in order for changes made to that temp-table to be tracked by Progress. Reject Changes This attribute must be set after the fill method is executed, otherwise a run-time error will occur. The user may select either the student or the student charge data to reject or both. Reject Changes In order to reject a single row of changes or all the changes for a particular temp-table, the before image table buffer must be used. find tstudentb4 where rowid(tstudentb4) = buffer tstudent:before-rowid no-error. Once the before image table buffer is acquired, the reject-changes or reject-row-changes method may be executed. buffer tstudentb4:reject-row-changes() no-error. Reject Changes To reject all changes for both temp-tables, the REJECT-CHANGESmethod may be executed on the dataset handle. The before-image table values are put back into the after-image table records. All before-image table records are cleared from each before-image table in this case. The ROW-STATE attributes in each after-image table are zeroed out and the BEFORE-ROWID attribute has be reset to?.

8 Accept and Save Changes When one of the save buttons are selected, changes are committed to the ProDataSetwith the ACCEPT-CHANGESor ACCEPT-ROW-CHANGES method. Accept and Save Changes To update changes to the database, the SAVE-ROW- CHANGESmethod must be executed. Here are the steps required: 1. Find the associated before-image table buffer to the temp-table buffer. 2. If the before-image table buffer is available, then attach the Data-Source from the temp-table to the database table. 3. Execute the SAVE-ROW-CHANGES method on the before-image table buffer. 4. Assuming no errors, execute the ACCEPT-ROW- CHANGES method on the before-image table buffer. 5. Detach the Data-Source from the temp-table to the database table. Accept and Save Changes The SAVE-ROW-CHANGESmethod has many options, giving the developer the ability to: Specify the buffer in the data-source to be updated. Specify a list of fields that should not be updated in the table if a new record is created. Specify the no-lobs keyword to ignore BLOBsand CLOBs in the save operation. Please note that there is no SAVE-CHANGES method for the entire temp-table or DataSet. Each individual record must use the SAVE-ROW- CHANGES method. The SAVE-ROW-CHANGESmethod goes through the following steps for a modified row: 1. Finds the corresponding database record exclusivelock based on its key. If the record is not available, the method retries every two seconds up to ten times, and then returns an error if the record is still not available. 2. Compares the before-image table buffer to the database buffer to see whether data has changed since it has been read. The SAVE-ROW-CHANGESmethod goes through the following steps for a modified row: 3. Buffer-copies changed fields in the corresponding after-image table buffer to the corresponding database buffer fields. This uses the same field mapping used to fill the table (as defined in the ATTACH-DATA-SOURCE method). 4. Validates the updated record to force any WRITE or ASSIGN triggers to fire. 5. Sets the ERROR logical attribute in the after-image table row as well as in its temp-table and in the DataSetif any errors resulted from the attempted update, such as duplicate unique keys. The SAVE-ROW-CHANGESmethod goes through the following steps for a modified row: 6. Repopulates the after-image table record from the database record, to catch any changes made by either event procedure code or trigger procedure code. 7. Releases the after-image table and database table records.

9 For a newly created row, SAVE-ROW-CHANGES creates the record in the database and buffer-copies all data table buffer fields except any skip-fields specified in the SAVE-ROW-CHANGES method. It then executes steps 4-7. For a delete row, SAVE-ROW-CHANGES deletes the corresponding row from the Data-Source, based on the record s keys. Even though the SAVE-ROW-CHANGES method updates the database, it does not count as a reference for automatically making a block a transaction block. Try to think of the SAVE-ROW-CHANGES method as a self-contained procedure block, where the transaction is committed at the end of the SAVE- ROW-CHANGES method statement. This means that the developer must specify the TRANSACTION keywordon the block that is desired for the transaction. Summary ProDataSetscan be used effectively to represent data in a business application. Questions ProDataSets communicate easily with XML files. ProDataSetsrepresent data in a logical way for the end-user, without the end-user having to know how the data is stored in the database. ProDataSetsgive the developer many tools that make it easy to perform transactions and to selectively undo, desired temptable records. This presentation was meant to cover only some of the ProDataSet sfeatures and characteristics. Additional information can be learned from PGA s Keys to OpenEdge Course.