Constructs native language message strings.
CS_RETCODE cs_strbuild(context, buffer, buflen,
resultlen, text, textlen
[, formats, formatlen]
[, arguments]);
CS_CONTEXT *context;
CS_CHAR *buffer;
CS_INT buflen;
CS_INT *resultlen;
CS_CHAR *text;
CS_INT textlen;
CS_CHAR *formats; /* Optional */
CS_INT formatlen; /* Optional */
<optional arguments>
A pointer to a CS_CONTEXT structure.
A pointer to the space in which cs_strbuild places the finished message. Note that the finished message is not null-terminated. An application must use *resultlen to determine the length of the message placed in *buffer.
The length, in bytes, of the *buffer data space.
A pointer to an integer variable. cs_strbuild sets *resultlen to the length, in bytes, of the string placed in *buffer.
A pointer to the unfinished text of the message. The *text string contains message text and placeholders for variables. A placeholder has the form %integer!, for example, %1!, %2!, and so forth. The integer indicates which argument to substitute for a particular placeholder. Arguments are numbered from left to right.
The length, in bytes, of *text. If *text is null-terminated, pass textlen as CS_NULLTERM.
A pointer to a string containing one sprintf-style format specifier for each place holder in the *text string.
The length, in bytes, of *formats. If *formats is null-terminated, pass formatlen as CS_NULLTERM.
The values which will be converted to character according to the *formats string and substituted into the *text string to produce the message that is placed in *buffer.
There must be one argument for each place holder. The first value corresponds to the first format and the %1! placeholder, the second value corresponds to the second format and the %2! placeholder, and so forth.
If insufficient arguments are supplied, cs_strbuild generates unpredictable results.
If too many arguments are supplied, the excess arguments are ignored.
cs_str_build returns:
Returns |
Indicates |
|---|---|
CS_SUCCEED |
The routine completed successfully. |
CS_FAIL |
The routine failed. |
cs_strbuild builds a printable native-language message string from a text containing place holders for values, a format string containing information on the types and appearances of the values, and a variable number of arguments that represent the values.
Parameters in error messages can occur in different orders in different languages. cs_strbuild allows an application to construct error messages in a sprintf-like fashion to ensure easy translation of error messages from one language to another.
For example, consider an error message that informs the user of 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 the U.S. English localization file, the message text appears as:
The keyword ‘%1!‘ is misused in line %2! of stored procedure ‘%3!‘.
In the Spanish localization file, the same message appears as:
En linea %2! de stored procedure ‘%3!‘, la palabra ‘%1!‘ esta mal usado!
The cs_strbuild call for either of the above messages is:
cs_strbuild(context, &mybuffer, buflength,
&resultlength, messagetext, CS_NULLTERM,
“%s, %d, %s”, CS_NULLTERM,
keyword, linenum, sp_name);
The only difference is the content of messagetext.
cs_strbuild format specifiers can be separated by other characters, or they can be adjacent to each other. This allows existing message strings in U.S. English to be used as format parameters. The first format specifier describes the %1! placeholder, the second describes the %2! placeholder, and so forth.
