dbconvert

Converts data from one data type to another.

Syntax

INT dbconvert (
PDBPROCESS dbproc,
INT srctype,
LPCBYTE src,
DBINT srclen,
INT desttype,
LPBYTE dest,
DBINT destlen );

Arguments

dbproc

Is the DBPROCESS structure that is the handle for a particular workstation/ Microsoft® SQL Server™ process. It contains all the information that DB-Library uses to manage communications and data between the workstation and SQL Server.

In dbconvert, the DBPROCESS is used only to supply any custom null values that the program specified through dbsetnull. If dbproc is NULL, dbconvert uses the default values for null value data conversions.

srctype

Is the data type of the source data to be converted. This parameter can be any of the SQL Server data type tokens. You can use dbcoltype to get the SQL Server data type token for a particular column.

src

Is a pointer to the source data to be converted. If this pointer is NULL, dbconvert puts an appropriate null value in the destination variable. You can use dbdata to get a pointer to data from a SQL Server column.

When srctype is SQLDECIMAL or SQLNUMERIC, the src parameter must be a pointer to a valid DBNUMERIC or DBDECIMAL C variable, respectively.

srclen

Is the length, in bytes, of the source data to be converted. This length is used for the following srctype data type tokens:

• SQLCHAR, SQLVARCHAR, SQLTEXT
• SQLBINARY, SQLVARBINARY, SQLIMAGE
• SQLINTN, SQLFLTN, SQLMONEYN, SQLDATETIMN

This length is ignored for all fixed-length, non-NULL data types. If srclen is 0, the source data is assumed to be null, and dbconvert places an appropriate null value in the destination variable. You can use dbdatlen to get the length of SQL Server data.

When src points to a DBCHAR string, a srclen of -1 indicates that the string is null-terminated.

desttype

Is the destination data type that the source data is to be converted into. This parameter can be any of the SQL Server data type tokens.

dest

Is a pointer to the destination variable that will receive the converted data. If this pointer is NULL, dbconvert calls the user-supplied error handler (if any) and returns -1.

When desttype is SQLDECIMAL or SQLNUMERIC, the dest parameter must be a pointer to a DBNUMERIC or DBDECIMAL C variable, respectively, with the precision and scale fields of the structure already set to the desired values. You can use DEFAULTPRECISION to specify a default precision and DEFAULTSCALE to specify a default scale.

destlen

Is the length, in bytes, of the destination variable. This length is used for the following desttype data type tokens:

• SQLCHAR, SQLVARCHAR, SQLTEXT
• SQLBINARY, SQLVARBINARY, SQLIMAGE
• SQLINTN, SQLFLTN, SQLMONEYN, SQLDATETIMN

The destlen is ignored for all fixed-length, non-NULL data types.

When dest points to a DBCHAR string or a DBBINARY array, the value of destlen must be the total length of the destination buffer space, or -1 to indicate that there is sufficient space available. Note that when dest points to a DBCHAR string, a destlen of -1 causes the character string to be given a terminating null.

Returns

The length of the converted data, in bytes, if the data type conversion succeeds. If the conversion fails, -1 is returned. If dbconvert fails, it first calls a user-supplied error handler (if any). This routine may fail for one of these reasons:

• The requested conversion was unavailable.
• The conversion resulted in truncation, overflow, or loss of precision in the destination variable.
• A syntax error occurred while converting a character string to some numeric type.

Remarks

This function allows the application 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.

The dbconvert function can convert data stored in any of the SQL Server data types (although not all conversions are legal). The following table shows the program variable type (src or dest parameters) you must provide for each non-NULL SQL Server data type (srctype or desttype parameters):

The following table shows the program variable type (src or dest parameters) you must provide for each fixed-length SQL Server data type (srctype or desttype parameters) that allows NULL values and valid byte length (srclen or destlen parameters):

Conversion to and from all SQL Server data types is supported, except for conversion between SQLDATETIME or SQLDATETIM4 and the following data types:

• SQLINT1, SQLINT2, SQLINT4
• SQLFLT4, SQLFLT8
• SQLBIT
• SQLMONEY, SQLMONEY4
• SQLDECIMAL, SQLNUMERIC

A conversion to or from the data types SQLBINARY and SQLIMAGE is a straight bit-copy unless the conversion involves SQLCHAR or SQLTEXT. When converting SQLCHAR or SQLTEXT data to SQLBINARY or SQLIMAGE, dbconvert interprets the SQLCHAR or SQLTEXT string as hexadecimal digits, whether or not the string contains a leading 0x. When converting SQLBINARY or SQLIMAGE data to SQLCHAR or SQLTEXT, dbconvert creates a string of hexadecimal digits without a leading 0x.

Converting to the approximate numeric data types SQLFLT4 or SQLFLT8 can result in some loss of precision. Converting from the approximate numeric data types SQLFLT4 or SQLFLT8 to SQLCHAR or SQLTEXT can also result in some loss of precision.

Converting to SQLFLTx, SQLINTx, SQLMONEY, SQLMONEY4, SQLDECIMAL, or SQLNUMERIC can result in overflow if the number is larger than the destination’s maximum value, or in underflow if the number is smaller than the destination’s minimum value. If overflow occurs when converting to SQLCHAR or SQLTEXT, the first character of the resulting value contains an asterisk (*) to indicate the error.

When binding data to variables rather than accessing the data directly, use dbbind to convert instead of dbconvert.

For the Microsoft Windows® operating system, DB-Library retrieves information about date, time, numeric, and currency formatting from the Sqlcommn.loc file. The location of Sqlcommn.loc is pointed to by the SQLLocalizationFile key in the Windows initialization file (Win.ini) under the [SQLSERVER] application heading. For example:

[SQLSERVER]
SQLLocalizationFile=C:\SQL60\BIN\SQLCOMMN.LOC

For the Microsoft Windows NT® operating system, you set the date, time, numeric, and currency formatting using the International application in Control Panel. Use the SQL Server Client Network Utility Use International Settings option to activate this for DB-Library.

Examples

This example converts SQL 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 pubs..titles");

// Send the query to SQL Server.
dbsqlexec(dbproc);

// Get ready to process the results of the query.
dbresults(dbproc);


// Process each row.
while (dbnextrow(dbproc) != NO_MORE_ROWS)
{
    // The first dbconvert() adds a null terminator to the string.
    dbconvert(dbproc, SQLCHAR, (dbdata(dbproc,1)), (dbdatlen(dbproc,1)),
    SQLCHAR, title, (DBINT)-1);
    // The second dbconvert() converts money to string.
    dbconvert(dbproc, SQLMONEY, (dbdata(dbproc,2)), (DBINT)-1, SQLCHAR,
        price, (DBINT)-1);

    if (dbdatlen(dbproc,3) != 0)
        printf ("%s\n $%s    %ld\n", title, price,
            *((DBINT *)dbdata(dbproc,3)));
}

See Also