dbfcmd
Adds text to the DBPROCESS command buffer using C run-time library sprintf-type formatting.
Syntax
RETCODE dbfcmd (
PDBPROCESS dbproc,
LPCSTR cmdstring,
... params );
Arguments
dbproc
Is the DBPROCESS structure that is the handle for a particular workstation or Microsoft® SQL Server™ 2000 process. It contains all the information that DB-Library uses to manage communications and data between the workstation and SQL Server.
cmdstring
Is a format string of the form used by the sprintf function.
params
Are optional parameters to dbfcmd. The number of parameters required depends on the number indicated in the cmdstring parameter. The parameters are passed directly to the sprintf function.
Returns
SUCCEED or FAIL.
Remarks
This function adds text to the command buffer in the DBPROCESS structure. The dbfcmd function works just like the C-language standard I/O library sprintf function. If you don't need any of the formatting capability of sprintf, use dbcmd instead.
The following table lists the conversions supported by dbfcmd.
| Conversion | Program variable type |
|---|---|
| %c | char |
| %s | null-terminated string |
| %d | int |
| %f | double |
| %g | double |
| %e | double |
| %% | none |
| %c | char |
| %x | unsigned hexadecimal integer string |
| %u | unsigned decimal |
The data type SQLDATETIME must be converted into a character string and passed, using %s. SQLMONEY can be converted to a character string and passed, using %s, or it can be converted to float and passed, using %f.
To include a percent character (%) in the command string, encode it as two percent characters (%%) because dbfcmd calls sprintf, which treats the % character as a format specification. In addition, don't use variables containing strings with apostrophes or single quotation marks because they conflict with the SQL statement syntax if there is any. If you don't need any of the formatting capability of sprintf, you can use dbcmd.
The dbfcmd function manages the space allocation for the command buffer. It adds to the existing command buffer; it doesn't delete or overwrite the current contents except after the buffer has been sent to SQL Server. You can call dbfcmd repeatedly. Note that sequential calls are concatenated: The application must make sure that any necessary blanks appear between the end of one line and the beginning of the next.
After a call to dbsqlexec or dbsqlsend, the first call to either dbcmd or dbfcmd automatically clears the command buffer before the new text is entered. If this situation is undesirable, set the DBNOAUTOFREE option. When DBNOAUTOFREE is set, the command buffer is cleared only by a call to dbfreebuf.
Do not pass dbfcmd null pointers contained in variables.
An application can intermingle calls to dbcmd and dbfcmd.
At any time, an application can access the contents of the command buffer through calls to dbgetchar, dbstrlen, and dbstrcpy.
Available memory is the only constraint on the size of the DBPROCESS command buffer created by calls to dbcmd and dbfcmd.
This function does not support the C data type long double.
This function allocates its working buffer dynamically. The size it picks to allocate space is the maximum of a defined constant (1024) and the string length of cmdstring * 2. If the arguments are big in comparison to the size of cmdstring, DB-Library may not be able to allocate enough space.
Examples
The following example shows how to use dbfcmd to build up a multiple-line SQL command. Note the leading spaces.
char *column_name;
DBPROCESS *dbproc;
int low_id;
char *object_type;
char *tablename;
dbfcmd(dbproc, "SELECT %s FROM %s", column_name, tablename);
dbfcmd(dbproc, " WHERE id > %d", low_id);
dbfcmd(dbproc, " AND type='%s'", object_type);