home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / usr / sybase / doc / dbbind.man < prev    next >
Encoding:
Text File  |  1993-04-22  |  10.0 KB  |  243 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89                   dbbind
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  dbbind
  6.  
  7.   FUNCTION:
  8.        Bind a regular result column to a program variable.
  9.  
  10.   SYNTAX:
  11.        RETCODE dbbind(dbproc, column, vartype, varlen, varaddr)
  12.  
  13.        DBPROCESS *dbproc;
  14.        int       column;
  15.        int       vartype;
  16.        DBINT     varlen;
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   dbbind                  Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.        BYTE      *varaddr;
  27.  
  28.   COMMENTS:
  29.  
  30.        o Data comes back from SQL Server one row at a time. This routine
  31.          directs  DB-Library  to  copy  the  data  for  a regular column
  32.          (designated in a SELECT statement's select-list) into a program
  33.          variable.   When  each new row containing regular (not compute)
  34.          data is read via dbnextrow() or dbgetrow(), the data  from  the
  35.          designated  column in that row is copied into the program vari-
  36.          able with the  address  varaddr.   There  must  be  a  separate
  37.          dbbind() call for each regular column that is to be copied.  It
  38.          is not necessary to bind every column to a program variable.
  39.        o The SQL Server can return two types of rows: regular  rows  and
  40.          compute  rows  resulting  from  the  COMPUTE clause of a SELECT
  41.          statement.  dbbind() binds data from regular rows.  Use  dbalt-
  42.          bind() for binding data from compute rows.
  43.  
  44.  
  45.  
  46.   3                       Version 4.0 -- 5/1/89                   dbbind
  47.   ______________________________________________________________________
  48.  
  49.        o You must make the calls to dbbind() after a call to dbresults()
  50.          and before the first call to dbnextrow().
  51.        o The typical sequence of calls is:
  52.  
  53.          DBINT     xvariable;
  54.          DBCHAR    yvariable[10];
  55.  
  56.          /* read the query into the command buffer */
  57.          dbcmd(dbproc, "select x = 100, y = 'hello'");
  58.  
  59.          /* send the query to SQL Server */
  60.          dbsqlexec(dbproc);
  61.  
  62.          /* get ready to process the results of the query */
  63.          dbresults(dbproc);
  64.  
  65.  
  66.  
  67.  
  68.   dbbind                  Version 4.0 -- 5/1/89                        4
  69.   ______________________________________________________________________
  70.          /* bind column data to program variables */
  71.          dbbind(dbproc, 1, INTBIND, (DBINT) 0, (BYTE *) &xvariable);
  72.          dbbind(dbproc, 2, STRINGBIND, (DBINT) 0, yvariable);
  73.  
  74.          /* now process each row */
  75.          while (dbnextrow(dbproc) != NO_MORE_ROWS)
  76.          {
  77.              C-code to print or process row data
  78.          }
  79.  
  80.  
  81.        o dbbind() incurs a little overhead, because it causes  the  data
  82.          to  be  copied into a program variable.  To avoid this copying,
  83.          you can  use  the  dbdata()  routine  to  directly  access  the
  84.          returned data.
  85.        o You can only bind a result column to a single program variable.
  86.          If  you  bind  a  result column to multiple variables, only the
  87.  
  88.  
  89.  
  90.   5                       Version 4.0 -- 5/1/89                   dbbind
  91.   ______________________________________________________________________
  92.          last binding takes effect.
  93.  
  94.        o Since SQL Server can return null values, DB-Library provides  a
  95.          set  of  default  values,  one  for each datatype, that it will
  96.          automatically substitute when binding null values.  The  dbset-
  97.          null() function allows you to explicitly set your own null sub-
  98.          stitution values.  (See the manual  page  for  the  dbsetnull()
  99.          function for a list of the default substitution values.)
  100.  
  101.   PARAMETERS:
  102.        dbproc -  A pointer to the DBPROCESS structure that provides  the
  103.            connection for a particular front-end/SQL Server process.  It
  104.            contains all the information that DB-Library uses  to  manage
  105.            communications and data between the front end and SQL Server.
  106.        column -  The column number of the row data that is to be  copied
  107.            to a program variable.  The first column is column number 1.
  108.        vartype -  This describes the datatype of the  binding.  It  must
  109.            correspond  to the datatype of the program variable that will
  110.  
  111.  
  112.   dbbind                  Version 4.0 -- 5/1/89                        6
  113.   ______________________________________________________________________
  114.            receive the copy of the data from the DBPROCESS.   The  table
  115.            below  shows  the correspondence between vartypes and program
  116.            variable types.
  117.  
  118.            dbbind() supports a wide range of type  conversions,  so  the
  119.            vartype  can  be  different from the type returned by the SQL
  120.            query.  For instance, a SYBMONEY result may  be  bound  to  a
  121.            DBFLT8  program  variable  via  FLT8BIND, and the appropriate
  122.            data conversion will happen automatically.  For a list of the
  123.            data  conversions provided by DB-Library, see the manual page
  124.            for dbwillconvert().
  125.  
  126.            For a list of the typedefs used by DB-Library, see the manual
  127.            page for types.
  128.  
  129.            Here is a list of the legal vartypes recognized by  dbbind(),
  130.            along  with  the  SQL Server  and program variable types that
  131.  
  132.  
  133.  
  134.   7                       Version 4.0 -- 5/1/89                   dbbind
  135.   ______________________________________________________________________
  136.            each one refers to:
  137.  
  138.               Vartype                 Program variable type     SQL Server type
  139.  
  140.               CHARBIND                DBCHAR                    SYBCHAR or SYBTEXT
  141.               STRINGBIND              DBCHAR                    SYBCHAR or SYBTEXT
  142.               NTBSTRINGBIND           DBCHAR                    SYBCHAR or SYBTEXT
  143.               VARYCHARBIND            DBVARYCHAR                SYBCHAR or SYBTEXT
  144.               BINARYBIND              DBBINARY                  SYBBINARY or SYBIMAGE
  145.               VARYBINBIND             DBVARYBIN                 SYBBINARY or SYBIMAGE
  146.               TINYBIND                DBTINYINT                 SYBINT1
  147.               SMALLBIND               DBSMALLINT                SYBINT2
  148.               INTBIND                 DBINT                     SYBINT4
  149.               FLT8BIND                DBFLT8                    SYBFLT8
  150.               BITBIND                 DBBIT                     SYBBIT
  151.               DATETIMEBIND            DBDATETIME                SYBDATETIME
  152.               MONEYBIND               DBMONEY                   SYBMONEY
  153.  
  154.  
  155.  
  156.   dbbind                  Version 4.0 -- 5/1/89                        8
  157.   ______________________________________________________________________
  158.            Note that the SQL Server type in the table  above  is  listed
  159.            merely  for  your  information.  The vartype you specify does
  160.            not necessarily have to correspond to a particular SQL Server
  161.            type,  because,  as  mentioned earlier, dbbind() will convert
  162.            SQL Server data into the specified vartype.
  163.  
  164.            The table shows that four representations for  character  and
  165.            text  data  are  available.  They differ according to whether
  166.            the data is blank-padded or null-terminated:
  167.  
  168.               Vartype                 Program type            Padding        Terminator
  169.  
  170.               CHARBIND                DBCHAR                  blanks         none
  171.               STRINGBIND              DBCHAR                  blanks         \0
  172.               NTBSTRINGBIND           DBCHAR                  none           \0
  173.               VARYCHARBIND            DBVARYCHAR              none           none
  174.  
  175.            Note that the "\0" in the table above is the null  terminator
  176.  
  177.  
  178.   9                       Version 4.0 -- 5/1/89                   dbbind
  179.   ______________________________________________________________________
  180.            character.
  181.  
  182.            If overflow occurs when converting integer or float data to a
  183.            character/text  binding  type,  the  first  character  of the
  184.            resulting value will contain an asterisk  ("*")  to  indicate
  185.            the error.
  186.  
  187.            Binary and image data may be stored in two different ways:
  188.  
  189.               Vartype                 Program type            Padding
  190.  
  191.               BINARYBIND              DBBINARY                nulls
  192.               VARYBINBIND             DBVARBINARY             none
  193.  
  194.        varlen -  The length of the program variable in bytes.
  195.  
  196.            For fixed-length vartypes, such  as  MONEYBIND  or  FLT8BIND,
  197.            this length is ignored.
  198.  
  199.  
  200.   dbbind                  Version 4.0 -- 5/1/89                       10
  201.   ______________________________________________________________________
  202.            For character, text, binary, and  image  types,  varlen  must
  203.            describe the total length of the available destination buffer
  204.            space, including any space that may be required  for  special
  205.            terminating  bytes,  such as a null terminator.  If varlen is
  206.            0, the total number of bytes available will  be  copied  into
  207.            the  program variable.  (For char and binary SQL Server data,
  208.            the total number of bytes available is equal to  the  defined
  209.            length  of  the database column, including any blank padding.
  210.            For varchar, varbinary,  text,  and  image  data,  the  total
  211.            number  of  bytes  available is equal to the actual data con-
  212.            tained in the column.) Therefore, if you are sure  that  your
  213.            program  variable  is large enough to handle the results, you
  214.            can just set varlen to 0.
  215.        varaddr -  The address of the program variable to which the  data
  216.            will be copied.
  217.  
  218.   RETURNS:
  219.  
  220.  
  221.  
  222.   11                      Version 4.0 -- 5/1/89                   dbbind
  223.   ______________________________________________________________________
  224.        SUCCEED or FAIL.  dbbind() returns  FAIL  if  the  column  number
  225.        isn't  valid,  if  the data conversion specified by vartype isn't
  226.        legal, or if varaddr is NULL.
  227.  
  228.   SEE ALSO:
  229.        dbaltbind, dbconvert, dbdata, dbsetnull, dbwillconvert, types
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.