dbfcmd

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 thecmdstring 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 dbcmdinstead.

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 dbfcmdcalls 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 calldbfcmd 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, anddbstrcpy.

Available memory is the only constraint on the size of the DBPROCESS command buffer created by calls to dbcmd anddbfcmd.

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);

 

See Also

Bulk-Copy Functions

dbfreebuf

dbcmd

DB-Library Options