MsiViewModify

[This is preliminary documentation and subject to change.]

The MsiViewModify function updates a fetched record.

UINT MsiViewModify(
  MSIHANDLE hView,        // view handle
  MSIMODIFY eModifyMode,  // modify mode
  MSIHANDLE hRecord       // record handle
);
 

Parameters

hView

Handle to a view.

eModifyMode

Specifies the modify mode. This parameter can be one of the following values.

Value	Meaning
MSIMODIFY_REFRESH	Refetch current record data.
MSIMODIFY_INSERT	Insert a new record. The function fails if a matching key exists.
MSIMODIFY_UPDATE	Update the existing non-key data of the fetched record.
MSIMODIFY_ASSIGN	Insert a new record. If a matching key exists, the record is replaced.
MSIMODIFY_REPLACE	Update the record, delete the old if primary key edit.
MSIMODIFY_MERGE	The function fails if there is a record with a duplicate key that is not identical.
MSIMODIFY_DELETE	Remove a row referenced by this record from the table.
MSIMODIFY_INSERT_TEMPORARY	Insert a temporary record.
MSIMODIFY_VALIDATE	Validate a fetched record.
MSIMODIFY_VALIDATE_DELETE	Validate a record to be deleted.
MSIMODIFY_VALIDATE_NEW	Validate a new record.
MSIMODIFY_VALIDATE_FIELD	Validate field(s) of an incomplete record.

hRecord

Handle to the record to modify.

Return Values

ERROR_ACCESS_DENIED

Access was not permitted.

ERROR_FUNCTION_FAILED

The function failed.

ERROR_INVALID_DATA

A validation was requested and the data did not pass. For more information, call MsiViewGetError.

ERROR_INVALID_HANDLE

An invalid or inactive handle was supplied.

ERROR_INVALID_HANDLE_STATE

The handle is in an invalid state.

ERROR_INVALID_PARAMETER

An invalid parameter was passed to the function.

ERROR_SUCCESS

The function succeeded.

Remarks

The MSIMODIFY_VALIDATE, MSIMODIFY_VALIDATE_NEW, and MSIMODIFY_VALIDATE_FIELD values of the MsiViewModify function do not perform actual updates; they ensure that the data in the record is valid.

The MsiViewModify function uses the following action and modification mode descriptions.

MSIMODIFY_INSERT

Inserts the information into the database table. You are not required to call the MsiViewFetch function before you call this operation. MsiViewModify fails if a row with the same primary keys exists in the table. For this operation, the database must be writable.

MSIMODIFY_UPDATE

Updates the existing information in the database, allowing modification of non-primary keys only. Before you call this operation, you must call the MsiViewFetch function with the same record as that returned by the fetch. The function fails if the row has been deleted from the table. For this operation, the database must be writable.

MSIMODIFY_DELETE

Deletes the information already existing in the database. Before you call this operation, you must call the MsiViewFetch function with the same record as that returned by the fetch. The function fails if the row has been deleted from the table. For this operation, the database must be writable.

MSIMODIFY_INSERT_TEMPORARY

Temporarily inserts the information into the database table. The information is not persistent. You are not required to call the MsiViewFetch function before you call this operation. The function fails if a row with the same primary keys exists. For this operation, the database can be writable or read-only.

MSIMODIFY_REFRESH

Refreshes the information in the record from the database. Before you call this operation, you must call the MsiViewFetch function with the same record as that returned by the retrieval. The function fails if the row has been deleted from the table. For this operation, the database can be writable or read-only.

MSIMODIFY_ASSIGN

Inserts or updates the information into the database table. You are not required to call the MsiViewFetch function before you call this operation. An update operation takes place if primary keys match an existing row. An insert operation takes place if primary keys do not match any row. In either case, the current data in the cursor is written to a table row. For this operation, the database must be writable.

MSIMODIFY_MERGE

Inserts or validates the information into the database table. You are not required to call the MsiViewFetch function before you call this operation. An insert operation takes place if primary keys do not match any row. A validation operation takes place if primary keys match an existing row. The operation fails if the record data does not match the data in the table. For this operation, the database must be writable.

MSIMODIFY_REPLACE

Performs an update or a delete/insert operation on the information that is going into the database table. Before you call this operation, you must call the MsiViewFetch function with the same record as that returned by the fetch. If the primary keys have not been changed, an update of the table row occurs. If the primary keys have been changed, the old table row is deleted and a new row corresponding to the record is inserted. For this operation, the database must be writable.

MSIMODIFY_VALIDATE

Validates a record. This operation does not validate across joins. Before calling the operation, you must call the MsiViewFetch function with the same record as that returned by the fetch. You can obtain validation errors by calling MsiViewGetError. For this operation, the database can be read-only or writable.

MSIMODIFY_VALIDATE_DELETE

Validates a row of a retrieved record that will later be deleted. Before calling this operation, you must call the MsiViewFetch function. The function fails if another row of a table refers to the primary keys of this row. However, validation does not check for the existence of the primary keys of this row in properties or strings. This operation also does not check if a column might be a foreign key to possibly multiple tables of which the table for this row is listed. You can obtain validation errors by calling MsiViewGetError.

MSIMODIFY_VALIDATE_NEW

Validates a record as a new record. This operation does not validate across joins. This operation differs from MSIMODIFY_VALIDATE because it checks for duplicate keys. You can obtain validation errors by calling MsiViewGetError. For this operation, the database must be writable.

MSIMODIFY_VALIDATE_FIELD

Validates fields of a fetched or new record. This operation does not validate across joins. The validation depends upon the number of fields in the record. If only one field exists, the operation validates only that field. The operation can also validate more fields. It should be used when the fetched/new record does not represent every column of the table. You can obtain validation errors by calling MsiViewGetError. For this operation, the database can be writable or read-only.

QuickInfo

  Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
  Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Windows CE: Unsupported.
  Header: Declared in msiquery.h.
  Import Library: Use msi.lib.

See Also

Database Access Reference, General Database Access Functions