Using Datastores (PB 5.x and later)
A datastore is a nonvisual DataWindow control. It acts like a datawindow control in that a datawindow object can be associated with it and a result set can be retrieved into it then manipulated, printed, shared with other datastores or datawindows, etc. For a complete list of properties, events and functions associated with datastores, refer to the PowerBuilder Objects and Controls manual which is a part of the PowerBuilder extended documentation set (the list of properties and events will also be listed without complete descriptions at the end of this document).
To use a datastore at the most simplistic level, declare a variable of type "datastore" and then create the datastore object using the "Create" statement. After creating the datastore you can associate a pre-defined datawindow object with it by specifying a value for its dataobject property.
1. Declare an instance variable of type datastore:
2. Script the creation of the datastore and the retrieval of data into it:
ids_mydatastore = Create datastore
ids_mydatastore.dataobject = "d_customer"
The result set can be printed or shared with other datawindow controls, exactly as you would manipulate a visual datawindow control:
The sample PowerBuilder application contains some excellent examples of using datastores.
Remember to destroy the datastore, using the Destroy statement, when finished with it to avoid memory leaks and/or potential gpfs, in the application.
The obvious limitation with the above approach is that there is no way to extend the functionality of the datastore through the use of scripted events as you could with a datawindow control. A quick look at the PB Objects and Controls manual shows us that the DataStore object has many of the same events as a DataWindow control - how does one take advantage of them?
In order to script a datastore's events, it is necessary to create a datastore user object in the User Object Painter. *Open the User Object Painter and create a Standard Class User Object of type "datastore". Script datastore events by right-mouse clicking in the User Object Painter workspace and selecting "script" to open the Script Painter. After saving the datastore user object it is possible to create an instance of it for use in an application exactly as you would create an instance of any other non-visual user object.
*To create a datastore user object in PowerBuilder 7.x and later, select menu option File -> New or click on the NEW icon. Select Object tab and Standard Class User Object. To script datastore events, select menu choice View ->Script.
1. Create a Standard Class user object of type "datastore" called nvo_ds and write code for its events as required
2. Declare an instance variable of type "nvo_ds":
3. Create an instance of the datastore, associate a datawindow
object with it and retrieve data into it:
invo_mydatastore = Create nvo_ds
invo_mydatastore.dataobject = "d_customer"
The critical difference between this example and the first one is that you have now implemented the extended functionality coded into the user object called nvo_ds. An example of such functionality could be the coding of the DBError event which occurs when a database error occurs in the datastore (while Updating for example) to trap the error which has occurred and react appropiately, or the coding of the ItemChanged event which occurs when the AcceptText and Update functions are called for the datastore (note that this is different behavior from the datawindow control whose ItemChanged event occurs when a field in the datawindow which has been modified loses focus).
*Tip for PFC users: if you are using PowerBuilder's Foundation Class Library and are using datastores inherited from n_ds please note that the DBError event has not been coded. It has been coded for the PFC object u_dw which is the ancestor object for PFC datawindow controls. Use the code from u_dw's DBError event as a model for the DBError event in n_ds.
Property Name Data Type Description
DataObject String Name of the datawindow object associated
with the datastore
ClassDefinition PowerObject An object of type PowerObject
containing information about the class definition of the
object or control
Object DWObject References an individual object within the
datawindow such as columns or text objects
Constructor Immediately before the window's Open event
DBError When a database error occurs in the datastore
Destructor Immediately after the window's Close event
Error When an error is found in a data or property expression for the dw
ItemChanged When the AcceptText and Update functions are called
ItemError When an item imported pass a column's validation rules
PrintEnd When the printing of the datastore ends
PrintPage Before each page of the datastore is formatted for printing
PrintStart When the printing of the datastore starts
RetrieveEnd When the retrieval into the datastore is complete
RetrieveRow After a row has been retrieved
RetrieveStart When the retrieval is about to start
SQLPreview After a Retrieve, Update or ReseletRow function call and
immediately before the SQL statement is submitted
UpdateEnd When updates to the database are complete
UpdateStart After an Update function call and before changes are sent to the
DataStore Functions (see PowerBuilder Help, Objects and Controls manual or the PB Powerscript Reference for descriptions)