dbsetnull

Defines substitution values for use when binding null values.

Syntax

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

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.
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. Since 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:

Binding type Default substitution value
TINYBIND 0
SMALLBIND 0
INTBIND 0
BITBIND 0
CHARBIND Empty string (padded with blanks)
STRINGBIND Empty string (padded with blanks, null-terminated)
NTBSTRINGBIND Empty string (null-terminated)
VARYCHARBIND Empty string
BINARYBIND Empty array (padded with zeros)
VARYBINBIND Empty array
DATETIMEBIND 8 bytes of zeros
MONEYBIND $0.00
FLT8BIND 0.0
FLT4BIND 0.0
SMALLMONEYBIND $0.00
SMALLDATETIBIND 4 bytes of zeros
DECIMALBIND 0.0
NUMERICBIND 0.0
SRCDECIMALBIND 0.0
SRCNUMERICBIND 0.0

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

dbaltbind, dbbind, dbconvert; DB-Library Datatypes