Climb Aboard the ProDataSets Trainpugchallenge.org/2012PPT/climbaboard5.pdf · PUG Challenge...

PUG Challenge Americas 2012May 6th – 9th, 2012

Westford, MA

Copyright Copyright ©© 20122012Paul Guggenheim & AssociatesPaul Guggenheim & Associates

Climb Aboard the Climb Aboard the ProDataSetProDataSet TrainTrain

Climb Aboard the

ProDataSets

Train

Paul Guggenheim

Paul Guggenheim & Associates


Westford, MA



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

� AppPro Partner

� Major consulting clients include Acument Global Technologies, Chicago Metal Rolled Products, Eastern Municipal Water District, Eaton Corporation, Interlocal Pension Fund, International Financial Data Services, JP Morgan Chase, National Safety Council, Plymouth Tube, Tower Automotive and Tyson Foods.

� Head of the Chicago Area Progress Users Group


Westford, MA



Session Overview� ProDataSets Overview

� Definition

� Uses

� Features

� ProDataSet Programming

� Define DataSet Statement

� DataSet Components

� Temp-Tables

� Data-Relations

� Data-Sources

� Eight Programming Steps


Westford, MA



Session Overview� Examples

� 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


Westford, MA



ProDataSet Definition


Westford, MA



ProDataSet Definition� What is a ProDataSet?

� A ProDataSet is collection of one or more temp-

tables 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 ProDataSet receiving data from the

database is called filling.


Westford, MA



ProDataSet Definition� In addition, ABL procedures may be assigned to the

many ProDataSet named events in order to customize the behavior, perform validation, and

execute different kinds of business logic.


Westford, MA



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 OE

GUI for .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.


Westford, MA



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 ProDataSet temp-table records

for updating the database.

� Provides automatic rollback features for temp-tables independent of transactions.

� Simplifies populating data in related temp-tables.


Westford, MA



ProDataSet Features� Associate hooks to custom event procedures.

� Can pass the DataSet as 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.


Westford, MA



ProDataSet ProgrammingDEFINE DATASET Statement:

DEFINE [ NEW [ SHARED ] ] [ PRIVATE | PROTECTED ] DATASET dataset-name

FOR buffer-name [ , buffer-name ] ...

[ DATA-RELATION [ data-rel-name ] data-rel-spec ] ...


Westford, MA



ProDataSet ComponentsTemp-Tables:

� Temp-tables must be defined before ProDataSet is defined.

� The ProDataSet references the temp-table in the

ProDataSet definition by referring to a buffer name

of the temp-table.

� By default, the buffer name is the temp-table name.


Westford, MA



ProDataSet ComponentsData 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.


Westford, MA



ProDataSet ComponentsData 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.


Westford, MA



ProDataSet ComponentsData Sources:

� The Data-Source definition identifies the unique key in the

database table for the Data-Source. How it maps to the temp-

table buffer of the ProDataSet is defined in the ATTACH-

DATA-SOURCE 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.

� In most cases, only a source-buffer phrase is used for a

child ProDataSet buffer. This populates the child buffer

with related records from the parent


Westford, MA



ProDataSets Eight Steps1. 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 ATTACH-DATA-SOURCE method for the Data-Sources.

6. Execute the QUERY-PREPARE method on the query associated with the top-level data source.

7. Execute the FILL method on the ProDataSet

8. Execute the DETACH-DATA-SOURCE method for the Data-Source.


Westford, MA



ProDataSets Single Table


Westford, MA



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.


Westford, MA



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 ATTACH-DATA-SOURCE method for

the Data-Source.

buffer tstudent:attach-data-source(data-source srcstudent:handle).


Westford, MA



ProDataSets Single Table� 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").

� 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().


Westford, MA



Load Additional Data


Westford, MA



Load Additional Data� The FILL method is executed as many times as the

user desires to populate the DataSet with 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


Westford, MA



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.


Westford, MA



Multiple Tables - Data Relations


Westford, MA




� Three temp-tables are used to represent three

database tables:

� tstudent for student

� tstuchrg for stuchrg (student charge)

� tcharge for charge (charge type)

� One student record may have many stuchrgrecords, with the studentid field being the foreign

key in the stuchrg table.

� One charge type record may have many sturchrg

records, with the chargecode field being the foreign key in the stuchrg table.


Westford, MA




