DataStore object – PB Docs 150

DataStore object

A DataStore is a nonvisual DataWindow control. DataStores
act just like DataWindow controls except that many of the visual
properties associated with DataWindow controls do not apply to DataStores.
Because you can print DataStores, PowerBuilder provides some events
and functions for DataStores that pertain to the visual presentation
of the data.

However, graph functions such as CategoryCount, CategoryName, GetData, SeriesCount,
and so forth depend on the visual graph control, which is not created
for a DataStore object. These functions return an error value or
an empty string when used with DataStores.

Properties

DataStore property

Datatype

Description

DataObject

String

Specifies the name of the DataWindow
or Report object associated with the control.

ClassDefinition

PowerObject

An object of type PowerObject containing
information about the class definition of the object or control.

Object

DWObject

Used for the direct manipulation of objects
within a DataWindow object from a script. These objects can be,
for example, columns or text objects.

Events

Some but not all DataStore events have return codes that you
can use to determine what action will be taken after the event occurs.
You set the return codes in a RETURN statement
in the event script.

DataStore event

Occurs

Constructor

Immediately before the Open event occurs
in the window.

DBError

When a database error occurs in the DataStore.

Return codes:

  • 0 – (Default)
    Display the error message.

  • 1 – Do not display the error message.

Destructor

Immediately after the Close event occurs
in the window.

Error

When an error is found in a data or property
expression for a DataWindow object.

ItemChanged

When the AcceptText and Update functions
are called for the DataStore.

Return codes:

  • 0 – (Default)
    Accept the data value.

  • 1 – Reject the data value and do not allow focus
    to change.

  • 2 – Reject the data value but allow focus to change.

ItemError

When a value imported into a DataStore
from a string or file does not pass the validation rules for its
column. Can also occur when the AcceptText and Update functions
are called for the DataStore.

Return codes:

  • 0 – (Default)
    Reject the data value and show an error message box.

  • 1 – Reject the data value with no message box.

  • 2 – Accept the data value.

  • 3 – Reject the data value but allow focus to change.

If the return code is 0 or 1 (rejects the data), the field
with the incorrect data regains the focus.

Printend

When the printing of the DataStore ends.

PrintPage

Before each page of the DataStore is
formatted for printing.

Return codes:

  • 0 – Do
    not skip a page.

  • 1 – Skip a page.

PrintStart

When the printing of the DataStore starts.

RetrieveEnd

When the retrieval for the DataStore
is complete.

RetrieveRow

After a row has been retrieved.

Return codes:

  • 0 – (Default)
    Continue.

  • 1 – Stop the retrieval.

RetrieveStart

When the retrieval for the DataStore
is about to begin.

Return codes:

  • 0 – (Default)
    Continue.

  • 1 – Do not perform the retrieval.

  • 2 – Do not reset the rows and buffers before retrieving
    the data from the database.

SQLPreview

After a Retrieve, Update,
or ReselectRow function call and immediately
before the SQL statement is
submitted to the DBMS.

The following return codes specify the action that takes place
when the event occurs after an Update function
call only:

  • 0 – (Default) Continue.

  • 1 – Stop.

  • 2 – Skip this request and execute the next request.

UpdateEnd

When all the updates from the DataStore
to the database are complete.

UpdateStart

After an Update function
call and just before changes in the DataStore are sent to the database.

Return codes:

  • 0 – (Default)
    Continue.

  • 1 – Do not perform the update.

Functions

DataStore function

Datatype returned

Description

AcceptText

Integer

Applies the contents of the DataStore’s
edit control to the current item in the DataStore buffer.

CategoryCount

Integer

Returns the number of categories in the
specified graph. (Returns an error value or an empty string for
DataStores.)

CategoryName

String

Returns the name of the specified category
in the specified graph. (Returns an error value or an empty string
for DataStores.)

ClassName

String

Returns the name assigned to the DataStore.

ClearValues

Integer

Deletes all items from the value list
associated with the specified column in the DataStore.

Clipboard

Integer

