1 Version 4.0 -- 5/1/89 dbconvert
______________________________________________________________________
NAME: dbconvert
FUNCTION:
Convert data from one datatype to another.
SYNTAX:
DBINT dbconvert(dbproc, srctype, src, srclen, desttype, dest, destlen)
DBPROCESS *dbproc;
int srctype;
BYTE *src;
DBINT srclen;
dbconvert Version 4.0 -- 5/1/89 2
______________________________________________________________________
int desttype;
BYTE *dest;
DBINT destlen;
COMMENTS:
o 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.
o dbconvert() can convert data stored in any of the SQL Server
datatypes (although, of course, not all conversions are legal):
3 Version 4.0 -- 5/1/89 dbconvert
______________________________________________________________________
SQL Server type Program variable type
SYBCHAR DBCHAR
SYBTEXT DBCHAR
SYBBINARY DBBINARY
SYBIMAGE DBBINARY
SYBINT1 DBTINYINT
SYBINT2 DBSMALLINT
SYBINT4 DBINT
SYBFLT8 DBFLT8
SYBBIT DBBIT
SYBMONEY DBMONEY
SYBDATETIME DBDATETIME
o The table below 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
dbconvert Version 4.0 -- 5/1/89 4
______________________________________________________________________
eliminated from each datatype.) T (TRUE) indicates that the
conversion is supported; F (FALSE) indicates that the conver-
sion is not supported.
FROM: TO: BIN- DATE-
CHAR CHA
TR TET
XT ART
Y IMA
TGE INT1 INT2 INT4 FLT8 BI
TT MONET
Y TIM
TE
B
TE
IN
XA
TRY T T T T T T T T T T F
T
IM
NA
T1
GE T T T T T T T T T T F
INT2
4 T T T T T T T T T T F
B
FI
LT8 T T T T T T T T T F
T F
D
MA
ON
TET
YIME T T T T F
T F
T F
T F
T F
T F
T F
T
o A conversion to or from the datatypes SYBBINARY and SYBIMAGE is
a straight bit-copy, except when the conversion involves SYB-
CHAR 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
5 Version 4.0 -- 5/1/89 dbconvert
______________________________________________________________________
contains a leading "0x". When converting SYBBINARY or SYBIMAGE
data to SYBCHAR or SYBTEXT, dbconvert() creates a hexadecimal
string without a leading "0x".
o 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 preci-
sion.
o Converting a SYBFLT8 value to SYBMONEY can result in overflow,
because the maximum value for SYBMONEY is
$922,337,203,685,477.58.
o 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.
o 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
dbconvert Version 4.0 -- 5/1/89 6
______________________________________________________________________
the value is 0, the SYBBIT value will be set to 0.
o 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 termi-
nator to a string, as the example below illustrates.
o Here's a short example that illustrates how to convert
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);
7 Version 4.0 -- 5/1/89 dbconvert
______________________________________________________________________
/* 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, 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)));
}
dbconvert Version 4.0 -- 5/1/89 8
______________________________________________________________________
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.
o If you're binding data to variables with dbbind() rather than
accessing the data directly with dbdata(), dbbind() can perform
the conversions itself, making dbconvert() unnecessary.
o Example 5 in the DB-Library Reference Supplement illustrates
several more types of conversions using dbconvert().
o For more information on SQL Server datatypes, see the Commands
Reference and the types manual page in this document.
PARAMETERS:
dbproc - A pointer to the DBPROCESS structure that provides the
connection for a particular front-end/SQL Server process. It
contains all the information that DB-Library uses to manage
9 Version 4.0 -- 5/1/89 dbconvert
______________________________________________________________________
communications and data between the front end and SQL Server.
In dbconvert(), the DBPROCESS is used only to supply any cus-
tom null values that the program may have specified via
dbsetnull(). If dbproc is NULL, dbconvert() 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 SQL Server datatypes, as
listed in the first table above.
src - 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 SQL 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() will place an appropriate null value in the des-
tination variable. Otherwise, this length is ignored for all
datatypes except character, text, binary, and image. For
dbconvert Version 4.0 -- 5/1/89 10
______________________________________________________________________
SYBCHAR data, a length of -1 indicates that the string is
null-terminated. You can use dbdatlen() to get the length of
SQL Server data.
desttype - The datatype that the source data is to be converted
into. This parameter can be any of the SQL Server datatypes,
as listed in the first table above.
dest - 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
FAIL.
destlen - The length, in bytes, of the destination variable.
destlen is ignored for fixed-length datatypes. For a SYBCHAR
destination, the value of destlen must be the total length of
the destination buffer space. A length of -1 for a SYBCHAR
or SYBBINARY destination means that there is sufficient space
available. In addition, for a SYBCHAR destination a length
of -1 will cause the character string to be given a
11 Version 4.0 -- 5/1/89 dbconvert
______________________________________________________________________
terminating null.
RETURNS:
The length of the converted data, in bytes, if the datatype
conversion succeeds. If the conversion fails, dbconvert()
returns -1. 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 conver-
sion 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.
SEE ALSO:
dbaltbind, dbbind, dberrhandle, dbsetnull, dbwillconvert, errors,
dbconvert Version 4.0 -- 5/1/89 12
______________________________________________________________________
types