SetItemStatus

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 object


Syntax

PowerBuilder

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 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 specifying the new status.

For a list of valid values, see DWItemStatus.


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 object

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

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

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

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

GetItemStatus

ResetUpdate