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