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 or Microsoft® SQL Server™ 2000 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:
| 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.