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