home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / usr / sybase / doc / dbsqlok.man < prev    next >
Encoding:
Text File  |  1993-04-22  |  6.6 KB  |  155 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89                  dbsqlok
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  dbsqlok
  6.  
  7.   FUNCTION:
  8.        Wait for results from the SQL Server and verify  the  correctness
  9.        of the instructions the SQL Server is responding to.
  10.  
  11.   SYNTAX:
  12.        RETCODE dbsqlok(dbproc)
  13.  
  14.        DBPROCESS *dbproc;
  15.  
  16.   COMMENTS:
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   dbsqlok                 Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.  
  27.        o This routine waits for results from the SQL Server and verifies
  28.          the  correctness  of  the  instructions  that the SQL Server is
  29.          responding to.
  30.          The "instructions that the SQL Server is responding to" can  be
  31.          any of the following:
  32.  
  33.           o A command batch (when dbsqlok() is used with dbsqlsend()).
  34.           o Processing information for handling chunks of text or  image
  35.             data (when dbsqlok() is used with dbmoretext()).
  36.  
  37.           o A  remote  procedure  call  (when  dbsqlok()  is  used  with
  38.             dbrpcsend()).
  39.        o The application must call dbsqlok() after a call to dbsqlsend()
  40.          or  dbrpcsend(),  and  before  and  after a set of dbmoretext()
  41.          calls.  A successful dbsqlok() call must always be followed  by
  42.          a call to dbresults() to process the results.
  43.  
  44.  
  45.  
  46.   3                       Version 4.0 -- 5/1/89                  dbsqlok
  47.   ______________________________________________________________________
  48.  
  49.        o dbsqlexec() is equivalent to dbsqlsend() followed by dbsqlok().
  50.        o The use of dbsqlsend() with dbsqlok() is of particular value in
  51.          UNIX  applications.   After  sending  a  query  to  SQL Server,
  52.          dbsqlexec() waits until a response is  received  or  until  the
  53.          timeout  period  has  elapsed.  By substituting dbsqlsend() and
  54.          dbsqlok() for dbsqlexec(), you can sometimes provide a way  for
  55.          a  UNIX  application  to  respond  more effectively to multiple
  56.          input and output streams.  The time  between  the  request  for
  57.          information  from  SQL Server  (made via a call to dbsqlsend())
  58.          and SQL Server's response (read by calling  dbsqlok())  can  be
  59.          used,  in  conjunction with DBIORDESC() or DBIOWDESC(), to ser-
  60.          vice  other  parts  of  the   application.    DBIORDESC()   and
  61.          DBIOWDESC()  are available for UNIX only.  See the manual pages
  62.          for those two routines for more information.
  63.  
  64.          To manage input data streams efficiently,  a  UNIX  application
  65.          using dbsqlok() should confirm that unread bytes are available,
  66.  
  67.  
  68.   dbsqlok                 Version 4.0 -- 5/1/89                        4
  69.   ______________________________________________________________________
  70.          either in the DB-Library network buffer (by  calling  DBRBUF())
  71.          or  in  the  network itself (by calling the UNIX select() func-
  72.          tion), before calling dbresults().
  73.  
  74.          For a UNIX example that illustrates the use of  dbsqlok()  with
  75.          dbsqlsend(),  DBRBUF(),  DBIORDESC(),  and DBIOWDESC(), see the
  76.          DB-Library Reference Supplement.
  77.          On occasion the operating system  may  inform  the  application
  78.          that  data  is  ready for dbsqlok() to read when only the first
  79.          part of the SQL Server response is present.  When this  occurs,
  80.          dbsqlok()  waits  for  the  rest  of  the response or until the
  81.          timeout period has elapsed, just like  dbsqlexec().   In  prac-
  82.          tice,  however, the entire response is usually available at one
  83.          time.
  84.  
  85.        o dbsqlok() is also  useful  in  text  update  operations.   When
  86.          chunks  of  text  are  sent to SQL Server via dbwritetext() and
  87.          dbmoretext(), dbsqlok() must be called before the first call to
  88.  
  89.  
  90.   5                       Version 4.0 -- 5/1/89                  dbsqlok
  91.   ______________________________________________________________________
  92.          dbmoretext() and after the last call to dbmoretext().   For  an
  93.          example  of  its  use  in this context, see the manual page for
  94.          dbwritetext().
  95.  
  96.        o dbsqlok() is also necessary when making remote procedure calls.
  97.          The  application  must  call  it  after  dbrpcsend() and before
  98.          dbresults().
  99.  
  100.   PARAMETERS:
  101.        dbproc -  A pointer to the DBPROCESS structure that provides  the
  102.            connection for a particular front-end/SQL Server process.  It
  103.            contains all the information that DB-Library uses  to  manage
  104.            communications and data between the front end and SQL Server.
  105.  
  106.   RETURNS:
  107.        SUCCEED or FAIL. The most common reason for failing is a SQL syn-
  108.        tax  error.   dbsqlok()  will  also  fail  if  there are semantic
  109.        errors, such as incorrect column or table names.  Failure  occurs
  110.  
  111.  
  112.   dbsqlok                 Version 4.0 -- 5/1/89                        6
  113.   ______________________________________________________________________
  114.        if any of the commands in the batch contains a semantic or syntax
  115.        error.
  116.  
  117.        In addition, a run-time error, such as a database protection vio-
  118.        lation,  will  cause dbsqlok() to fail if the command buffer con-
  119.        tains only a single command.  If the command buffer contains mul-
  120.        tiple  commands,  a  run-time  error  will not cause dbsqlok() to
  121.        fail.  Instead, failure will occur with the dbresults() call that
  122.        processes the command causing the run-time error.
  123.        The situation is a bit more complicated for run-time  errors  and
  124.        stored  procedures.   A  run-time error on an EXECUTE command may
  125.        cause dbsqlok() to fail, in accordance with the rule given in the
  126.        previous  paragraph.   A  run-time  error on a statement inside a
  127.        stored procedure will not cause dbsqlok() to fail, however.   For
  128.        example, if the stored procedure contains an INSERT statement and
  129.        the user does not have insert permission on the  database  table,
  130.        the  INSERT  statement will fail, but dbsqlok() will still return
  131.  
  132.  
  133.  
  134.   7                       Version 4.0 -- 5/1/89                  dbsqlok
  135.   ______________________________________________________________________
  136.        SUCCEED.  To check for run-time errors inside stored  procedures,
  137.        use  the  dbretstatus() routine to look at the procedure's return
  138.        status, and trap relevant SQL Server messages inside your message
  139.        handler.
  140.  
  141.   SEE ALSO:
  142.        dbcmd,  dbfcmd,  DBIORDESC,  DBIOWDESC,  dbmoretext,   dbnextrow,
  143.        DBRBUF,  dbresults, dbretstatus, dbrpcsend, dbsettime, dbsqlexec,
  144.        dbsqlsend, dbwritetext
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.