home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / usr / sybase / doc / dbfcmd.man < prev    next >
Encoding:
Text File  |  1993-04-22  |  5.2 KB  |  133 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89                   dbfcmd
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  dbfcmd
  6.  
  7.   FUNCTION:
  8.        Add text to the DBPROCESS command buffer using C run-time library
  9.        sprintf-type formatting.
  10.  
  11.   SYNTAX:
  12.        RETCODE dbfcmd(dbproc, cmdstring, args...)
  13.  
  14.        DBPROCESS *dbproc;
  15.        char      *cmdstring;
  16.        long      args...;
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   dbfcmd                  Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.  
  27.   COMMENTS:
  28.  
  29.        o This routine adds text to the Transact-SQL  command  buffer  in
  30.          the  DBPROCESS  structure.   dbfcmd()  works  just  like  the C
  31.          language Standard  I/O  library  sprintf()  function,  using  %
  32.          conversion  specifications.   If you don't need any of the for-
  33.          matting capability of sprintf(), you can use dbcmd() instead.
  34.        o Since dbfcmd() calls sprintf(), you must remember that % has  a
  35.          special  meaning  as the beginning of a format command.  If you
  36.          want to include % in the command string, you  must  precede  it
  37.          with  another  %.   In addition, don't use variables containing
  38.          strings with apostrophes or single quotes.
  39.  
  40.        o dbfcmd() manages the space allocation for the  command  buffer.
  41.          It  adds  to  the  existing command buffer-it doesn't delete or
  42.          overwrite the current contents except after the buffer has been
  43.          sent  to  SQL Server  (see below).  A single command buffer may
  44.  
  45.  
  46.   3                       Version 4.0 -- 5/1/89                   dbfcmd
  47.   ______________________________________________________________________
  48.          contain multiple commands; in fact, this  represents  an  effi-
  49.          cient use of the command buffer.
  50.  
  51.        o The application may  call  dbfcmd()  repeatedly.   The  command
  52.          strings  in sequential calls are just concatenated together. It
  53.          is the program's responsibility to ensure  that  any  necessary
  54.          blanks  appear  between the end of one string and the beginning
  55.          of the next.
  56.        o After a call to dbsqlexec() or dbsqlsend(), the first  call  to
  57.          either  dbcmd()  or  dbfcmd()  automatically clears the command
  58.          buffer before the new text is entered.  If  this  situation  is
  59.          undesirable, set the DBNOAUTOFREE option.  When DBNOAUTOFREE is
  60.          set, the command buffer is cleared only by an explicit call  to
  61.          dbfreebuf().
  62.  
  63.        o Here's a small program fragment that uses dbfcmd() to build  up
  64.          a multi-line SQL command:
  65.  
  66.  
  67.  
  68.   dbfcmd                  Version 4.0 -- 5/1/89                        4
  69.   ______________________________________________________________________
  70.          char            *column_name;
  71.          DBPROCESS       *dbproc;
  72.          int             low_id;
  73.          char            *object_type;
  74.          char            *tablename;
  75.  
  76.          dbfcmd(dbproc, "select %s from %s", column_name, tablename);
  77.          dbfcmd(dbproc, " where id > %d", low_id);
  78.          dbfcmd(dbproc, " and type='%s'", object_type);
  79.  
  80.          Note the required spaces at the start of the second  and  third
  81.          command strings.
  82.  
  83.        o Be sure to guard against passing a null pointer contained in  a
  84.          variable  to  dbfcmd().   If a null value is a possibility, you
  85.          should check for it before using the variable with  a  dbfcmd()
  86.          call.
  87.  
  88.  
  89.  
  90.   5                       Version 4.0 -- 5/1/89                   dbfcmd
  91.   ______________________________________________________________________
  92.        o The application can intermingle calls to dbcmd() and dbfcmd().
  93.  
  94.        o At any time, the application can access  the  contents  of  the
  95.          command  buffer  through  calls to dbgetchar(), dbstrlen(), and
  96.          dbstrcpy().
  97.  
  98.   PARAMETERS:
  99.        dbproc -  A pointer to the DBPROCESS structure that provides  the
  100.            connection for a particular front end/SQL Server process.  It
  101.            contains all the information that DB-Library uses  to  manage
  102.            communications and data between the front end and SQL Server.
  103.        cmdstring -  A format string of the form used  by  the  sprintf()
  104.            routine.
  105.        args... -  There is an optional and variable number of  arguments
  106.            to dbfcmd().  The number of arguments required depends on the
  107.            number indicated in the cmdstring  argument.   The  arguments
  108.            are passed directly to the sprintf() function.
  109.  
  110.  
  111.  
  112.   dbfcmd                  Version 4.0 -- 5/1/89                        6
  113.   ______________________________________________________________________
  114.  
  115.   RETURNS:
  116.        SUCCEED or FAIL.
  117.  
  118.   LIMITATIONS:
  119.        Currently, only eight  args  may  be  handled  in  each  call  to
  120.        dbfcmd().   To format commands that require more than eight args,
  121.        call dbfcmd() repeatedly.
  122.  
  123.        This routine allocates its working buffer dynamically.  The  size
  124.        it  picks  to allocate space is the maximum of a defined constant
  125.        (1024) and the string length of cmdstring * 2.  If the  args  are
  126.        very big in comparison to the size of cmdstring, there may not be
  127.        enough space allocated.
  128.  
  129.   SEE ALSO:
  130.        dbcmd, dbfreebuf, dbgetchar, dbstrcpy, dbstrlen, options
  131.  
  132.  
  133.