1 Version 4.0 -- 5/1/89 dbfcmd
______________________________________________________________________
NAME: dbfcmd
FUNCTION:
Add text to the DBPROCESS command buffer using C run-time library
sprintf-type formatting.
SYNTAX:
RETCODE dbfcmd(dbproc, cmdstring, args...)
DBPROCESS *dbproc;
char *cmdstring;
long args...;
dbfcmd Version 4.0 -- 5/1/89 2
______________________________________________________________________
COMMENTS:
o This routine adds text to the Transact-SQL command buffer in
the DBPROCESS structure. dbfcmd() works just like the C
language Standard I/O library sprintf() function, using %
conversion specifications. If you don't need any of the for-
matting capability of sprintf(), you can use dbcmd() instead.
o Since dbfcmd() calls sprintf(), you must remember that % 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 %. In addition, don't use variables containing
strings with apostrophes or single quotes.
o dbfcmd() 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 (see below). A single command buffer may
3 Version 4.0 -- 5/1/89 dbfcmd
______________________________________________________________________
contain multiple commands; in fact, this represents an effi-
cient use of the command buffer.
o 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.
o 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().
o Here's a small program fragment that uses dbfcmd() to build up
a multi-line SQL command:
dbfcmd Version 4.0 -- 5/1/89 4
______________________________________________________________________
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.
o Be sure to guard against passing a null pointer contained in a
variable to dbfcmd(). If a null value is a possibility, you
should check for it before using the variable with a dbfcmd()
call.
5 Version 4.0 -- 5/1/89 dbfcmd
______________________________________________________________________
o The application can intermingle calls to dbcmd() and dbfcmd().
o At any time, the application can access the contents of the
command buffer through calls to dbgetchar(), dbstrlen(), and
dbstrcpy().
PARAMETERS:
dbproc - A pointer to the DBPROCESS structure that provides the
connection for a particular front end/SQL Server process. It
contains all the information that DB-Library uses to manage
communications and data between the front end and SQL Server.
cmdstring - A format string of the form used by the sprintf()
routine.
args... - There is an optional and variable number of arguments
to dbfcmd(). The number of arguments required depends on the
number indicated in the cmdstring argument. The arguments
are passed directly to the sprintf() function.
dbfcmd Version 4.0 -- 5/1/89 6
______________________________________________________________________
RETURNS:
SUCCEED or FAIL.
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.
This routine 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 args are
very big in comparison to the size of cmdstring, there may not be
enough space allocated.
SEE ALSO:
dbcmd, dbfreebuf, dbgetchar, dbstrcpy, dbstrlen, options