home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / usr / sybase / doc / dbsqlexec.man < prev    next >
Encoding:
Text File  |  1993-04-22  |  4.7 KB  |  133 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89                dbsqlexec
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  dbsqlexec
  6.  
  7.   FUNCTION:
  8.        Send a command batch to SQL Server.
  9.  
  10.   SYNTAX:
  11.        RETCODE dbsqlexec(dbproc)
  12.  
  13.        DBPROCESS *dbproc;
  14.  
  15.   COMMENTS:
  16.  
  17.        o This routine sends SQL commands, stored in the  command  buffer
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   dbsqlexec               Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.          of the DBPROCESS, to SQL Server.  Commands may be added to  the
  27.          DBPROCESS structure by calling dbcmd() or dbfcmd().
  28.  
  29.        o Once dbsqlexec() returns SUCCEED,  the  application  must  call
  30.          dbresults() to process the results.
  31.        o The typical sequence of calls is:
  32.  
  33.          DBINT        xvariable;
  34.          DBCHAR       yvariable[10];
  35.  
  36.          /* read the query into the command buffer */
  37.          dbcmd(dbproc, "select x = 100, y = 'hello'");
  38.  
  39.          /* send the query to SQL Server */
  40.          dbsqlexec(dbproc);
  41.  
  42.          /* get ready to process the results of the query */
  43.  
  44.  
  45.  
  46.   3                       Version 4.0 -- 5/1/89                dbsqlexec
  47.   ______________________________________________________________________
  48.          dbresults(dbproc);
  49.  
  50.          /* bind column data to program variables */
  51.          dbbind(dbproc, 1, INTBIND, (DBINT) 0, (BYTE *) &xvariable);
  52.          dbbind(dbproc, 2, STRINGBIND, (DBINT) 0, yvariable);
  53.  
  54.          /* now process each row */
  55.          while (dbnextrow(dbproc) != NO_MORE_ROWS)
  56.          {
  57.              C-code to print or process row data
  58.          }
  59.  
  60.  
  61.        o dbsqlexec() is equivalent to dbsqlsend() followed by dbsqlok().
  62.          However, after sending a query to SQL Server, dbsqlexec() waits
  63.          until a response is received or until the  timeout  period  has
  64.          elapsed.    By   substituting  dbsqlsend()  and  dbsqlok()  for
  65.          dbsqlexec(),  you  can  sometimes  provide  a   way   for   the
  66.  
  67.  
  68.   dbsqlexec               Version 4.0 -- 5/1/89                        4
  69.   ______________________________________________________________________
  70.          application to respond more effectively to multiple  input  and
  71.          output  streams.   See  the manual pages for those two routines
  72.          for more information.
  73.  
  74.  
  75.  
  76.  
  77.   PARAMETERS:
  78.        dbproc -  A pointer to the DBPROCESS structure that provides  the
  79.            connection for a particular front-end/SQL Server process.  It
  80.            contains all the information that DB-Library uses  to  manage
  81.            communications and data between the front end and SQL Server.
  82.  
  83.   RETURNS:
  84.        SUCCEED or FAIL.  The most common reason for  failing  is  a  SQL
  85.        syntax  error.   dbsqlexec() will also fail if there are semantic
  86.        errors, such as incorrect column or table names.  Failure  occurs
  87.        if any of the commands in the batch contains a semantic or syntax
  88.  
  89.  
  90.   5                       Version 4.0 -- 5/1/89                dbsqlexec
  91.   ______________________________________________________________________
  92.        error.  dbsqlexec() also fails if previous results had  not  been
  93.        processed, or if the command buffer was empty.
  94.  
  95.        In addition, a run-time error, such as a database protection vio-
  96.        lation, will cause dbsqlexec() to fail if the command buffer con-
  97.        tains only a single command.  If the command buffer contains mul-
  98.        tiple  commands,  a  run-time error will not cause dbsqlexec() to
  99.        fail.  Instead, failure will occur with the dbresults() call that
  100.        processes the command causing the run-time error.
  101.        The situation is a bit more complicated for run-time  errors  and
  102.        stored  procedures.   A  run-time error on an EXECUTE command may
  103.        cause dbsqlexec() to fail, in accordance with the rule  given  in
  104.        the previous paragraph.  A run-time error on a statement inside a
  105.        stored procedure will not cause  dbsqlexec()  to  fail,  however.
  106.        For example, if the stored procedure contains an INSERT statement
  107.        and the user does not have  insert  permission  on  the  database
  108.        table, the INSERT statement will fail, but dbsqlexec() will still
  109.  
  110.  
  111.  
  112.   dbsqlexec               Version 4.0 -- 5/1/89                        6
  113.   ______________________________________________________________________
  114.        return SUCCEED.  To check for run-time errors inside stored  pro-
  115.        cedures, use the dbretstatus() routine to look at the procedure's
  116.        return status, and trap relevant SQL Server messages inside  your
  117.        message handler.
  118.  
  119.   SEE ALSO:
  120.        dbcmd,  dbfcmd,  dbnextrow,  dbresults,  dbretstatus,  dbsettime,
  121.        dbsqlexec_a, dbsqlok, dbsqlsend
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.