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.

Controls

DataWindow type	Method applies to
PowerBuilder	DataWindow control, DataWindowChild object, DataStore object
Web	Server component
Web ActiveX	DataWindow control, DataWindowChild object

Syntax

Argument	Description
dwcontrol	A reference to a DataWindow control, DataStore, or child DataWindow.
row	The row location in which you want to set the status.
column	The column location in which you want to set the status. Column can be a column number or a column name. To set the status for the row, enter 0 for column.
dwbuffer	A value identifying the DataWindow buffer that contains the row. For a list of valid values, see DWBuffer.
status	A value of the dwItemStatus enumerated datatype (PowerBuilder) or an integer (Web ActiveX) or a string (Web DataWindow) specifying the new status. For a list of valid values, see DWItemStatus.

Return Values

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:

Table 9-7: Possible statuses for DataWindow items

Status	Applies to
New!	Rows
NewModified!	Rows
NotModified!	Rows and columns
DataModified!	Rows and columns

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

Table 9-8: Effect of row status on SQL command
called by Update method

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 object

  For more information about setting the update
  characteristics of the DataWindow object, see the 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.

Table 9-9: Effect of changing from one row status to another

Original status	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 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

See Also

• GetItemStatus

• ResetUpdate

---