dbconvert_ps

Description

Convert data from one datatype to another, with precision and scale support for numeric and decimal datatypes.

Syntax

DBINT dbconvert_ps(dbproc, srctype, src, srclen,
                 desttype, dest, destlen, typeinfo)
 
DBPROCESS        *dbproc;
int                          srctype;
BYTE                     *src;
DBINT                   srclen;
int                          desttype;
BYTE                     *dest;
DBINT                   destlen;
DBTYPEINFO        *typeinfo;

Parameters

dbproc: 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_ps, the DBPROCESS is used only to supply any custom null values that the program may have specified using dbsetnull. If dbproc is NULL, dbconvert_ps uses the default values for null value data conversions.

srctype: The datatype of the data which is to be converted. This parameter can be any of the server datatypes, as listed in Table 2-8.

src: A pointer to the data that is to be converted. If this pointer is NULL, dbconvert_ps will place an appropriate null value in the destination variable. You can use dbdata to get the server data.

srclen: 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_ps 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 data, a length of -1 indicates that the string is null-terminated. You can use dbdatlen to get the length of the server data.

desttype: The datatype that the source data is to be converted into. This parameter can be any of the server datatypes, as listed in Table 2-8.

dest: A pointer to the destination variable that will receive the converted data. If this pointer is NULL, dbconvert_ps will call the user-supplied error handler (if any) and return -1.

destlen: 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-6 describes special values for destlen:

Table 2-6: Special values for destlen (dbconvert_ps)
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.

typeinfo: A pointer to a DBTYPEINFO structure containing information about the precision and scale of decimal or numeric values. An application sets a DBTYPEINFO structure with values for precision and scale before calling dbconvert_ps to convert data into DBDECIMAL or DBNUMERIC variables.

If typeinfo is NULL:

If the source value is of type SYBNUMERIC or SYBDECIMAL, dbconvert_ps picks up precision and scale values from the source. In effect, the source data is copied to the destination space.

If the source value is not SYBNUMERIC or SYBDECIMAL, dbconvert_ps uses a default precision of 18 and a default scale of 0.

If srctype is not SYBDECIMAL or SYBNUMERIC, typeinfo is ignored.

A DBTYPEINFO structure is defined as follows:

typedef struct typeinfo {

DBINT precision;

DBINT scale;

} DBTYPEINFO;

Legal values for precision are from 1 to 77. Legal values for scale are from 0 to 77. scale must be less than or equal to precision.

Returns

The length of the converted data, in bytes, if the datatype conversion succeeds.

If the conversion fails, dbconvert_ps returns either -1 or FAIL, depending on the cause of the failure. dbconvert_ps returns -1 to indicate a NULL destination pointer or an illegal datatype. dbconvert_ps returns FAIL to indicate other types of failures.

If dbconvert_ps 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.

Usage

dbconvert_ps is the equivalent of dbconvert, except that dbconvert_ps provides precision and scale support for numeric and decimal datatypes, which dbconvert does not. Calling dbconvert is equivalent to calling dbconvert_ps with typeinfo as NULL.

dbconvert_ps allows a 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_ps can convert data stored in any of the server datatypes (but not all conversions are legal—see Table 2-8).

Table 2-7 shows type constants for server datatypes and the corresponding program variable types:

**Table 2-7: Type constants and program variable types**
Server datatype constant	Program variable type
SYBCHAR	DBCHAR
SYBTEXT	DBCHAR
SYBBINARY	DBBINARY
SYBIMAGE	DBBINARY
SYBINT1	DBTINYINT
SYBINT2	DBSMALLINT
SYBINT4	DBINT
SYBFLT8	DBFLT8
SYBREAL	DBREAL
SYBNUMERIC	DBNUMERIC
SYBDECIMAL	DBDECIMAL
SYBBIT	DBBIT
SYBMONEY	DBMONEY
SYBMONEY4	DBMONEY4
SYBDATETIME	DBDATETIME
SYBDATETIME4	DBDATETIME4
SYBBOUNDARY	DBCHAR
SYBSENSITIVITY	DBCHAR

WARNING! It is an error to use the following datatypes with dbconvert_ps if the library version has not been set (with dbsetversion) to DBVERSION_100 or higher: SYBNUMERIC, SYBDECIMAL, SYBBOUNDARY, and SYBSENSITIVITY.

Table 2-8 shows the datatype conversions that dbconvert_ps supports. Source datatypes are listed down the left side, and destination datatypes are listed across the top. (For brevity, the “SYB” datatype prefix is not shown.)

**Table 2-8: Supported datatype conversions**
From:	To:
From:	CHAR	TEXT	BINARY	IMAGE	INT1	INT2	INT4	FLT8	REAL	NUMERIC	DECIMAL	BIT	MONEY	MONEY4	DATETIME	DATETIME4	BOUNDARY	SENSITIVITY
CHAR	•	•	•	•	•	•	•	•	•	•	•	•	•	•	•	•	•	•
TEXT	•	•	•	•	•	•	•	•	•	•	•	•	•	•	•	•	•	•
BINARY	•	•	•	•	•	•	•	•	•	•	•	•	•	•
IMAGE	•	•	•	•	•	•	•	•	•	•	•	•	•	•
INT1	•	•	•	•	•	•	•	•	•	•	•	•	•	•
INT2	•	•	•	•	•	•	•	•	•	•	•	•	•	•
INT4	•	•	•	•	•	•	•	•	•	•	•	•	•	•
FLT8	•	•	•	•	•	•	•	•	•	•	•	•	•	•
REAL	•	•	•	•	•	•	•	•	•	•	•	•	•	•
NUMERIC	•	•	•	•	•	•	•	•	•	•	•	•	•	•
DECIMAL	•	•	•	•	•	•	•	•	•	•	•	•	•	•
BIT	•	•	•	•	•	•	•	•	•	•	•	•	•	•
MONEY	•	•	•	•	•	•	•	•	•	•	•	•	•	•
MONEY4	•	•	•	•	•	•	•	•	•	•	•	•	•	•
DATETIME	•	•	•	•											•	•
DATETIME4	•	•	•	•											•	•
BOUNDARY	•	•															•
SENSITIVITY	•	•																•

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_ps 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_ps 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.

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.

If you are binding data to variables with dbbind or dbbind_ps rather than accessing the data directly with dbdata, dbbind can perform the conversions itself, making dbconvert_ps unnecessary.

The sample program example5.c illustrates several more types of conversions using dbconvert_ps.

See Types for a list of DB-Library datatypes and the corresponding Adaptive Server Enterprise datatypes. See the Adaptive Server Enterprise Reference Manual.

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.