� The tstudent temp-table is the top-level temp-

table in the dsstuchrg prodataset.

� Inside the dataset definition, the first data relation

is for tstudent and tstuchrg and the relation fields for both records is studentid.

� The second data relation is for tstuchrg and tcharge and the relation fields for both records is

chargecode.

� Specifying a data-relation name is optional. By

default, Progress names these relation1 and relation2.


Westford, MA




� Before the DataSet can be filled all defined Data-

Sources for the ProDataSet must be attached; otherwise a run-time error occurs.

� By default, the FILL method on the ProDataSetretrieves 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.


Westford, MA




� In this example, the tcharge temp-table will only

contain charge types that occur with the tstuchrgtemp-table during the FILL method.

� To have all tcharge records 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.


Westford, MA



Multiple Tables – XML Schema Write

� After filling the prodataset in the previous example

to populate the tstudent, tstuchrg and tchargetemp-tables, the WRITE-XML and WRITE-XML-

SCHEMA methods are used to dump the records

and the definitions to xml files in example dsstuchrgwritexml.p.

dataset dsstuchrg:write-xml

("file","dsstuchrg.xml",true /* formatted */).

dataset dsstuchrg:write-xmlschema

("file","dsstuchrgschema.xml",true /* formatted */).


Westford, MA



Multiple Tables – XML Schema Read


Westford, MA



Multiple Tables – XML Schema Read

� In dsstuchrgxmlread.p, a dynamic prodataset is created and the

xml-schema definitions and xml data are loaded into it.

dshand:read-xml("file","dsstuchrg.xml","merge","dss tuchrgschema.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.


Westford, MA



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


Westford, MA




� 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 DataSet and the DataSet temp-table buffer handle. The latter two may only be used for the

DataSet temp-table buffer handle.


Westford, MA




� Notice that total charges is now calculated.


Westford, MA




� 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.

End.


Westford, MA



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

table records:

MethodREJECT-ROW-CHANGES

MethodREJECT-CHANGES

AttributeAFTER-TABLE

AttributeBEFORE-TABLE

AttributeAFTER-ROWID

AttributeBEFORE-ROWID

AttributeROW-STATE

AttributeTRACKING-CHANGES

TypeName


Westford, MA




� The before-table phrase is required for each temp-

table in a ProDataSet for 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.


Westford, MA




� 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.


Westford, MA




� 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.

� This attribute must be set AFTER the fill method is executed, otherwise a run-time error will occur.


Westford, MA



Reject Changes

� The user may select either the student or the

student charge data to reject or both.


Westford, MA



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.


Westford, MA



Reject Changes

� To reject all changes for both temp-tables, the

REJECT-CHANGES method 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 ?.


Westford, MA



Accept and Save Changes

� When one of the save buttons are selected, changes are

committed to the ProDataSet with the ACCEPT-CHANGES or

ACCEPT-ROW-CHANGES method.


Westford, MA




� To update changes to the database, the SAVE-ROW-

CHANGES method 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.


Westford, MA




� The SAVE-ROW-CHANGES method 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 BLOBs and

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.


Westford, MA



Save-Row-Changes Method� The SAVE-ROW-CHANGES method goes through

the following steps for a modified row:

1. Finds the corresponding database record exclusive-

lock 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.


Westford, MA





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

DataSet if any errors resulted from the attempted

update, such as duplicate unique keys.


Westford, MA





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.


Westford, MA



Save-Row-Changes Method� 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.


Westford, MA



Save-Row-Changes Method� 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 keyword on the block that is desired

for the transaction.


Westford, MA



Summary� ProDataSets can be used effectively to represent data in a

business application.

� ProDataSets communicate easily with XML files.

� ProDataSets represent data in a logical way for the end-user, without the end-user having to know how the data is stored in the database.

� ProDataSets give the developer many tools that make it easy to perform transactions and to selectively undo, desired temp-table records.

� This presentation was meant to cover only some of the ProDataSet’s features and characteristics. Additional information can be learned from PGA’s Keys to OpenEdgeCourse.


Westford, MA



Questions

Climb Aboard the ProDataSets Trainpugchallenge.org/2012PPT/climbaboard5.pdf · PUG Challenge...

Documents

Transcript of Climb Aboard the ProDataSets Trainpugchallenge.org/2012PPT/climbaboard5.pdf · PUG Challenge...