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