dbsetnull

Defines substitution values for use when binding null values.

Syntax

RETCODE dbsetnull (
PDBPROCESS dbproc,
INT bindtype,
INT bindlen,
LPCBYTE bindval );

Arguments

dbproc

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.

bindtype

Is the type of variable binding to which the substitute value applies. (For more information about the different bindtypes, see dbbind. )

bindlen

Is the length, in bytes, of the substitute value you are supplying. It is ignored in all cases except CHARBIND and BINARYBIND. All the other types are either fixed length or have a special terminator or embedded byte count that provides the length of the data.

bindval

Is a generic BYTE pointer to the value you want to use as a null value substitution. The dbsetnull function always makes a copy of this data, so you can free this pointer any time after this call.

Returns

SUCCEED or FAIL. The dbsetnull function fails if you give it a null bindval or if the length is smaller than 1 when CHARBIND and BINARYBIND types are used.

Remarks

The dbbind and dbaltbind functions are used to bind returned SQL Server column values to your program variables. Because a null value can be returned, there is a mechanism for defining what values should be substituted for the null value when doing automatic copying of column data to program variables. Associated with each DBPROCESS is a list of substitute values for each of the binding types. The default substitution values are as follows:

Call dbsetnull to supply your own null substitution values. Whenever you call dbsetnull to change a particular null substitution value, the new value remains in force for that DBPROCESS until you change it with another call to dbsetnull.

The dbconvert function also uses the current null substitution values when it needs to set a destination variable to null.

See Also