dbupdatetext

Updates an existing text or image value. Unlike dbwritetext which replaces an entire text or image value, dbupdatetext can change only a portion of a text or image value in place.

Syntax

RETCODE dbupdatetext (
PDBPROCESS pdbproc,
LPCSTR dest_object,
LPCDBBINARY dest_textptr,
LPCDBBINARY dest_timestamp,
INT update_type,
DBINT insert_offset,
DBINT delete_length,
LPCSTR src_object,
DBINT src_size,
LPCBYTE src_text );

Arguments

pdbproc

Is the DBPROCESS structure that is the handle for a particular workstation/Microsoft® SQL Server™ process. It contains all the information that DB-Library uses to manage communications and data between the workstation and SQL Server.

dest_object

Is the destination table and text or image column name (separated with a period) of the existing text or image value to be updated.

dest_textptr

Is the text pointer of the existing text or image value to be updated. Call dbtxptr to get this value. This parameter cannot be NULL.

dest_timestamp

Is the timestamp of the existing text or image value to be updated. Call dbtxtimestamp to get this value. This parameter cannot be NULL.

update_type

The type of update operation to perform.

Use UT_TEXT to insert new data from a C program variable specified in this call to dbupdatetext. You must specify an src_object value of NULL, an src_size equal to the size in bytes of the new data value being inserted, and a non-NULL src_text that points to the C program variable that contains the new data value being inserted.

Use UT_MORETEXT to insert new data from a C program variable with later calls to dbmoretext. You must specify a src_object value of NULL, a src_size equal to the total size in bytes of the new data value (that will be inserted by calls to dbmoretext), and a src_text value of NULL. Then call dbmoretext to insert the new data value in chunks.

Use UT_TEXTPTR to insert new data from a text or image column of an existing table. You must specify a non-NULL src_object value that gives the table and column, a src_size of 0, and a non-NULL src_text that gives the text pointer (returned by dbtxptr) of the new data value being inserted from the src_object.

Use UT_DELETEONLY to only delete existing data. You must specify an insert_offset value other than -1 and a nonzero delete_length value. Specify that no new data be inserted by using a src_object value of NULL, a src_size of 0 and a src_text value of NULL.

By default, a dbupdatetext operation is not recorded in the transaction log. You can join the UT_LOG bit flag in a bitwise OR with any of these update_type values (for example UT_TEXT | UT_LOG) to indicate that this operation will be recorded in the transaction log.

insert_offset

Is the zero-based starting position, specified as the number of bytes (from the start of the existing text or image value) to skip before inserting the new data. The existing text or image data beginning at this zero-based starting position will be shifted to the right to make room for the new data. A value of 0 means that the new data will be inserted at the beginning of the existing data value. A value of -1 means that the new data will be appended to the existing data value.

delete_length

Is the number of bytes to delete from the existing text or image value, starting at the insert_offset position. A value of 0 means that no data will be deleted. A value of -1 means that all data from the insert_offset position to the end of the existing text or image value will be deleted.

src_object

Is the source table and text or image column name (separated with a period) that can be used as the source of the inserted data. If non-NULL, the src_size and src_text parameters are ignored. If NULL, the src_size and src_text parameters specify the data to be inserted.

src_size

Is the total size, in bytes, of the source text or image value (specified by src_text) to be inserted. Use this parameter only if the src_object parameter is NULL.

src_text

Is a pointer to the source data value to be inserted. Use this parameter only if the src_object parameter is NULL.

Returns

SUCCEED or FAIL.

Remarks

The dbupdatetext function can be used to delete existing data and then insert new data, to delete only existing data, or to insert only new data.

To delete existing data and then insert new data, specify an update_type other than UT_DELETEONLY, an insert_offset value other than -1, a nonzero delete_length value, and the new data to be inserted.

To delete only existing data, specify an update_type value of UT_DELETEONLY, an insert_offset value other than -1 and a nonzero delete_length value. Do not specify any new data to be inserted.

To insert only new data, specify an update_type other than UT_DELETEONLY, a delete_length value of 0, and the new data to be inserted.

See Also