dbtsput

Puts the new value of the timestamp column into the given table's current row in the DBPROCESS.

Syntax

RETCODE dbtsput (
PDBPROCESS dbproc,
LPCDBBINARY newts,
INT newtslen,
INT tabnum,
LPCSTR tabname );

where

dbproc

Is the DBPROCESS structure that is the handle for a particular workstation/ SQL Server process. It contains all the information that DB-Library uses to manage communications and data between the workstation and SQL Server. This must be the DBPROCESS used to perform the original SELECT query.

newts

Is a pointer to the new timestamp value. It is returned by dbtsnewval.

newtslen

Is the length of the new timestamp value. It is returned by dbtsnewlen.

tabnum

Is the number of the updated table. Table numbers start at 1. The tabnum must refer to a table that can be browsed. The dbtabbrowse function determines whether a table can be browsed. If this value is -1, the tabname parameter identifies the table.

tabname

Is a pointer to a null-terminated table name. The tabname must refer to a table that can be browsed. Set this pointer to NULL if the tabnum parameter is used to identify the table. The value of tabname is returned by dbtabsource.

Returns

SUCCEED or FAIL. The following situations cause this function to return FAIL:

• The application tries to update the timestamp of a nonexistent row.
• The application tries to update the timestamp, using NULL as the new timestamp value (newts).
• The specified table cannot be browsed.

Remarks

The dbtsput function is one of the DB-Library browse-mode functions. For a detailed discussion of browse mode, see Browse Mode in Programming with DB-Library.

The dbtsput function manipulates the timestamp column. The WHERE clause returned by dbqual contains a call to the TSEQUAL built-in function. When such a WHERE clause is used in an UPDATE statement, the TSEQUAL function places a new value in the updated row's timestamp column and returns the new timestamp value to the application (if the update is successful). If the same row is updated a second time, the UPDATE statement's WHERE clause must use the latest timestamp value. This function updates the timestamp in the DBPROCESS for the row currently being browsed. Then, if the application needs to update the row a second time, it can call dbqual to formulate a new WHERE clause that uses the new timestamp. Call dbtsput only after dbnextrow or dbgetrow has returned reg_row.

See Also

dbcolbrowse, dbcolsource, dbqual, dbtabbrowse, dbtabcount, dbtabname, dbtabsource, dbtsnewlen, dbtsnewval; Bulk-Copy Functions