Build a printable string from text containing placeholders for variables.
int dbstrbuild(dbproc, charbuf, bufsize,
text [, formats [, arg] ... ])
DBPROCESS *dbproc;
char *charbuf;
int bufsize;
char *text;
char *formats;
??? args...;
A pointer to the DBPROCESS 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 the server. dbstrbuild uses it only as a parameter to the programmer-installed error handler (if one exists) when an error occurs.
A pointer to the destination buffer that will contain the message built by dbstrbuild.
The size of the destination buffer, in bytes. This size must include a single byte for the results string’s null terminator.
A pointer to a null-terminated character string that contains message text and placeholders for variables. Placeholders consist of a percent sign, an integer, and an exclamation point. The integer indicates which argument to substitute for a particular placeholder. Arguments and format strings are numbered from left to right. Argument 1 is substituted for placeholder “%1!”, and so on.
A pointer to a null-terminated string containing one sprintf-style format specifier for each place holder in the text string.
The values that will be converted according to the contents of the formats string. There must be one argument for each format in the formats string. The first value will correspond to the “%1!” parameter, the second the “%2!”, and so forth. The results are undefined if there are insufficient arguments for the format. If the format is exhausted while arguments remain, the excess arguments are simply ignored.
On success, the length of the resulting message string, not including the null terminator; on failure, a negative integer.
Parameters in error messages can occur in different orders in different languages. dbstrbuild allows construction of error messages in a manner similar to the C standard-library sprintf routine. Use of dbstrbuild ensures easy translation of error messages from one language to another.
dbstrbuild builds a printable string from an error text that contains placeholders for variables, a format string containing information about the types and appearances of those variables, and a variable number of arguments that provide actual values for those variables.
Placeholders for variables consist of a percent sign, an integer, and an exclamation point. The integer indicates which argument to substitute for a particular placeholder. Arguments and format strings are numbered from left to right. Argument 1 is substituted for placeholder “%1!”, and so on.
For example, consider an error message that complains about a misused keyword in a stored procedure. The message requires three arguments: the misused keyword, the line in which the keyword occurs, and the name of the stored procedure in which the misuse occurs. In the English localization file, the message text might appear as:
The keyword ’%1!’ is misused in line %2! of stored
procedure ’%3!’ .
In the localization file, the same message might appear as:
In line ’%2!’ of stored procedure ’%3!’, the keyword ’%1!’ misused is.
The dbstrbuild line for either of the above messages would be:
dbstrbuild(dbproc, charbuf, BUFSIZE, <get the
message somehow>, "%s %d %s", keyword,
linenum, sp_name)
keyword is substituted for placeholder “%1!”, linenum is substituted for placeholder “%2!”, and sp_name is substituted for placeholder “%3!”.
The following code fragment illustrates the use of dbstrbuild to build messages. For simplicity, the text of the message is hard-coded. In practice, dbstrbuild message texts come from a localization file.
char charbuf[BUFSIZE];
int linenum = 15;
char *filename = "myfile";
char *dirname = "mydir";
dbstrbuild (dbproc, charbuf, BUFSIZE,
"Unable to read line %1! of file %2! in \
directory %3!.", "%d %s %s", linenum,
filename, dirname);
printf(charbuf);
dbstrbuild format specifiers may be separated by any other characters, or they may be adjacent to each other. This allows pre-existing English-language message strings to be used as dbstrbuild format parameters. The first format specifier describes the “%1!” parameter, the second the “%2!” parameter, and so forth.
