home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / NextLibrary / Documentation / Sybase / DBLIB / Section2 / dbwritetext.nr < prev    next >
Encoding:
Text File  |  1993-04-22  |  8.7 KB  |  253 lines
  1. .Na "dbwritetext"
  2. .mc |
  3. .Aa
  4. .Fu
  5. Send a text or image value to \*S.
  6. .Ih "text value, updating"
  7. .Ih "image value, updating"
  8. .Sy
  9. .Sf "RETCODE dbwritetext(dbproc, objname, textptr, textptrlen,"
  10. .sp -1v
  11. .Sf "                    timestamp, log, size, text)"
  12. .Sp "DBPROCESS" "*dbproc"
  13. .Sp "char" "*objname"
  14. .Sp "DBBINARY" "*textptr"
  15. .Sp "DBTINYINT" "textptrlen"
  16. .Sp "DBBINARY" "*timestamp"
  17. .Sp "DBBOOL" "log"
  18. .Sp "DBINT" "size"
  19. .Sp "BYTE" "*text"
  20. .Co
  21. .Bl
  22. \f2dbwritetext()\f1 updates SYBTEXT and SYBIMAGE values.
  23. It allows the application to send long 
  24. values to \*S without having to copy them into a
  25. \*N UPDATE statement.
  26. In addition, \f2dbwritetext()\f1 gives applications access
  27. to the text timestamp mechanism, which can be used to
  28. ensure that two competing application users do not inadvertently
  29. wipe out each other's modifications to the same value in the database.
  30. .Ih "text timestamp"
  31. .Ih "timestamp, text"
  32. .Bl
  33. \f2dbwritetext()\f1 
  34. will succeed only if its \f2timestamp\f1 parameter, usually obtained when the column's
  35. value was originally retrieved, matches the text column's timestamp in the database.
  36. If a match does occur, \f2dbwritetext()\f1 will update the text column,
  37. and at the same time it will update the column's timestamp.
  38. This has the effect of governing updates by competing applications\(eman application's 
  39. \f2dbwritetext()\f1 call will fail if a second application updated the text column between
  40. the time the first application retrieved the column and the time 
  41. it made its \f2dbwritetext()\f1 call.
  42. .Bl
  43. \f2dbwritetext()\f1 is similar in function to the \*N WRITETEXT command.
  44. It is usually more efficient to call \f2dbwritetext()\f1 than to send
  45. a WRITETEXT command through the command buffer.
  46. In addition, \f2dbwritetext()\f1 can handle columns up to 2 gigabytes in length,
  47. while WRITETEXT data is limited to approximately 120K bytes.
  48. For more information on WRITETEXT, see the \f2Commands Reference\f1.
  49. .Bl
  50. \f2dbwritetext()\f1 can be invoked with or without logging,
  51. according to the value of the \f2log\f1 parameter.
  52. .sp 0.5v
  53. While logging aids media recovery, logging text data quickly
  54. increases the size of the transaction log.
  55. If you're logging \f2dbwritetext()\f1 operations, make sure that the transaction log
  56. resides on a separate database device.
  57. See the \f2System Administration Guide\f1 
  58. and the CREATE DATABASE and \f2sp_logdevice\f1 manual pages in the
  59. \f2Commands Reference\f1 for details.
  60. .sp 0.5v
  61. To use \f2dbwritetext()\f1 with logging turned off,
  62. the database option \f2select into/bulkcopy\f1 must be set to ``true''.
  63. The following SQL command will do this:
  64. .SD
  65. .in +3n
  66. sp_dboption 'mydb', 'select into/bulkcopy', 'true'
  67. .in -3n
  68. .ED
  69. See the \f2Commands Reference\f1 for further details on \f2sp_dboption\f1.
  70. .Bl
  71. The application can send a text or image value to the \*S all at once or a
  72. chunk at a time.
  73. \f2dbwritetext()\f1 by itself handles sending an entire text or image value.
  74. The use of \f2dbwritetext()\f1 with \f2dbmoretext()\f1
  75. allows the application to send a 
  76. large text or image value to \*S in the form
  77. of a number of smaller chunks.
  78. This is particularly useful with operating systems 
  79. unable to allocate extremely long data buffers.
  80. .Bl
  81. To send an entire text or image value requires a
  82. non-NULL \f2text\f1 parameter.
  83. Then, \f2dbwritetext()\f1
  84. will execute the data transfer from start to finish, including
  85. any necessary calls to \f2dbsqlok()\f1 and \f2dbresults()\f1.
  86. Here's a code fragment that illustrates this use of \f2dbwritetext()\f1:
  87. .SD
  88. .ne 5
  89. .ta +4n +4n +4n +4n +4n +4n
  90. LOGINREC        *login;
  91. DBPROCESS       *q_dbproc;
  92. DBPROCESS       *u_dbproc;
  93. DBCHAR          abstract_var[512];
  94.  
  95. /* Initialize DB-Library. */
  96. if (dbinit() == FAIL)
  97.     exit(ERREXIT);
  98.  
  99. /* Open separate DBPROCESSes for querying and updating. 
  100. ** This is not strictly necessary in this example, which
  101. ** retrieves only one row.  However, this approach becomes
  102. ** essential when performing updates on multiple rows of 
  103. ** retrieved data. 
  104. */
  105. login = dblogin();
  106. q_dbproc = dbopen(login, NULL);
  107. u_dbproc = dbopen(login, NULL);
  108.  
  109. /* The database column "abstract" is a text column.  Retrieve the 
  110. ** value of one of its rows. 
  111. */
  112. dbcmd(q_dbproc, "select abstract from articles where article_id = 10");
  113. dbsqlexec(q_dbproc);
  114. dbresults(q_dbproc);
  115. dbbind(q_dbproc, 1, STRINGBIND, (DBINT) 0, abstract_var);
  116.  
  117. /* For simplicity, we'll assume that just one row is returned. */
  118. dbnextrow(q_dbproc);
  119.  
  120. /* Here we can change the value of "abstract_var".  For instance ... */
  121. strcpy(abstract_var, "A brand new value.");
  122.  
  123. /* Update the text column. */
  124. dbwritetext
  125.     (u_dbproc, "articles.abstract", dbtxptr(q_dbproc, 1), DBTXPLEN, 
  126.      dbtxtimestamp(q_dbproc, 1), TRUE, (DBINT)strlen(abstract_var), 
  127.      abstract_var);
  128.  
  129. /* We're all done. */
  130. dbexit();
  131. .ED
  132. .Bl
  133. To send chunks of text or image, rather than the whole value at once, set
  134. the \f2text\f1 parameter to NULL.
  135. Then, \f2dbwritetext()\f1 will
  136. return control to the application immediately after notifying
  137. \*S that a text transfer is about to begin.
  138. The actual text will be sent to \*S with \f2dbmoretext()\f1, which can be called
  139. multiple times, once for each chunk.
  140. Here's a code fragment that illustrates the 
  141. use of \f2dbwritetext()\f1 with \f2dbmoretext()\f1:
  142. .SD
  143. .ne 5
  144. .ta +4n +4n +4n +4n +4n +4n
  145. LOGINREC        *login;
  146. DBPROCESS       *q_dbproc;
  147. DBPROCESS       *u_dbproc;
  148. DBCHAR          part1[512];
  149. static DBCHAR   part2[512] = " This adds another sentence to the text.";
  150.  
  151. if (dbinit() == FAIL)
  152.     exit(ERREXIT);
  153.  
  154. login = dblogin();
  155. q_dbproc = dbopen(login, NULL);
  156. u_dbproc = dbopen(login, NULL);
  157.  
  158. dbcmd(q_dbproc, "select abstract from articles where article_id = 10");
  159. dbsqlexec(q_dbproc);
  160. dbresults(q_dbproc);
  161. dbbind(q_dbproc, 1, STRINGBIND, (DBINT) 0, part1);
  162.  
  163. /* For simplicity, we'll assume that just one row is returned. */
  164. dbnextrow(q_dbproc);
  165.  
  166. /* 
  167. ** Here we can change the value of part of the text column. In
  168. ** this example, we will merely add a sentence to the end of the 
  169. ** existing text.
  170. */
  171.  
  172. /* Update the text column. */
  173. dbwritetext
  174.     (u_dbproc, "articles.abstract", dbtxptr(q_dbproc, 1), DBTXPLEN, 
  175.      dbtxtimestamp(q_dbproc, 1), TRUE, (DBINT)(strlen(part1) + strlen(part2)), 
  176.      NULL);
  177.  
  178. dbsqlok(u_dbproc);
  179. dbresults(u_dbproc);
  180.  
  181. /* Send the update value in chunks. */
  182. dbmoretext(u_dbproc, (DBINT)strlen(part1), part1);
  183. dbmoretext(u_dbproc, (DBINT)strlen(part2), part2);
  184.  
  185. dbsqlok(u_dbproc);
  186. dbresults(u_dbproc);
  187.  
  188. dbexit();
  189. .ED
  190. Note the required calls to \f2dbsqlok()\f1 and \f2dbresults()\f1 between
  191. the call to \f2dbwritetext()\f1 and the first call to
  192. \f2dbmoretext()\f1, and after the final call to \f2dbmoretext()\f1.
  193. .Bl
  194. When \f2dbwritetext()\f1 is used with \f2dbmoretext()\f1,
  195. it locks the specified database text column.
  196. The lock is not released until the final \f2dbmoretext()\f1 has sent its data.
  197. This ensures that a second application does not read or update the text
  198. column in the midst of the first application's update.
  199. .Bl
  200. You cannot use \f2dbwritetext()\f1 on text or image columns in views.
  201. .Bz
  202. .Pa
  203. .Pi dbproc
  204. A pointer to the DBPROCESS structure that provides the connection
  205. for a particular front-end/\*S process.  It contains all the
  206. information that \*L uses to manage communications and data between the
  207. front end and \*S.
  208. .Pi objname
  209. The database table and column name of interest.
  210. The table and the column should be separated by a period (``.'').
  211. .Pi textptr
  212. A pointer to
  213. the text pointer of the text or image value to be modified.
  214. This can be obtained by calling \f2dbtxptr()\f1.
  215. The text pointer must be a valid one, as described on
  216. the \f2dbtxptr()\f1 manual page.
  217. .Pi textptrlen
  218. This parameter is included for future compatibility.
  219. For now, its value must be the defined constant DBTXPLEN.
  220. .Pi timestamp
  221. A pointer to the text timestamp of the text or image value to be modified.
  222. This can be obtained by calling \f2dbtxtimestamp()\f1 or \f2dbtxtsnewval()\f1.
  223. This value changes whenever the text or image value itself is changed.
  224. .Pi log
  225. A Boolean value, specifying whether this \f2dbwritetext()\f1 operation
  226. should be recorded in the transaction log.
  227. .Pi size
  228. The total size, in bytes, of the text or image value to be written.
  229. Since \f2dbwritetext()\f1 uses this parameter as its only guide
  230. to determining how many bytes to send,
  231. \f2size\f1 must not exceed the actual size of the value.
  232. .Pi text
  233. A pointer to the text or image to be written.
  234. If this pointer is NULL, \*L will expect the application to
  235. call \f2dbmoretext()\f1 one or more times, until all \f2size\f1
  236. bytes of data have been sent to \*S.
  237. .in -.375i
  238. .Re
  239. .br
  240. SUCCEED or FAIL.
  241. .sp 0.5v
  242. A common cause for failure is an invalid \f2timestamp\f1 parameter.
  243. This will occur if, between the time the application retrieves the 
  244. text column and the time the application calls \f2dbwritetext()\f1 to update it,
  245. a second application intervenes with its own update.
  246. .Sa
  247. dbmoretext,
  248. dbtxptr, 
  249. dbtxtimestamp,
  250. dbtxtsnewval,
  251. dbtxtsput
  252. .mc
  253.