Convert data from one datatype to another.
DBINT dbconvert(dbproc, srctype, src, srclen,
desttype, dest, destlen)
DBPROCESS *dbproc;
int srctype;
BYTE *src;
DBINT srclen;
int desttype;
BYTE *dest;
DBINT destlen;
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. In dbconvert, the DBPROCESS is used only to supply any custom null values that the program may have specified using dbsetnull. If dbproc is NULL, dbconvert uses the default values for null value data conversions.
The datatype of the data that is to be converted. This parameter can be any of the server datatypes, as listed below in Table 2-7.
A pointer to the data which is to be converted. If this pointer is NULL, dbconvert will place an appropriate null value in the destination variable. You can use dbdata to get the server data.
The length, in bytes, of the data to be converted. If the srclen is 0, the source data is assumed to be null and dbconvert will place an appropriate null value in the destination variable. Otherwise, this length is ignored for all datatypes except char, text, binary, and image. For SYBCHAR, SYBBOUNDARY, and SYBSENSITIVITY data, a length of -1 indicates that the string is null-terminated. You can use dbdatlen to get the length of the server data.
The datatype that the source data is to be converted into. This parameter can be any of the server datatypes, as listed below in Table 2-7.
A pointer to the destination variable that will receive the converted data. If this pointer is NULL, dbconvert will call the user-supplied error handler (if any) and return -1.
The length, in bytes, of the destination variable. destlen is ignored for fixed-length datatypes. For a SYBCHAR, SYBBOUNDARY or SYBSENSITIVITY destination, the value of destlen must be the total length of the destination buffer space.
Table 2-5 describes special values for destlen:
Value of destlen |
Applicable to |
Meaning |
|---|---|---|
-1 |
SYBCHAR, SYBBOUNDARY, SBYSENSITIVITY |
There is sufficient space available. The string will be trimmed of trailing blanks and given a terminating null. |
-2 |
SYBCHAR |
There is sufficient space available. The string will not be trimmed of trailing blanks, but will be given a terminating null. |
The length of the converted data, in bytes, if the datatype conversion succeeds.
If the conversion fails, dbconvert returns either -1 or FAIL, depending on the cause of the failure. dbconvert returns -1 to indicate a NULL destination pointer or an illegal datatype. dbconvert returns FAIL to indicate other types of failures.
If dbconvert fails, it will first call a user-supplied error handler (if any) and set the global DB-Library error value.
This routine may fail for several reasons: the requested conversion was not available; the conversion resulted in truncation, overflow, or loss of precision in the destination variable; or a syntax error occurred in converting a character string to some numeric type.
This routine allows the program to convert data from one representation to another. To determine whether a particular conversion is permitted, the program can call dbwillconvert before attempting a conversion.
dbconvert can convert data stored in any of the server datatypes (although, of course, not all conversions are legal). See Table 2-7 for a list of type constants and corresponding program variable types.
It is an error to use the following datatypes with dbconvert if the library version has not been set (with dbsetversion) to DBVERSION_100 or higher: SYBNUMERIC, SYBDECIMAL, SYBBOUNDARY, and SYBSENSITIVITY.
Table 2-8 lists the datatype conversions that dbconvert supports. The source datatypes are listed down the leftmost column and the destination datatypes are listed along the top row of the table. (For brevity, the prefix “SYB” has been eliminated from each datatype.) T (“True”) indicates that the conversion is supported; F (“False”) indicates that the conversion is not supported.
A conversion to or from the datatypes SYBBINARY and SYBIMAGE is a straight bit-copy, except when the conversion involves SYBCHAR or SYBTEXT. When converting SYBCHAR or SYBTEXT data to SYBBINARY or SYBIMAGE, DBCONVERT interprets the SYBCHAR or SYBTEXT string as hexadecimal, whether or not the string contains a leading “0x”. When converting SYBBINARY or SYBIMAGE data to SYBCHAR or SYBTEXT, dbconvert creates a hexadecimal string without a leading “0x”.
Note that SYBINT2 and SYBINT4 are signed types. When converting these types to character, conversion error can result if the quantity being converted is unsigned and uses the high bit.
Converting a SYBMONEY, SYBCHAR, or SYBTEXT value to SYBFLT8 may result in some loss of precision. Converting a SYBFLT8 value to SYBCHAR or SYBTEXT may also result in some loss of precision.
Converting a SYBFLT8 value to SYBMONEY can result in overflow, because the maximum value for SYBMONEY is $922,337,203,685,477.58.
If overflow occurs when converting integer or float data to SYBCHAR or SYBTEXT, the first character of the resulting value will contain an asterisk (*) to indicate the error.
A conversion to SYBBIT has the following effect: If the value being converted is not 0, the SYBBIT value will be set to 1; if the value is 0, the SYBBIT value will be set to 0.
dbconvert does not offer precision and scale support for numeric and decimal datatypes. When converting to SYBNUMERIC or SYBDECIMAL, dbconvert uses a default precision and scale of 18 and 0, respectively. To specify a different precision and scale, an application can use dbconvert_ps.
SYBBOUNDARY and SYBSENSITIVITY destinations are always null-terminated.
In certain cases, it can be useful to convert a datatype to itself. For instance, a conversion of SYBCHAR to SYBCHAR with a destlen of -1 serves as a useful way to append a null terminator to a string, as the example below illustrates.
Here is a short example that illustrates how to convert server data obtained with dbdata:
DBCHAR title[81];
DBCHAR price[9];
/* Read the query into the command buffer */
dbcmd(dbproc, "select title, price, royalty from \
pubs2..titles");
/* Send the query to Adaptive Server Enterprise */
dbsqlexec(dbproc);
/* Get ready to process the query results */
dbresults(dbproc);
/* Process each row */
while (dbnextrow(dbproc) != NO_MORE_ROWS)
{
/*
** The first dbconvert() adds a null
** terminator to the string.
*/
dbconvert(dbproc, SYBCHAR, (dbdata(dbproc,1)),
(dbdatlen(dbproc,1)), SYBCHAR, title,
(DBINT)-1);
/*
** The second dbconvert() converts money to
** string.
*/
dbconvert(dbproc, SYBMONEY,
(dbdata(dbproc,2)), (DBINT)-1, SYBCHAR,
price, (DBINT)-1);
if (dbdatlen(dbproc,3) != 0)
printf ("%s\n $%s %ld\n", title, price,
*((DBINT *)dbdata(dbproc,3)));
}
In the dbconvert calls it was not necessary to cast the returns from dbdata, because dbdata returns a BYTE pointer—precisely the datatype dbconvert expects in the third parameter.
If you are binding data to variables with dbbind rather than accessing the data directly with dbdata, dbbind can perform the conversions itself, making dbconvert unnecessary.
The sample program example5.c illustrates several more types of conversions using dbconvert.
See Types for a list of DB-Library datatypes and the corresponding Adaptive Server Enterprise datatypes. See the Adaptive Server Enterprise Reference Manual.
dbaltbind, dbaltbind_ps, dbbind, dbbind_ps, dbconvert_ps, dberrhandle, dbsetnull, dbsetversion, dbwillconvert, Errors, Types
