srv_convert
Changes data from one data type to another.
Syntax
int srv_convert (
SRV_PROC * srvproc,
int srctype,
void * src,
DBINT srclen,
int desttype,
void * dest,
DBINT destlen );
Arguments
srvproc
Is a pointer to the SRV_PROC structure that is the handle for a particular client connection. The structure contains all the control information that Open Data Services uses to manage communications and data between the Open Data Services server application and the client. If the srvproc handle is supplied, it is passed to the Open Data Services error handler function when an error occurs.
srctype
Specifies the data type of the data to be converted. This parameter can be any of the Open Data Services data types.
src
Is a pointer to the data to be converted. This parameter can be any of the Open Data Services data types.
srclen
Specifies the length, in bytes, of the data to be converted. If srclen is 0, srv_convert places a null value in the destination variable. Unless it is 0, this parameter is ignored for fixed-length data types, in which case the source data is assumed to be NULL. For data of the SRVCHAR data type, a length of -1 indicates the string is null-terminated.
desttype
Specifies the data type to convert the source to. This parameter can be any of the Open Data Services data types.
dest
Is a pointer to the destination variable that receives converted data. If this pointer is NULL, srv_convert calls the user-supplied error handler (if any) and returns -1.
If desttype is SRVDECIMAL or SRVNUMERIC, the dest parameter must be a pointer to a DBNUMERIC or DBDECIMAL structure 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
Specifies the length, in bytes, of the destination variable. This parameter is ignored for fixed-length data types. For a destination variable of type SRVCHAR, the value of destlen must be the total length of the destination buffer space. A length of -1 for a destination variable of type SRVCHAR or SRVBINARY indicates there is sufficient space available. For a destination variable of type srvchar, a length of -1 causes the character string to be null-terminated.
Returns
The length of the converted data, in bytes, if the data type conversion succeeds. When srv_convert encounters a request for a conversion it does not support, it calls the developer-supplied error handler (if any), sets a global error number, and returns -1.
Remarks
The srv_willconvert function determines whether a particular conversion is allowed.
Converting to the approximate numeric data types SRVFLT4 or SRVFLT8 can result in some loss of precision. Converting from the approximate numeric data types SRVFLT4 or SRVFLT8 to SRVCHAR or SRVTEXT can also result in some loss of precision.
Converting to SRVFLTx, SRVINTx, SRVMONEY, SRVMONEY4, SRVDECIMAL, or SRVNUMERIC 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 SRVCHAR or SRVTEXT, the first character of the resulting value contains an asterisk (*) to indicate the error.
When converting SRVCHAR to SRVBINARY, srv_convert interprets SRVCHAR as hexadecimal, whether or not the string contains a leading 0. When converting SRVBINARY to SRVCHAR, srv_convert creates a hexadecimal string without a leading 0. In all other cases, a conversion to or from the SRVBINARY data type is a straight bit-copy.
In certain cases, it can be useful to convert a data type to itself. For example, converting SRVCHAR to SRVCHAR with a destlen of -1 adds a null terminator to a string.
For a description of data types and Open Data Services data type conversions, see Data Types.
The srv_convert function can fail for several reasons:
- The requested conversion is not available.
- The conversion resulted in truncation, overflow, or loss of precision in the destination variable.
- A syntax error occurred while converting a character string to a numeric data type.