SetItemStatus
method (DataWindows)
Description
Changes the modification status of a row or a column within a row.
The modification status determines the type of SQL statement the Update
method will generate for the row.
Applies to
|
DataWindow type |
Method applies to |
|---|---|
|
PowerBuilder |
DataWindow control, DataWindowChild object, DataStore |
Syntax
PowerBuilder
|
1 2 3 4 |
integer dwcontrol.SetItemStatus ( long row, integer column, dwbuffer dwbuffer, dwitemstatus status ) integer dwcontrol.SetItemStatus ( long row, string column, dwbuffer dwbuffer, dwitemstatus status ) |
|
Argument |
Description |
|---|---|
|
dwcontrol |
A reference to a DataWindow control, DataStore, or |
|
row |
The row location in which you want to set the |
|
column |
The column location in which you want to set the |
|
dwbuffer |
A value identifying the DataWindow buffer that For a list of valid values, see |
|
status |
A value of the dwItemStatus enumerated datatype For a list of valid values, |
Return value
Returns 1 if it succeeds and -1 if an error occurs. If any
argument’s value is null, in PowerBuilder and JavaScript the method
returns null.
Usage
How statuses are set
There are four DataWindow item statuses, two of which apply only to
rows:
|
Status |
Applies to |
|---|---|
|
New! |
Rows |
|
NewModified! |
Rows |
|
NotModified! |
Rows and columns |
|
DataModified! |
Rows and columns |
When data is retrieved
When data is retrieved into a DataWindow, all rows and columns
initially have a status of NotModified!.
After data has changed in a column in a particular row, either
because the user changed the data or the data was changed
programmatically, such as through the SetItem method, the column status
for that column changes to DataModified!. Once the status for any column
in a retrieved row changes to DataModified!, the row status also changes
to DataModified!.
When rows are inserted
When a row is inserted into a DataWindow, it initially has a row
status of New!, and all columns in that row initially have a column status
of NotModified!. After data has changed in a column in the row, either
because the user changed the data or the data was changed
programmatically, such as through the SetItem method, the column status
changes to DataModified!. Once the status for any column in the inserted
row changes to DataModified!, the row status changes to
NewModified!.
When a DataWindow column has a default value, the column’s status
does not change to DataModified! until the user makes at least one actual
change to a column in that row.
When Update is called
A row’s status flag determines what SQL command the Update method
uses to update the database. INSERT or UPDATE is called, depending upon
the following row statuses:
|
Row status |
SQL statement generated |
|---|---|
|
NewModified! |
INSERT |
|
DataModified! |
UPDATE |
A column is included in an UPDATE statement only if the following
two conditions are met:
-
The column is on the updatable column list maintained by the
DataWindow objectFor more information about setting the update characteristics of
the DataWindow object, see the section called “Controlling Updates in DataWindow objects” in Users Guide. -
The column has a column status of DataModified!
The DataWindow control includes all columns in INSERT statements
it generates. If a column has no value, the DataWindow attempts to
insert a null. This causes a database error if the database does not
allow nulls in that column.
Changing statuses using
SetItemStatus
Use SetItemStatus when you want to change the way a row will be
updated. Typically, you do this to prevent the default behavior from
taking place. For example, you might copy a row from one DataWindow to
another. After the user modifies the row, you want to issue an UPDATE
statement instead of an INSERT statement.
Changing column status
You use SetItemStatus to change the column status from DataModified!
to NotModified!, or the converse.
Change column status when you change row status
Changing the row status changes the status of all columns in that
row to NotModified!, so if the Update method is called, no SQL update is
produced. You must change the status of columns to be updated after you
change the row status.
Changing row status
Changing row status is a little more complicated. The following
table illustrates the effect of changing from one row status to
another:
|
Original |
Specified status |
|||
|---|---|---|---|---|
|
New! |
New Modified! |
Data Modified! |
Not Modified! |
|
|
New! |
– |
Yes |
Yes |
No |
|
NewModified! |
No |
– |
Yes |
New! |
|
DataModified! |
NewModified! |
Yes |
– |
Yes |
|
NotModified! |
Yes |
Yes |
Yes |
– |
In the table, Yes means the change is valid. For example, issuing
SetItemStatus on a row that has the status NotModified! to change the
status to New! does change the status to New!. No means that the change is
not valid and the status is not changed.
Issuing SetItemStatus to change a row status from NewModified! to
NotModified! actually changes the status to New!. Issuing SetItemStatus to
change a row status from DataModified! to New! actually changes the status
to NewModified!.
Changing a row’s status to NotModified! or New! causes all columns
in that row to be assigned a column status of NotModified!. Change the
column’s status to DataModified! to ensure that an update results in a SQL
UPDATE.
Changing the status of a retrieved row from NotModified! to
New!
If you change the status of a retrieved row to New! and then make
a change to data in a column, all the columns in that row change status
to DataModified! All the columns change status because the Update method
generates a SQL INSERT command that includes the changed data as well as
the data that already existed in the other columns.
Changing status indirectly
When you cannot change to the desired status directly, you can
usually do it indirectly. For example, change New! to DataModified! to
NotModified!.
Resetting status for the whole DataWindow
object
To reset the update status of the entire DataWindow object, use the
ResetUpdate method. This sets all status flags to NotModified! except for
New! status flags, which remain unchanged.
Examples
This statement sets the status of row 5 in the Salary column of the
primary buffer of dw_history to NotModified!:
|
1 2 |
dw_history.SetItemStatus(5, "Salary", & Primary!, NotModified!) |
This statement sets the status of row 5 in the emp_status column of
the primary buffer of dw_new_hire to DataModified!:
|
1 2 |
dw_new_hire.SetItemStatus(5, "emp_status", & Primary!, DataModified!) |
This code sets the status of row 5 in the primary buffer of dw_rpt
to DataModified! if its status is currently NewModified!:
|
1 2 3 4 5 6 |
dwItemStatus l_status l_status = dw_rpt.GetItemStatus(5, 0, Primary!) IF l_status = NewModified! THEN dw_rpt.SetItemStatus(5, 0, Primary!, DataModified!) END IF |
See also