dbfcmd

Adds text to the DBPROCESS command buffer using C run-time library sprintf-type formatting.

Syntax

RETCODE dbfcmd (
PDBPROCESS dbproc,
LPCSTR cmdstring,
... params );

where

dbproc: Is the DBPROCESS structure that is the handle for a particular workstation/ SQL Server 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 datatype 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 datatype long double.

Example

The following example shows how to use dbfcmd to build up a multiple-line SQL command. Please 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);

Limitations