srv_convert

Changes data from one datatype to another.

Syntax

int srv_convert (
SRV_PROC * srvproc,
int srctype,
void * src,
DBINT srclen,
int desttype,
void * dest,
DBINT destlen );

where

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 datatype of the data to be converted. This parameter can be any of the Open Data Services datatypes.

src

Is a pointer to the data to be converted. This parameter can be any of the Open Data Services datatypes.

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 datatypes, in which case the source data is assumed to be NULL. For data of the SRVCHAR datatype, a length of -1 indicates that the string is null-terminated.

desttype

Specifies the datatype to convert the source to. This parameter can be any of the Open Data Services datatypes.

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

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 datatypes. 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 that 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 datatype conversion succeeds. When srv_convert encounters a request for a conversion that it doesn't support, it calls the developer-supplied error handler (if any), sets a global error number, and returns FAIL.

Remarks

Conversion to and from all Open Data Services datatypes is supported, except for conversion from SRVDATETIME or SRVDATETIME4 to these datatypes, and from these datatypes to SRVDATETIME or SRVDATETIME4:

• SRVINT1, SRVINT2, SRVINT4
• SRVFLT4, SRVFLT8
• SRVBIT
• SRVMONEY, SRVMONEY4
• SRVDECIMAL, SRVNUMERIC

The srv_willconvert function determines whether a particular conversion is allowed.

Converting to the approximate numeric datatypes SRVFLT4 or SRVFLT8 can result in some loss of precision. Converting from the approximate numeric datatypes 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 datatype is a straight bit-copy.

In certain cases, it can be useful to convert a datatype to itself. For example, converting SRVCHAR to SRVCHAR with a destlen of -1 adds a null terminator to a string.

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

See Also