dbconvert

Converts data from one datatype to another.

Syntax

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

where

dbproc

Is the DBPROCESS structure that is the handle for a particular workstation/ 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 datatype of the source data to be converted. This parameter can be any of the SQL Server datatype tokens. You can use dbcoltype to get the SQL Server datatype 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 datatype tokens:

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

This length is ignored for all fixed-length, non-NULL datatypes. 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 datatype that the source data is to be converted into. This parameter can be any of the SQL Server datatype 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 datatype tokens:

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

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

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 datatype 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 datatypes (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 datatype (srctype or desttype parameters):



Datatype (srctype, desttype)	Program variable type (src, dest)

SQLCHAR	DBCHAR
SQLVARCHAR	DBCHAR
SQLTEXT	DBCHAR
SQLBINARY	DBBINARY
SQLVARBINARY	DBBINARY
SQLIMAGE	DBBINARY
SQLINT1	DBTINYINT
SQLINT2	DBSMALLINT
SQLINT4	DBINT
SQLFLT4	DBFLT4
SQLFLT8	DBFLT8
SQLBIT	DBBIT
SQLMONEY4	DBMONEY4
SQLMONEY	DBMONEY
SQLDATETIM4	DBDATETIM4
SQLDATETIME	DBDATETIME
SQLDECIMAL	DBDECIMAL
SQLNUMERIC	DBNUMERIC

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



srctype, desttype	srclen, destlen	src, dest

SQLINTN	1	DBTINYINT
SQLINTN	2	DBSMALLINT
SQLINTN	4	DBINT
SQLFLTN	4	DBFLT4
SQLFLTN	8	DBFLT8
SQLMONEYN	4	DBMONEY4
SQLMONEYN	8	DBMONEY
SQLDATIMETIMN	4	DBDATETIM4
SQLDATIMETIMN	8	DBDATETIME

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

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

A conversion to or from the datatypes 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 datatypes SQLFLT4 or SQLFLT8 can result in some loss of precision. Converting from the approximate numeric datatypes 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 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 Windows NT operating system, you set the date, time, numeric, and currency formatting using the International application in the Control Panel. Use the SQL Client Configuration Utility's Use International Settings option to activate this for DB-Library.

Example

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)));
}

dbconvert

Syntax

Returns

Remarks

Example

See Also