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