Copies the specified graph in the DataStore
to the clipboard.

CopyRTF

String

Returns the selected text, pictures,
and input fields in a DataStore as a string with rich text formatting.
Bitmaps and input fields are included in the string.

Create

Integer

Creates a DataWindow object using the
specified source code and replaces the DataWindow object in the
specified DataStore with the new DataWindow object.

CreateFrom

Integer

Creates a DataStore object from the passed
ResultSet object.

DataCount

Long

Returns the number of data points in
the specified series in the specified graph. (Returns an error value
or an empty string for DataStores.)

DBCancel

Integer

Cancels a database retrieval in progress.

DeletedCount

Long

Returns the number of rows that have
been deleted from the DataStore but have not yet been updated in
the associated database table.

DeleteRow

Integer

Deletes the specified row from the DataStore.

Describe

String

Returns requested information about the
structure of the DataStore.

Filter

Integer

Moves rows that do not meet the current
filter criteria to the filter buffer.

FilteredCount

Integer

Returns the number of rows that do not
meet the current filter criteria.

Find

Long

Returns the number of the first row that
meets the search criteria within a specified search range in the
detail area of a DataStore.

FindCategory

Integer

Returns the number of the specified category
in the specified graph. (Returns an error value or an empty string
for DataStores.)

FindGroupChange

Long

Searches starting at a specified row
for the first break for the specified group in the DataStore.

FindRequired

Integer

Identifies the required columns that
the user has not filled.

FindSeries

Integer

Returns the number of the specified series
in the specified graph. (Returns an error value or an empty string
for DataStores.)

GenerateHTMLForm

Integer

Creates an HTML Form element containing
columns for one or more rows. Also returns an HTML Style element
containing style sheet information.

GenerateResultSet

Long

Returns an EAServer result
set from a PowerBuilder user object running as a component on EAServer.

GetBorderStyle

Border (enumerated)

Returns a Border enumerated datatype
indicating the border style of the specified column in the DataStore.
Border enumerated datatypes are:

  • Box!

  • Lowered!

  • NoBorder!

  • Raised!

  • ResizeBorder!

  • ShadowBox!

  • Underline!

GetChanges

Long

Retrieves changes made to a DataStore
into a blob. This function is used primarily in distributed applications.

GetChild

Integer

Stores in the specified variable the
name of the child DataWindow in the specified column.

GetClickedColumn

Integer

Obtains the number of the column the
user clicked or double–clicked in a DataStore.

GetClickedRow

Long

Obtains the number of the row the user
clicked or double–clicked in a DataStore.

GetColumn

Integer

Returns the number of the current column
in the DataStore.

GetColumnName

String

Returns the name of the current column
in the DataStore.

GetContextService

Integer

Creates a reference to a context-specific
instance of the specified service.

GetData

Double

Returns the value of the specified data
in the specified series in the specified graph. (Returns an error
value or an empty string for DataStores.)

GetDataPieExplode

Integer

Reports the percentage that a pie slice
is exploded in a pie graph. (Returns an error value or an empty
string for DataStores.)

GetDataStyle

Integer

Finds out the appearance of a data point
in a graph. (Returns an error value or an empty string for DataStores.)

GetDataValue

Integer

Returns the value of the specified data
in the specified series in the specified graph. (Returns an error
value or an empty string for DataStores.)

GetFormat

String

Returns the format used for display in
the specified column of the DataStore.

GetFullState

Long

Retrieves the complete state of a DataStore
into a blob. This function is used primarily in distributed applications.

GetItemDate

Date

Returns the date data in the specified
row and column of the DataStore.

GetItemDateTime

DateTime

Returns the datetime data in the specified
row and column of the DataStore.

GetItemDecimal

Decimal

Returns the decimal data in the specified
row and column of the DataStore.

GetItemNumber

Double

Returns the numeric data in the specified
row and column of the DataStore.

GetItemStatus

dwItemStatus (enumerated)

Returns the status of the item at the
specified row and column location in the specified buffer. Values
are:

  • DataModified!

  • New!

  • NewModified!

  • NotModified!

