Switch to standard view 
  Sybase logo
 
 
 



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.

Example:

1. Declare an instance variable of type datastore:

datastore ids_mydatastore

2. Script the creation of the datastore and the retrieval of data into it:

ids_mydatastore = Create datastore
ids_mydatastore.dataobject = "d_customer"
ids_mydatastore.SetTransObject(sqlca)
ids_mydatastore.Retrieve()

The result set can be printed or shared with other datawindow controls, exactly as you would manipulate a visual datawindow control:

ids_mydatastore.Print()

ids_mydatastore.ShareData(dw_cust)

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

  • nvo_ds invo_mydatastore
  • 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"
    invo_mydatastore.SetTransObject(sqlca)
    invo_mydatastore.Retrieve()

    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.

    DataStore Properties

    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

    DataStore Events

    Event Occurs
    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
    Object
    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
    Database

    DataStore Functions (see PowerBuilder Help, Objects and Controls manual or the PB Powerscript Reference for descriptions)



    Back to Top
    © Copyright 2010, Sybase Inc.