Museum

  1                       Version 4.0 -- 5/1/89                dbsetnull
  ______________________________________________________________________

  NAME:  dbsetnull

  FUNCTION:
       Define substitution values to be used when binding null values.

  SYNTAX:
       RETCODE dbsetnull(dbproc, bindtype, bindlen, bindval)

       DBPROCESS *dbproc;
       int       bindtype;
       int       bindlen;
       BYTE      *bindval;







  dbsetnull               Version 4.0 -- 5/1/89                        2
  ______________________________________________________________________

  COMMENTS:

       o The dbbind() and dbaltbind() routines bind result column values
         to  program variables.  After the application calls them, calls
         to dbnextrow() and dbgetrow() automatically copy result  values
         into  the  variables  to  which  they are bound.  If SQL Server
         returns a null value for one of the result columns,  DB-Library
         automatically  places  a substitute value into the result vari-
         able.
       o Each DBPROCESS has a list of substitute values for each of  the
         binding types.  The default substitution values are:








  3                       Version 4.0 -- 5/1/89                dbsetnull
  ______________________________________________________________________
              Binding Type      Null Substitution Value

              TINYBIND          0
              SMALLBIND         0
              INTBIND           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
       o dbsetnull() lets you provide your own null substitution values.
         When you call dbsetnull() to change a particular null substitu-
         tion value,  the  new  value  will  remain  in  force  for  the



  dbsetnull               Version 4.0 -- 5/1/89                        4
  ______________________________________________________________________
         specified DBPROCESS until you change it with  another  call  to
         dbsetnull().

       o The dbconvert() routine also uses the current null substitution
         values when it needs to set a destination variable to null.

  PARAMETERS:
       dbproc -  A pointer to the DBPROCESS structure that provides  the
           connection for a particular front-end/SQL Server process.  It
           contains all the information that DB-Library uses  to  manage
           communications and data between the front end and SQL Server.
       bindtype -  The type of variable binding to which the  substitute
           value will apply.  (See the manual page for dbbind() for more
           information about the different bindtypes.)
       bindlen -  The length in bytes of the substitute  value  you  are
           supplying.   DB-Library  ignores it in all cases except CHAR-
           BIND and BINARYBIND.  All the other types  are  either  fixed
           length  or  have  a special terminator or embedded byte-count


  5                       Version 4.0 -- 5/1/89                dbsetnull
  ______________________________________________________________________
           that provides the length of the data.
       bindval -  A generic BYTE pointer to the value you want to use as
           a  null  substitution value.  dbsetnull() makes a copy of the
           value, so you can free this pointer at any  time  after  this
           call.

  RETURNS:
       SUCCEED or FAIL. dbsetnull() returns FAIL if you give it an  unk-
       nown  bindtype.   It will also fail if the specified DBPROCESS is
       dead.

  SEE ALSO:
       dbaltbind, dbbind, dbconvert, types