About DataStores

A DataStore is a nonvisual DataWindow control. DataStores act just like DataWindow controls except that they do not have many of the visual characteristics associated with DataWindow controls. Like a DataWindow control, a DataStore has a DataWindow object associated with it.

NoteAvailability In PowerBuilder, a DataStore is a nonvisual object. The Web control for ActiveX does not support DataStores.

The Web DataWindow server component uses an instance of a custom DataStore object to hold the DataWindow definition and data. See “Using a custom DataStore object”.

When to use a DataStore

DataStores are useful when you need to access data but do not need the visual presentation of a DataWindow control. DataStores allow you to:

DataStore methods

Most of the methods and events available for DataWindows are also available for DataStores. However, some of the methods that handle online interaction with the user are not available. For example, DataStores support the Retrieve, Update, InsertRow, and DeleteRow methods, but not GetClickedRow and SetRowFocusIndicator.

Prompting for information

When you are working with DataStores, you cannot use functionality that causes a dialog box to display to prompt the user for more information. Here are some examples of ways to overcome this restriction:

SetSort and SetFilter You can use the SetSort and SetFilter methods to specify sort and filter criteria for a DataStore object, just as you would with a DataWindow control. However, when you are working with a DataWindow control, if you pass a NULL value to either SetSort or SetFilter, the DataWindow prompts the user to enter information. When you are working with a DataStore, you must supply a valid format when you call the method. Moreover, you must supply a valid format when you share data between a DataStore and a DataWindow control; you cannot pass the NULL value to the DataWindow control rather than the DataStore.

Prompt for Criteria You can define your DataWindow objects so that the user is prompted for retrieval criteria before the DataWindow retrieves data. This feature works with DataWindow controls only. It is not supported with DataStores.

SaveAs When you use the SaveAs method with a DataWindow object, you can pass an empty string for the filename argument so that the user is prompted for a file name to save to. If you are working with a DataStore, you must supply the filename argument.

Prompt for Printing For DataWindow controls, you can specify that a print setup dialog box display at execution time, either by checking the Prompt Before Printing check box on the DataWindow object’s Print Specifications property page, or by setting the DataWindow object’s Print.Prompt property in a script. This is not supported with DataStores.

Retrieval arguments If you call the Retrieve method for a DataWindow control that has a DataWindow object that expects an argument, but do not specify the argument in the method call, the DataWindow prompts the user for a retrieval argument. This behavior is not supported with DataStores.

DataStores have some visual methods

Many of the methods and events that pertain to the visual presentation of the data in a DataWindow do not apply to DataStores. However, because you can print the contents of a DataStore and also import data into a DataStore, DataStores have some visually oriented events and methods. For example, DataStores support the SetBorderStyle and SetSeriesStyle methods so that you can control the presentation of the data at print time. Similarly, DataStores support the ItemError event, because data imported from a string or file that does not pass the validation rules for a column triggers this event.

For a complete list of the methods and events for the DataStore object and information about each method, see the DataWindow Reference.

DataStores require no visual overhead

Unlike DataWindow controls, DataStores do not require any visual overhead in a window. Using a DataStore is therefore more efficient than hiding a DataWindow control in a window.