home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / usr / sybase / doc / options.man < prev    next >
Encoding:
Text File  |  1993-04-22  |  9.4 KB  |  199 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89                  options
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  options
  6.  
  7.   FUNCTION:
  8.        The complete list of DB-Library options.
  9.  
  10.   SYNTAX:
  11.        #include <sybfront.h>
  12.        #include <sybdb.h>
  13.  
  14.   COMMENTS:
  15.  
  16.        o dbsetopt() and dbclropt() use the following constants,  defined
  17.          in  sybdb.h, for setting and clearing options.  All options are
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   options                 Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.          off by default.  These options are available:
  27.   DBPARSEONLY -  If this option is set, the SQL Server will  only  check
  28.       the  syntax  of  the  query and return error messages to the host.
  29.       Offsets will be returned if the DBOFFSET option is set  and  there
  30.       are no errors.
  31.   DBSHOWPLAN -  If this option is set, the SQL Server  will  generate  a
  32.       description  of the processing plan after compilation and continue
  33.       executing the query.
  34.   DBNOEXEC -  If this option is set, the  SQL Server  will  process  the
  35.       query through the compile step but the query will not be executed.
  36.       This can be used in conjunction with DBSHOWPLAN.
  37.   DBARITHABORT -  If this option is set, the  SQL Server  will  abort  a
  38.       query when an arithmetic exception occurs during its execution.
  39.   DBARITHIGNORE -  If this option is set, the SQL Server will substitute
  40.       null  values  for  selected  or  updated values when an arithmetic
  41.       exception occurs during query execution.  The SQL Server will  not
  42.       return   a   warning   message.    If   neither  DBARITHABORT  nor
  43.  
  44.  
  45.  
  46.   3                       Version 4.0 -- 5/1/89                  options
  47.   ______________________________________________________________________
  48.       DBARITHIGNORE is set, SQL Server will substitute null  values  and
  49.       print a warning message after the query has been executed.
  50.   DBNOCOUNT -  This option causes SQL Server to stop sending back infor-
  51.       mation  about  the  number of rows affected by each SQL statement.
  52.       The application can otherwise obtain this information  by  calling
  53.       DBCOUNT().
  54.   DBTEXTSIZE -  This option causes  SQL Server  to  limit  the  size  of
  55.       returned text or image values.  When setting this option, you sup-
  56.       ply a parameter which is the length, in bytes, of the longest text
  57.       or  image value that SQL Server should return.  Note that, in pro-
  58.       grams that allow application users to make  ad  hoc  queries,  the
  59.       user  may  override this option with the Transact-SQL SET TEXTSIZE
  60.       command.  To set a text limit that the user cannot  override,  use
  61.       the DBTEXTLIMIT option instead.
  62.   DBOFFSET -  This  option  indicates  where  SQL Server  should  return
  63.       offsets  to  certain  constructs  in  the query.  DBOFFSET takes a
  64.       parameter that specifies  the  particular  construct.   The  valid
  65.  
  66.  
  67.  
  68.   options                 Version 4.0 -- 5/1/89                        4
  69.   ______________________________________________________________________
  70.       parameters for this option are "select", "from", "table", "order",
  71.       "compute", "statement", "procedure", "execute", or "param".  (Note
  72.       that "param" refers to parameters of stored procedures.) Calls  to
  73.       routines such as dbsetopt() can specify these option parameters in
  74.       either  lower  or  upper  case.   For  the  internal  types   that
  75.       correspond  to  the offsets, see dbgetoff().  Offsets are returned
  76.       only if the batch contains no syntax errors.
  77.   DBSTAT -  This option  determines  when  performance  statistics  (CPU
  78.       time,  elapsed time, I/O, etc.) will be returned to the host after
  79.       each query.  DBSTAT takes one of two parameters: "io", for statis-
  80.       tics  about  SQL Server  internal I/O; and "time", for information
  81.       about SQL Server's  parsing,  compilation,  and  execution  times.
  82.       These  statistics are received by DB-Library in the form of infor-
  83.       mational  messages,  and  application  programs  can  access  them
  84.       through the user-supplied message handler.
  85.   DBSTORPROCID -  If this option is set, SQL Server will send the stored
  86.       procedure  id  to  the  host  before sending rows generated by the
  87.  
  88.  
  89.  
  90.   5                       Version 4.0 -- 5/1/89                  options
  91.   ______________________________________________________________________
  92.       stored procedure.
  93.   DBROWCOUNT -  If this option is set, the SQL Server will return only a
  94.       maximum  specified  number  of regular rows for SELECT statements.
  95.       This option does not limit the number of compute rows returned.
  96.  
  97.       DBROWCOUNT works somewhat differently from most  options.   It  is
  98.       always set on, never off.  Setting DBROWCOUNT to 0 sets it back to
  99.       the default-that is, to return all the rows generated by a  SELECT
  100.       statement.  Therefore, the way to turn DBROWCOUNT off is to set it
  101.       on with a count of  0.
  102.   DBBUFFER -  This option allows the application to buffer result  rows,
  103.       so  that  it  can  access them non-sequentially via the dbgetrow()
  104.       function.  This option is handled locally by DB-Library and is not
  105.       a SQL Server option.  When the option is set, you supply a parame-
  106.       ter which is the number of rows you want buffered.  If you  use  0
  107.       as  the  number  of  rows  to  buffer, the buffer will be set to a
  108.       default size (currently 1000).
  109.  
  110.  
  111.  
  112.   options                 Version 4.0 -- 5/1/89                        6
  113.   ______________________________________________________________________
  114.       Row buffering provides  a  way  to  keep  a  specified  number  of
  115.       SQL Server  result rows in program memory.  Without row buffering,
  116.       the result row generated by each new dbnextrow()  call  overwrites
  117.       the  contents of the previous result row.  Row buffering is there-
  118.       fore useful for programs that need to look at  result  rows  in  a
  119.       non-sequential  manner.  It does, however, carry a memory and per-
  120.       formance penalty because each row in the buffer must be  allocated
  121.       and  freed  individually.   Therefore, use it only if you need to.
  122.       Specifically, the application should only turn the DBBUFFER option
  123.       on if it calls dbgetrow().  Note that row buffering has nothing to
  124.       do with network buffering and is a completely  independent  issue.
  125.       (See  dbgetrow(), dbnextrow(), and dbclrbuf() for more information
  126.       about row buffering.)
  127.   DBNOAUTOFREE -  This option causes the command buffer  to  be  cleared
  128.       only by an explicit call to dbfreebuf().  When DBNOAUTOFREE is not
  129.       set, after a call to dbsqlexec() or dbsqlsend() the first call  to
  130.       either dbcmd() or dbfcmd() automatically clears the command buffer
  131.  
  132.  
  133.  
  134.   7                       Version 4.0 -- 5/1/89                  options
  135.   ______________________________________________________________________
  136.       before the new text is entered.
  137.   DBTEXTLIMIT -  This option causes DB-Library  to  limit  the  size  of
  138.       returned text or image values.  When setting this option, you sup-
  139.       ply a parameter which is the length, in bytes, of the longest text
  140.       or image value that your program can handle.  DB-Library will read
  141.       but ignore any part of a text or image value that goes  over  this
  142.       limit.  In the case of huge text values, it may take some time for
  143.       the entire text value to be returned over the  network.   To  keep
  144.       SQL Server  from  sending  this extra text in the first place, use
  145.       the DBTEXTSIZE option instead.
  146.  
  147.   o DBBUFFER, DBNOAUTOFREE,  and  DBTEXTLIMIT  are  DB-Library  options.
  148.     That  is, they affect DB-Library but are not sent to the SQL Server.
  149.     The other options  are  SQL Server  options-they  get  sent  to  the
  150.     SQL Server.    SQL Server   options   are   also   settable  through
  151.     Transact-SQL.
  152.   o As mentioned in the preceding  descriptions,  certain  options  take
  153.  
  154.  
  155.  
  156.   options                 Version 4.0 -- 5/1/89                        8
  157.   ______________________________________________________________________
  158.     parameters:
  159.  
  160.        Option               Possible parameter values
  161.  
  162.        DBTEXTSIZE           "0" to "2,147,483,647"
  163.  
  164.        DBOFFSET             "select", "from", "table", "order", "compute", "statement",
  165.                               "procedure", "execute", or "param"
  166.  
  167.        DBSTAT               "io" or "time"
  168.  
  169.        DBROWCOUNT           "0" to "2,147,483,647"
  170.  
  171.        DBBUFFER             "0" to either "32,767" or "2,147,483,647", depending on whether
  172.                               your int datatype is 2 or 4 bytes long
  173.  
  174.        DBTEXTLIMIT          "0" to "2,147,483,647"
  175.  
  176.  
  177.  
  178.   9                       Version 4.0 -- 5/1/89                  options
  179.   ______________________________________________________________________
  180.     dbsetopt() requires that an option parameter be specified when  set-
  181.     ting  any  option  on  the preceding list.  dbclropt() and dbisopt()
  182.     require that the  parameter  be  specified  only  for  DBOFFSET  and
  183.     DBSTAT.   This  is  because DBOFFSET and DBSTAT are the only options
  184.     that can have multiple settings at a time,  and  thus  they  require
  185.     further definition before being cleared or checked.
  186.  
  187.     Note that parameters specified in calls to  dbsetopt(),  dbclropt(),
  188.     and  dbisopt()  are  always  passed as character strings and must be
  189.     quoted, even if they are numeric values.  See the dbsetopt()  manual
  190.     page for more information.
  191.  
  192.   SEE ALSO:
  193.        dbclropt, dbisopt, dbsetopt
  194.  
  195.  
  196.  
  197.  
  198.  
  199.