dbfcmd

Description

Add text to the DBPROCESS command buffer using C runtime library sprintf-type formatting.

Syntax

RETCODE dbfcmd(dbproc, cmdstring, args...)
 
DBPROCESS     *dbproc;
char                    *cmdstring;
???                     args...;

Parameters

dbproc: A pointer to the DBPROCESS structure that provides the connection for a particular front end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server.

cmdstring: A format string of the form used by the sprintf routine.

There is an optional and variable number of arguments to dbfcmd. The number and type of arguments required depends on the format specifiers included in the cmdstring argument. The arguments are passed directly to the C-library sprintf function. Neither dbfcmd nor the C compiler can type check these arguments. As with using sprintf, the programmer must ensure that each argument type matches the corresponding format specifier.

Returns

SUCCEED or FAIL.

Usage

This routine adds text to the Transact-SQL command buffer in the DBPROCESS structure. dbfcmd works just like the sprintf function in the C language standard I/O library, using % conversion specifiers. If you do not need any of the formatting capability of sprintf, you can use dbcmd instead.

Table 2-20 lists the conversions supported by dbfcmd:

**Table 2-20: dbfcmd conversions**
Conversion	Program variable type
%s	char*, null-terminated
%d	int, decimal representation
%f	double
%g	double
%e	double
%%	None, the “%” character is written into the command buffer

The datatype SYBDATETIME must be converted to a character string and passed using %s. The datatype SYBMONEY may be converted to a character string and passed using %s, or converted to float and passed using %f.

Currently, only eight arguments may be handled in each call to dbfcmd. To format commands that require more than eight arguments, call dbfcmd repeatedly.

dbfcmd manages the space allocation for the command buffer. It adds to the existing command buffer—it does not delete or overwrite the current contents except after the buffer has been sent to the server (see “Clearing the command buffer”). A single command buffer may contain multiple commands; in fact, this represents an efficient use of the command buffer.
The application may call dbfcmd repeatedly. The command strings in sequential calls are just concatenated together. It is the program’s responsibility to ensure that any necessary blanks appear between the end of one string and the beginning of the next.

Here is a small program fragment that uses dbfcmd to build up a multiline SQL command:

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

Note the required spaces at the start of the second and third command strings.

When passing character or string variables to dbfcmd, beware of variables that contain quotes (single or double) or null characters (ASCII 0).
- Improperly placed quotes in the SQL command can cause SQL syntax errors or, worse yet, unanticipated query results.
- NULL characters (ASCII 0) should never be inserted into the command buffer. They can confuse DB-Library and the server, causing SQL syntax errors or unanticipated query results.
Since dbfcmd calls sprintf, you must remember that % (percentage sign) has a special meaning as the beginning of a format command. If you want to include % in the command string, you must precede it with another %.
Be sure to guard against passing a null pointer as a string parameter to dbfcmd. If a null value is a possibility, you should check for it before using the variable in a dbfcmd call.
The application can intermingle calls to dbcmd and dbfcmd.
At any time, the 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.

Clearing the command buffer

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 an explicit call to dbfreebuf.

Limitations

Currently, only eight args may be handled in each call to dbfcmd. To format commands that require more than eight args, call dbfcmd repeatedly. On some platforms, dbfcmd may allow more than eight args per call. For portable code, do not pass more than eight arguments.

Because it makes text substitutions, dbfcmd uses a working buffer in addition to the DBPROCESS command buffer. dbfcmd allocates this working buffer dynamically. The size of the space it allocates is equal to the maximum of a defined constant (1024) or the string length of cmdstring *2 . For example, if the length of cmdstring is 600 bytes, dbfcmd allocates a working buffer 1200 bytes long. If the length of cmdstring is 34 bytes, dbfcmd allocates a working buffer 1024 bytes long. To work around this limitation:

sprintf (buffer, “%s”, SQL commmand”);

dbcmd (dbproc, buffer)

If the args are very big in comparison to the size of cmdstring, the working buffer may not be large enough to hold the string after substitutions are made. In this situation, break cmdstring up and use multiple calls to dbfcmd.

Note that the working buffer is not the same as the DBPROCESS command buffer. The working buffer is a temporary buffer used only by dbfcmd when making text substitutions. The DBPROCESS command buffer holds the text after substitutions have been made. There is no constraint, other than available memory, on the size of the DBPROCESS command buffer.