home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / NextLibrary / Documentation / Sybase / DBLIB / Section3 / bcp_moretext.nr < prev    next >
Encoding:
Text File  |  1993-04-22  |  4.2 KB  |  149 lines
  1. .Na "bcp_moretext"
  2. .mc |
  3. .Aa
  4. .Fu
  5. Send part of a text or image value to \*S.
  6. .Ih "text value, with bcp"
  7. .Ih "image value, with bcp"
  8. .Sy
  9. .Sf "RETCODE bcp_moretext(dbproc, size, text)"
  10. .Sp "DBPROCESS" "*dbproc"
  11. .Sp "DBINT" "size"
  12. .Sp "BYTE" "*text"
  13. .Co
  14. .Bl
  15. This routine is used in conjunction with \f2bcp_bind()\f1 and \f2bcp_sendrow()\f1
  16. to send a large SYBTEXT or SYBIMAGE value to \*S in the form
  17. of a number of smaller chunks.
  18. This is particularly useful with operating systems 
  19. unable to allocate extremely long data buffers.
  20. .Bl
  21. If \f2bcp_bind()\f1 is called with a \f2type\f1 parameter of SYBTEXT or SYBIMAGE
  22. and a non-NULL \f2varaddr\f1 parameter, \f2bcp_sendrow()\f1 will send
  23. the entire text or image data value, just as it does for all other
  24. datatypes.
  25. If, however, \f2bcp_bind()\f1 has a NULL \f2varaddr\f1 parameter,
  26. \f2bcp_sendrow()\f1 will return control to the application immediately
  27. after all non-text or image columns are sent to \*S.
  28. The application can then call
  29. \f2bcp_moretext()\f1 repeatedly to send the text and image columns to \*S,
  30. a chunk at a time.
  31. .Bl
  32. Here's an example that illustrates how to use \f2bcp_moretext()\f1 with
  33. \f2bcp_bind()\f1 and \f2bcp_sendrow()\f1:
  34. .SD
  35. .ta +4n +4n +4n +4n +4n +4n
  36. .in +3n
  37. .ne 5
  38. LOGINREC        *login;
  39. DBPROCESS       *dbproc;
  40.  
  41. DBINT           id = 5;
  42. char            *part1 = "This text value isn't very long,";
  43. char            *part2 = " but it's broken up into three parts";
  44. char            *part3 = " anyhow.";
  45.  
  46. /* Initialize DB-Library. */
  47. if (dbinit() == FAIL)
  48.     exit(ERREXIT);
  49.     
  50. /* Install error handler and message handler. */
  51. dberrhandle(err_handler);
  52. dbmsghandle(msg_handler);
  53.     
  54. /* Open a DBPROCESS */
  55. login = dblogin();
  56. BCP_SETL(login, TRUE);
  57. dbproc = dbopen(login, NULL);
  58.  
  59. /* Initialize bcp. */
  60. if (bcp_init(dbproc, "comdb..articles", (BYTE *)NULL, (BYTE *)NULL, DB_IN) == FAIL)
  61.     exit(ERREXIT);
  62.  
  63. /* Bind program variables to table columns. */
  64. if (bcp_bind(dbproc, (BYTE *)&id, 0, (DBINT)-1, (BYTE *)NULL, 0, SYBINT4, 1)
  65.     == FAIL)
  66. {
  67.     fprintf(stderr, "bcp_bind, column 1, failed.\en");
  68.     exit(ERREXIT);
  69. }
  70.  
  71. if (bcp_bind
  72.     (dbproc, (BYTE *)NULL, 0, (DBINT) (strlen(part1) + strlen(part2) + strlen(part3)),
  73.      (BYTE *)NULL, 0, SYBTEXT, 2)
  74.      == FAIL)
  75. {
  76.     fprintf(stderr, "bcp_bind, column 2, failed.\en");
  77.     exit(ERREXIT);
  78. }
  79.  
  80. /* Now send this row, with the text value broken into three chunks. */
  81. if (bcp_sendrow(dbproc) == FAIL)
  82.     exit(ERREXIT);
  83. if (bcp_moretext(dbproc, (DBINT)strlen(part1), part1) == FAIL)
  84.     exit(ERREXIT);
  85. if (bcp_moretext(dbproc, (DBINT)strlen(part2), part2) == FAIL)
  86.     exit(ERREXIT);
  87. if (bcp_moretext(dbproc, (DBINT)strlen(part3), part3) == FAIL)
  88.     exit(ERREXIT);
  89.  
  90. /* We're all done. */
  91. bcp_done(dbproc);
  92. dbclose(dbproc);
  93. .in -3n
  94. .ED
  95. .Bl
  96. If you use \f2bcp_moretext()\f1 to send one text or image column in the row,
  97. you must also use it to send all other text and image columns in the row.
  98. .Bl
  99. If the row contains more than one text or image column,
  100. \f2bcp_moretext()\f1 will first send its data to the lowest-numbered (\f2i.e.,\f1
  101. leftmost) text or image column, followed by the next lowest-numbered
  102. column, and so on.
  103. .Bl
  104. An application will normally call \f2bcp_sendrow()\f1 and \f2bcp_moretext()\f1
  105. within loops, in order to send a number of rows of data.
  106. Here's an outline of how to do this for a table containing two text columns:
  107. .SD
  108. .in +3n
  109. .ta +4n +4n +4n +4n 
  110. .ne 5
  111. while (there are still rows to send)
  112. {
  113.     bcp_sendrow(...);
  114.  
  115.     for (all the data in the first text column)
  116.         bcp_moretext(...);
  117.  
  118.     for (all the data in the second text column)
  119.         bcp_moretext(...);
  120. }
  121. .in -3n
  122. .ED
  123. .Bl
  124. For information on the \f2bcp\f1 utility program, see its manual page
  125. in the \f2Commands Reference\f1.
  126. .Bz
  127. .Pa
  128. .Pi dbproc
  129. A pointer to the DBPROCESS structure that provides the connection
  130. for a particular front-end/\*S process.  It contains all the
  131. information that \*L uses to manage communications and data between the
  132. front end and \*S.
  133. .Pi size
  134. The size of this particular part of the text or image value being sent to \*S.
  135. It is an error to send more text or image bytes to \*S than were specified in the
  136. call to \f2bcp_bind()\f1 or \f2bcp_collen()\f1.
  137. .Pi text
  138. A pointer to the text or image portion to be written.
  139. .in -.375i
  140. .Re
  141. .br
  142. SUCCEED or FAIL.
  143. .Sa
  144. bcp_bind,
  145. bcp_sendrow,
  146. dbmoretext,
  147. dbwritetext
  148. .mc
  149.