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