home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / usr / sybase / doc / bcp_bind.man < prev    next >
Encoding:
Text File  |  1993-04-22  |  10.0 KB  |  265 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89                 bcp_bind
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  bcp_bind
  6.  
  7.   FUNCTION:
  8.        Bind data from a program variable to a SQL Server table.
  9.  
  10.   SYNTAX:
  11.        RETCODE bcp_bind (dbproc, varaddr, prefixlen, varlen,
  12.                          terminator, termlen, type, table_column)
  13.  
  14.        DBPROCESS *dbproc;
  15.        BYTE      *varaddr;
  16.        int       prefixlen;
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   bcp_bind                Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.        DBINT     varlen;
  27.        BYTE      *terminator;
  28.        int       termlen;
  29.        int       type;
  30.        int       table_column;
  31.  
  32.   COMMENTS:
  33.  
  34.        o There may be times when you want to copy data directly  from  a
  35.          program  variable into a table in SQL Server, without having to
  36.          first place the data in a host file or use the SQL INSERT  com-
  37.          mand.   The  bcp_bind() function is a fast and efficient way to
  38.          do this.
  39.        o You must call bcp_init() before calling this or any other  bulk
  40.          copy functions.
  41.  
  42.        o There must be a separate bcp_bind() call for  every  column  in
  43.          the  SQL Server  table  into  which you want to copy. After the
  44.  
  45.  
  46.   3                       Version 4.0 -- 5/1/89                 bcp_bind
  47.   ______________________________________________________________________
  48.          necessary bcp_bind()  calls  have  been  made,  you  then  call
  49.          bcp_sendrow() to send a row of data from your program variables
  50.          to SQL Server.  The table to be copied into is set  by  calling
  51.          bcp_init().
  52.  
  53.        o Whenever you want SQL Server to  checkpoint  the  rows  already
  54.          received,  call  bcp_batch(). For example, you may want to call
  55.          bcp_batch() once for every 1000 rows inserted, or at any  other
  56.          interval.
  57.        o When there are no more rows to be  inserted,  call  bcp_done().
  58.          Failure to do so will result in an error.
  59.  
  60.        o When using bcp_bind(), the host filename parameter used in  the
  61.          call to bcp_init(), hfile, must be set to NULL, and  the direc-
  62.          tion parameter, direction, must be set to DB_IN.
  63.        o Control parameter settings, specified with bcp_control(),  have
  64.          no effect on bcp_bind() row transfers.
  65.  
  66.  
  67.  
  68.   bcp_bind                Version 4.0 -- 5/1/89                        4
  69.   ______________________________________________________________________
  70.  
  71.        o It is an error to call bcp_columns() when using bcp_bind().
  72.        o The following program fragment illustrates bcp_bind():
  73.  
  74.          LOGINREC        *login;
  75.          DBPROCESS       *dbproc;
  76.          char            co_name[MAXNAME];
  77.          DBINT           co_id;
  78.          DBINT           rows_sent;
  79.          DBBOOL            more_data;
  80.          char            *terminator = "\t\t";
  81.  
  82.          /* Initialize DB-Library. */
  83.          if (dbinit() == FAIL)
  84.              exit(ERREXIT);
  85.  
  86.          /* Install error-handler and message-handler. */
  87.  
  88.  
  89.  
  90.   5                       Version 4.0 -- 5/1/89                 bcp_bind
  91.   ______________________________________________________________________
  92.          dberrhandle(err_handler);
  93.          dbmsghandle(msg_handler);
  94.  
  95.          /* Open a DBPROCESS. */
  96.          login = dblogin();
  97.          BCP_SETL(login, TRUE);
  98.          dbproc = dbopen(login, NULL);
  99.  
  100.          /* Initialize bcp. */
  101.          if (bcp_init(dbproc, "comdb..accounts_info", NULL, NULL, DB_IN) == FAIL)
  102.              exit(ERREXIT);
  103.  
  104.          /* Bind program variables to table columns. */
  105.          if (bcp_bind(dbproc, &co_id, 0, -1, (BYTE *)NULL, 0, 0, 1) == FAIL)
  106.          {
  107.              fprintf(stderr, "bcp_bind, column 1, failed.\n");
  108.              exit(ERREXIT);
  109.  
  110.  
  111.  
  112.   bcp_bind                Version 4.0 -- 5/1/89                        6
  113.   ______________________________________________________________________
  114.          }
  115.  
  116.          if (bcp_bind
  117.              (dbproc, co_name, 0, -1, (BYTE *)terminator, strlen(terminator), 0, 2)
  118.                  == FAIL)
  119.          {
  120.              fprintf(stderr, "bcp_bind, column 2, failed.\n");
  121.              exit(ERREXIT);
  122.          }
  123.  
  124.          while (TRUE)
  125.          {
  126.              /* Process/retrieve program data. */
  127.              more_data = getdata(&co_id, co_name);
  128.  
  129.              if (more_data == FALSE)
  130.                  break;
  131.  
  132.  
  133.  
  134.   7                       Version 4.0 -- 5/1/89                 bcp_bind
  135.   ______________________________________________________________________
  136.  
  137.              /* Send the data. */
  138.              if (bcp_sendrow(dbproc) == FAIL)
  139.                  exit(ERREXIT);
  140.          }
  141.  
  142.          /* Terminate the bulk copy operation. */
  143.          if ((rows_sent = bcp_done(dbproc)) == -1)
  144.              printf("Bulk-copy unsuccessful.\n");
  145.          else
  146.              printf("%ld rows copied.\n", rows_sent);
  147.  
  148.  
  149.        o For information on the bcp utility program, see its manual page
  150.          in the Commands Reference.
  151.  
  152.   PARAMETERS:
  153.        dbproc -  A pointer to the DBPROCESS structure that provides  the
  154.  
  155.  
  156.   bcp_bind                Version 4.0 -- 5/1/89                        8
  157.   ______________________________________________________________________
  158.            connection for a particular front-end/SQL Server process.  It
  159.            contains  all  the information that DB-Library uses to manage
  160.            communications and data between the front end and SQL Server.
  161.        varaddr -  The address of the program  variable  from  which  the
  162.            data will be copied.  If type is SYBTEXT or SYBIMAGE, varaddr
  163.            can be NULL.  A NULL varaddr indicates that  text  and  image
  164.            values   will   be   sent   to   SQL Server   in   chunks  by
  165.            bcp_moretext(), rather than all at once by bcp_sendrow().
  166.        prefixlen -  The length, in bytes,  of  any  length  prefix  this
  167.            column  may have. For example, strings in some non-C program-
  168.            ming languages are made up of a one-byte length prefix,  fol-
  169.            lowed by the string data itself.  If the data does not have a
  170.            length prefix, set prefixlen to 0.
  171.        varlen -  The length of the data in  the  program  variable,  not
  172.            including  the length of any length prefix and/or terminator.
  173.            Setting varlen to 0 signifies that the data is null.  Setting
  174.            varlen  to  -1  indicates  that the system should ignore this
  175.  
  176.  
  177.  
  178.   9                       Version 4.0 -- 5/1/89                 bcp_bind
  179.   ______________________________________________________________________
  180.            parameter.
  181.  
  182.            For fixed-length datatypes, such as  integers,  the  datatype
  183.            itself  indicates  to  the  system  the  length  of the data.
  184.            Therefore, for fixed-length datatypes, varlen must always  be
  185.            -1,  except  when the data is null, in which case varlen must
  186.            be 0.
  187.            For character, text, binary, and image data,  varlen  can  be
  188.            -1,  0,  or some positive value.  If varlen is -1, the system
  189.            will use either a length prefix or a terminator  sequence  to
  190.            determine the length.  (If both are supplied, the system will
  191.            use the one that results in the shortest amount of data being
  192.            copied.)  If  varlen  is -1 and neither a prefix length nor a
  193.            terminator sequence is specified, the system will  return  an
  194.            error  message.   If varlen is 0, the system assumes the data
  195.            is null.  If varlen is some positive value, the  system  uses
  196.            varlen  as  the  data  length.  However, if, in addition to a
  197.  
  198.  
  199.  
  200.   bcp_bind                Version 4.0 -- 5/1/89                       10
  201.   ______________________________________________________________________
  202.            positive varlen, a prefix length and/or  terminator  sequence
  203.            is  provided,  the system determines the data length by using
  204.            the method that results in the shortest amount of data  being
  205.            copied.
  206.        terminator -  A pointer to the byte pattern, if any,  that  marks
  207.            the  end  of  this  program variable.  For example, C strings
  208.            usually have a one-byte terminator, whose  value  is  0.   If
  209.            there  is  no  terminator for the variable, set terminator to
  210.            NULL.
  211.  
  212.            If you want to designate the C null terminator as the program
  213.            variable  terminator,  the  simplest  way  is to use an empty
  214.            string ("") as terminator and set termlen  to  1,  since  the
  215.            null terminator constitutes a single byte.  For instance, the
  216.            second bcp_bind() call in the previous example uses two  tabs
  217.            as the program variable terminator.  It could be rewritten to
  218.            use a C null terminator instead, as follows:
  219.  
  220.  
  221.  
  222.   11                      Version 4.0 -- 5/1/89                 bcp_bind
  223.   ______________________________________________________________________
  224.               (bcp_bind (dbproc, co_name, 0, -1, "", 1, 0, 2)
  225.  
  226.        termlen -  The length of this program variable's  terminator,  if
  227.            any.  If there is no terminator for the variable, set termlen
  228.            to 0.
  229.        type -  The datatype of your program  variable,  expressed  as  a
  230.            SQL Server datatype. The data in the program variable will be
  231.            automatically converted to the type of the  database  column.
  232.            If  this parameter is 0, no conversion will be performed. See
  233.            the dbconvert() manual page for a list of  supported  conver-
  234.            sions.  That  manual  page also contains a list of SQL Server
  235.            datatypes.
  236.        table_column -  The column in the database  table  to  which  the
  237.            data will be copied. Column numbers start at 1.
  238.  
  239.   RETURNS:
  240.        SUCCEED or FAIL.
  241.  
  242.  
  243.  
  244.   bcp_bind                Version 4.0 -- 5/1/89                       12
  245.   ______________________________________________________________________
  246.  
  247.   SEE ALSO:
  248.        bcp_batch,  bcp_colfmt,  bcp_collen,   bcp_colptr,   bcp_columns,
  249.        bcp_control,    bcp_done,   bcp_exec,   bcp_init,   bcp_moretext,
  250.        bcp_sendrow
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.