GetItemString

String

Returns the string data in the specified
row and column of the DataStore.

GetItemTime

Time

Returns the time data in the specified
row and column of the DataStore.

GetNextModified

Long

Returns the number of the first row that
was modified in the specified buffer in the specified DataStore
after the specified row.

GetParent

PowerObject

Returns a reference to the name of the
parent object.

GetRow

Long

Returns an integer containing the number
of the current row in the DataStore.

GetRowFromRowId

Long

Gets the row number of a row in a DataStore
from the unique row identifier associated with that row.

GetRowIdFromRow

Long

Gets the unique row identifier of a row
in a DataStore from the row number associated with that row.

GetSelectedRow

Integer

Returns the number of the first selected
row after the specified row number in the DataStore.

GetSeriesStyle

Integer

Finds out the appearance of a series
in a graph. (Returns an error value or an empty string for DataStores.)

GetSQLSelect

String

Returns the current SELECT statement
for the DataStore.

GetStateStatus

Long

Retrieves the current status of the internal
state flags for a DataWindow and places this information in a blob.
This function is used primarily in distributed applications.

GetText

String

Returns the text in the edit control
over the current row and column of the DataStore.

GetTrans

Integer

Returns the values in the DataStore Transaction
object.

GetValidate

String

Returns the validation rule used in the
specified column of the DataStore.

GetValue

String

Returns the specified item in the value
list for the specified column.

GroupCalc

Integer

Recalculates the breaks in the groups
in the DataStore.

ImportClipboard

Long

Copies data from the clipboard to the
DataStore.

ImportFile

Long

Copies data from a file to the DataStore.

ImportString

Long

Copies data from a string to the DataStore.

InsertDocument

Integer

Inserts a rich text format or plain text
file into a DataStore. You use a function parameter to specify how
the new content is added:

  • It
    can be inserted at the insertion point

  • It can replace all existing content

This function applies only to DataStores whose content has
the RichText presentation style.

InsertRow

Long

Inserts a new initialized row before
the specified row in the DataStore.

IsSelected

Boolean

Returns true if the
specified row in the DataStore is selected; returns false if
the row is not selected or is greater than the number of rows in
the DataStore.

ModifiedCount

Long

Returns the number of rows that have
been modified in the DataStore but have not yet been updated in
the associated database table.

Modify

String

Uses the specification contained in a
string to modify the DataStore.

PasteRTF

Long

Pastes rich text data from a string into
a DataStore whose content has the RichText presentation style.

PostEvent

Boolean

Adds an event to the end of the message
queue for the DataStore.

Print

Integer

Sends the content of the DataStore to
the current printer. This function has several syntaxes.

PrintCancel

Integer

Cancels the print job and deletes the
spool file (if any) when the content of the DataStore is sent to
print.

This function has two syntaxes. Use Syntax 1 when Syntax 1
of the Print function was used to send it to
print.

ReselectRow

Integer

Accesses the database to reselect all
columns that can be updated and refreshes all timestamp columns
in a row in the DataStore.

Reset

Integer

Clears all the data from a DataStore.

ResetDataColors

Integer

Resets the color of a data point to the
color specified for the series. (Returns an error value or an empty
string for DataStores.)

ResetTransObject

Integer

Stops the DataStore from using a programmer-defined Transaction
object (thereafter, the DataStore uses its internal Transaction
object).

ResetUpdate

Integer

Resets the update flags for the DataStore.

Retrieve

Long

Causes the DataStore to retrieve rows
from the database.

RowCount

Long

Returns the number of rows currently
available in the DataStore (all the rows retrieved minus any deleted
rows plus any inserted rows minus any rows that have been filtered
out).

RowsCopy

Integer

Copies a range of rows from one DataStore
to another DataStore (or DataWindow control) or from one buffer
to another within a single DataStore.

RowsDiscard

Integer

Discards a range of rows. The rows cannot
be restored unless retrieved from the database.

RowsMove

Integer

