SqlUpdateText%

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

Syntax

SqlUpdateText% ( sqlconn%, dest_object$, dest_textptr$, dest_timestamp$, update_type%, insert_offset&, delete_length&, src_object$, src_size&, src_text$ )

where

sqlconn%

A SQL Server connection. The value of sqlconn% is returned by SqlOpen%.

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 SqlTxPtr$ to get this value. This string cannot be empty.

dest_timestamp$

Is the timestamp of the existing text or image value to be updated. Call SqlTxTimeStamp$ to get this value. This string cannot be empty.

update_type%

The type of update operation to perform.

Use UTTEXT% to insert new data from a program variable specified in this call to SqlUpdateText%. You must specify an empty src_object$ string, a src_size& equal to the size in bytes of the new data value being inserted, and a non-empty src_text$ that contains the new data value being inserted.

Use UTMORETEXT% to insert new data from a program variable with later calls to SqlMoreText%. You must specify an empty src_object$ string, a src_size& equal to the total size in bytes of the new data value (that will be inserted by calls to SqlMoreText%), and an empty src_text$ string. Then call SqlMoreText% to insert the new data value in chunks.

Use UTTEXTPTR% to insert new data from a text or image column of an existing table. You must specify a non-empty src_object$ string that gives the table and column a src_size& of 0, and a non-empty src_text$ string that gives the text pointer (returned by SqlTxPtr$) of the new data value being inserted from the src_object$.

Use UTDELETEONLY% to only delete existing data. You must specify an insert_offset& value other than -1 and a non-zero delete_length& value. Specify that no new data will be inserted by using an empty src_object$ string, a src_size& of 0 and an empty src_text$ string.

By default, a SqlUpdateText% operation is not recorded in the transaction log. You can bitwise OR the UTLOG% bit flag with any of these update_type% values (for example UTTEXT% Or UTLOG%) 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 not empty, the src_size& and src_text$ parameters are ignored. If this string is empty, 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 empty.

src_text$

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

Returns

succeed (1) or fail (0).

Remarks

The SqlUpdateText% 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 UTDELETEONLY%, an insert_offset& value other than -1, a non-zero delete_length& value, and the new data to be inserted.

To delete only existing data, specify an update_type% value of UTDELETEONLY%, an insert_offset& value other than -1 and a non-zero delete_length& value. Do not specify any new data to be inserted.

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

See Also

SqlMoreText%, SqlTxPtr$, SqlTxTimeStamp$, SqlTxTsNewVal$, SqlTxTsPut%