Clears a range of rows from a DataStore
and inserts the rows in another DataStore (or DataWindow control)
or another buffer of the same DataStore.

SaveAs

Integer

Saves the content of the DataStore to
the specified file, in the specified format, with or without column
headings at the beginning

SaveAsAscii

Long

Saves the content of a DataStore into
a standard ASCII text file.

SelectRow

Integer

Selects or deselects the specified row
of the DataStore.

SeriesCount

Integer

Returns the number of series in the specified
graph. (Returns an error value or an empty string for DataStores.)

SeriesName

String

Returns the name of the specified series
in the specified graph. (Returns an error value or an empty string
for DataStores.)

SetBorderStyle

Integer

Sets the border style of the specified
column in the DataStore.

SetChanges

Long

Applies changes captured with GetChanges to
a DataStore. This function is used primarily in distributed applications.

SetColumn

Integer

Makes the specified column the current
column in the DataStore.

SetDataPieExplode

Integer

Explodes a pie slice in a pie graph.
(Returns an error value or an empty string for DataStores.)

SetDataStyle

Integer

For the specified data point in the specified
series in the specified graph. (Returns an error value or an empty
string for DataStores.)

SetDetailHeight

Integer

Sets the height of each row in a specified
range.

SetFilter

Integer

Defines the filter criteria for the DataStore.
The actual filtering is performed by the Filter function.

SetFormat

Integer

Sets the display format for the specified
column of the DataStore.

SetFullState

Long

Applies the contents of a DataWindow
blob retrieved by GetFullState to a DataStore.
This function is used primarily in distributed applications.

SetHTMLAction

Integer

Accepts action and context information
about user interaction with the Web DataWindow client control in
a Web browser so that newly generated HTML can reflect any requested
changes.

SetItem

Integer

Sets the value of the specified row and
column of the specified DataStore.

SetItemStatus

Integer

Sets the status of a row in a specified
column of the DataStore in the specified buffer.

SetPosition

Integer

Moves an object within the DataStore
to another band or changes the front-to-back order of objects within
a band.

SetRow

Integer

Makes the specified row the current row
in the DataStore.

SetSeriesStyle

Integer

For the specified series in the specified
graph. (Returns an error value or an empty string for DataStores.)

SetSort

Integer

Defines the sort criteria for the DataStore.
The actual sorting is performed by the Sort function.

SetSQLPreview

Integer

Sets the current SQL statement
for the DataStore.

SetSQLSelect

Integer

Changes the current SELECT statement
for the DataStore.

SetText

Integer

Replaces the text in the edit control
at the current row and column of the DataStore with the specified
text.

SetTrans

Integer

Sets values in the DataStore’s
internal Transaction object.

SetTransObject

Integer

Sets the Transaction object for the DataStore
and provides control over the transaction, including the ability
to commit from a script.

SetValidate

Integer

Changes the validation rule used for
the specified column of the DataStore.

SetValue

Integer

Sets the value of the specified item
in the value list or the code table of the specified column of the
DataStore.

SetWSObject

Integer

Causes a DataStore (or DataWindow control)
to use a programmer–specified connection object. The connection
object provides the information necessary for communicating with
a Web service data source.

ShareData

Integer

Shares data between a primary DataStore
(or DataWindow control) and a secondary DataStore (or DataWindow
control).

ShareDataOff

Integer

Turns off sharing for the DataStore.
If the DataStore is primary, all secondary DataStores (or DataWindow
controls) are disconnected and their DataWindow objects no longer
contain data.

Sort

Integer

Sorts the rows of the DataStore based
on its current sort criteria.

TriggerEvent

Integer

Triggers a specified event in the DataStore
and executes the script for the event.

TypeOf

Object

Returns the type of the DataStore.

Update

Integer

Sends to the database all inserts, deletes,
and updates of the DataStore.


Document get from Powerbuilder help
Thank you for watching.
Was this article helpful?
Subscribe
Notify of
guest
0 Comments
Inline Feedbacks
View all comments
0
Would love your thoughts, please comment.x
()
x