The decimal Library Functions
The following ESQL/C library functions are available to handle decimal data type numbers.
When you compile your ESQL/C program with the esql preprocessor, it calls on the link editor to link the library that contains these functions to your program.
Chapter 5, "Working with Numeric Data Types," describes the function rfmtdec(), which allows you to format a decimal number. The following pages describe the functions in the preceding table.
decadd()
The decadd() function adds two decimal type values.
Syntax
Usage
The sum can be the same as either n1 or n2.
Return Codes
Example
The file decadd.ec in the demo directory contains the following sample program.
/*
* decadd.ec *
The following program obtains the sum of two DECIMAL numbers.
*/
#include <stdio.h>
EXEC SQL include decimal;
char string1[] = " 1000.6789"; /* leading spaces will be ignored */
char string2[] = "80";
char result[41];
main()
{
int x;
dec_t num1, num2, sum;
printf("DECADD Sample ESQL Program running.\n\n");
if (x = deccvasc(string1, strlen(string1), &num1))
{
printf("Error %d in converting string1 to DECIMAL\n", x);
exit(1);
}
if (x = deccvasc(string2, strlen(string2), &num2))
{
printf("Error %d in converting string2 to DECIMAL\n", x);
exit(1);
}
if (x = decadd(&num1, &num2, &sum))
{
printf("Error %d in adding DECIMALs\n", x);
exit(1);
}
if (x = dectoasc(&sum, result, sizeof(result), -1))
{
printf("Error %d in converting DECIMAL result to string\n", x);
exit(1);
}
result[40] = '\0';
printf("\t%s + %s = %s\n", string1, string2, result); /* display result */
printf("\nDECADD Sample Program over.\n\n");
exit(0);
}
Example Output
deccmp()
The deccmp() function compares two decimal type numbers.
Syntax
Return Codes
Example
The file deccmp.ec in the demo directory contains the following sample program.
/*
* deccmp.ec *
The following program compares DECIMAL numbers and displays the results.
*/
#include <stdio.h>
EXEC SQL include decimal;
char string1[] = "-12345.6789"; /* leading spaces will be ignored */
char string2[] = "12345.6789";
char string3[] = "-12345.6789";
char string4[] = "-12345.6780";
main()
{
int x;
dec_t num1, num2, num3, num4;
printf("DECCOPY Sample ESQL Program running.\n\n");
if (x = deccvasc(string1, strlen(string1), &num1))
{
printf("Error %d in converting string1 to DECIMAL\n", x);
exit(1);
}
if (x = deccvasc(string2, strlen(string2), &num2))
{
printf("Error %d in converting string2 to DECIMAL\n", x);
exit(1);
}
if (x = deccvasc(string3, strlen(string3), &num3))
{
printf("Error %d in converting string3 to DECIMAL\n", x);
exit(1);
}
if (x = deccvasc(string4, strlen(string4), &num4))
{
printf("Error %d in converting string4 to DECIMAL\n", x);
exit(1);
}
printf("Number 1 = %s\tNumber 2 = %s\n", string1, string2);
printf("Number 3 = %s\tNumber 4 = %s\n",string3, string4);
printf("\nExecuting: deccmp(&num1, &num2)\n");
printf(" Result = %d\n", deccmp(&num1, &num2));
printf("Executing: deccmp(&num2, &num3)\n");
printf(" Result = %d\n", deccmp(&num2, &num3));
printf("Executing: deccmp(&num1, &num3)\n");
printf(" Result = %d\n", deccmp(&num1, &num3));
printf("Executing: deccmp(&num3, &num4)\n");
printf(" Result = %d\n", deccmp(&num3, &num4));
printf("\nDECCMP Sample Program over.\n\n");
exit(0);
}
Example Output
deccopy()
The deccopy() function copies one decimal structure to another.
Syntax
The deccopy() function does not return a status value. To determine the success of the copy operation, look at the contents of the decimal structure to which the target argument points.
Example
The file deccopy.ec in the demo directory contains the following sample program.
/*
* deccopy.ec *
The following program copies one DECIMAL number to another.
*/
#include <stdio.h>
EXEC SQL include decimal;
char string1[] = "12345.6789";
char result[41];
main()
{
int x;
dec_t num1, num2;
printf("DECCOPY Sample ESQL Program running.\n\n");
printf("String = %s\n", string1);
if (x = deccvasc(string1, strlen(string1), &num1))
{
printf("Error %d in converting string1 to DECIMAL\n", x);
exit(1);
}
printf("Executing: deccopy(&num1, &num2)\n");
deccopy(&num1, &num2);
if (x = dectoasc(&num2, result, sizeof(result), -1))
{
printf("Error %d in converting num2 to string\n", x);
exit(1);
}
result[40] = '\0';
printf("Destination = %s\n", result);
printf("\nDECCOPY Sample Program over.\n\n");
exit(0);
}
Example Output
deccvasc()
The deccvasc() function converts a value held as printable characters in a C char type into a decimal type number.
Syntax
Usage
The character string, strng_val, can contain the following symbols:
The deccvasc() function ignores leading spaces in the character string.
Return Codes
Example
The file deccvasc.ec in the demo directory contains the following sample program.
/*
* deccvasc.ec *
The following program converts two strings to DECIMAL numbers and displays
the values stored in each field of the decimal structures.
*/
#include <stdio.h>
EXEC SQL include decimal;
char string1[] = "-12345.6789";
char string2[] = "480";
main()
{
int x;
dec_t num1, num2;
printf("DECCVASC Sample ESQL Program running.\n\n");
if (x = deccvasc(string1, strlen(string1), &num1))
{
printf("Error %d in converting string1 to DECIMAL\n", x);
exit(1);
}
if (x = deccvasc(string2, strlen(string2), &num2))
{
printf("Error %d in converting string2 to DECIMAL\n", x);
exit(1);
}
/*
* Display the exponent, sign value and number of digits in num1.
*/
printf("\tstring1 = %s\n", string1);
disp_dec("num1", &num1);
/*
* Display the exponent, sign value and number of digits in num2.
*/
printf("\tstring2 = %s\n", string2);
disp_dec("num2", &num2);
printf("\nDECCVASC Sample Program over.\n\n");
exit(0);
}
disp_dec(s, num)
char *s;
dec_t *num;
{
int n;
printf("%s dec_t structure:\n", s);
printf("\tdec_exp = %d, dec_pos = %d, dec_ndgts = %d, dec_dgts: ",
num->dec_exp, num->dec_pos, num->dec_ndgts);
n = 0;
while(n < num->dec_ndgts)
printf("%02d ", num->dec_dgts[n++]);
printf("\n\n");
}
Example Output
deccvdbl()
The deccvdbl() function converts a C double type number into a decimal type number.
Syntax
Return Codes
Example
The file deccvdbl.ec in the demo directory contains the following sample program.
/*
* deccvdbl.ec *
The following program converts two double type numbers to DECIMAL numbers
and displays the results.
*/
#include <stdio.h>
EXEC SQL include decimal;
char result[41];
main()
{
int x;
dec_t num;
double d = 2147483647;
printf("DECCVDBL Sample ESQL Program running.\n\n");
printf("Number 1 (double) = 1234.5678901234\n");
if (x = deccvdbl((double)1234.5678901234, &num))
{
printf("Error %d in converting double1 to DECIMAL\n", x);
exit(1);
}
if (x = dectoasc(&num, result, sizeof(result), -1))
{
printf("Error %d in converting DECIMAL1 to string\n", x);
exit(1);
}
result[40] = '\0';
printf(" String Value = %s\n", result);
printf("Number 2 (double) = $.1f\n", d);
if (x = deccvdbl(d, &num))
{
printf("Error %d in converting double2 to DECIMAL\n", x);
exit(1);
}
if (x = dectoasc(&num, result, sizeof(result), -1))
{
printf("Error %d in converting DECIMAL2 to string\n", x);
exit(1);
}
result[40] = '\0';
printf(" String Value = %s\n", result);
printf("\nDECCVDBL Sample Program over.\n\n");
exit(0);
}
Example Output
deccvint()
The deccvint() function converts a C int type number into a decimal type number.
Syntax
Return Codes
Example
The file deccvint.ec in the demo directory contains the following sample program.
/*
* deccvint.ec *
The following program converts two integers to DECIMAL numbers and displays
the results.
*/
#include <stdio.h>
EXEC SQL include decimal;
char result[41];
main()
{
int x;
dec_t num;
printf("DECCVINT Sample ESQL Program running.\n\n");
printf("Integer 1 = 129449233\n");
if (x = deccvint(129449233, &num))
{
printf("Error %d in converting int1 to DECIMAL\n", x);
exit(1);
}
if (x = dectoasc(&num, result, sizeof(result), -1))
{
printf("Error %d in converting DECIMAL to string\n", x);
exit(1);
}
result[40] = '\0';
printf(" String for Decimal Value = %s\n", result);
printf("Integer 2 = 33\n");
if (x = deccvint(33, &num))
{
printf("Error %d in converting int2 to DECIMAL\n", x);
exit(1);
}
result[40] = '\0';
printf(" String for Decimal Value = %s\n", result);
printf("\nDECCVINT Sample Program over.\n\n");
exit(0);
}
Example Output
deccvlong()
The deccvlong() function converts a C long type value into a decimal type value.
Syntax
Return Codes
Example
The file deccvlong.ec in the demo directory contains the following sample program.
/*
* deccvlong.ec *
The following program converts two longs to DECIMAL numbers and displays
the results.
*/
#include <stdio.h>
EXEC SQL include decimal;
char result[41];
main()
{
int x;
dec_t num;
long n;
printf("DECCVLONG Sample ESQL Program running.\n\n");
printf("Long Integer 1 = 129449233\n");
if (x = deccvlong(129449233L, &num))
{
printf("Error %d in converting long to DECIMAL\n", x);
exit(1);
}
if (x = dectoasc(&num, result, sizeof(result), -1))
{
printf("Error %d in converting DECIMAL to string\n", x);
exit(1);
}
result[40] = '\0';
printf(" String for Decimal Value = %s\n", result);
n = 2147483646; /* set n */
printf("Long Integer 2 = %ld\n", n);
if (x = deccvlong(n, &num))
{
printf("Error %d in converting long to DECIMAL\n", x);
exit(1);
}
if (x = dectoasc(&num, result, sizeof(result), -1))
{
printf("Error %d in converting DECIMAL to string\n", x);
exit(1);
}
result[40] = '\0';
printf(" String for Decimal Value = %s\n", result);
printf("\nDECCVLONG Sample Program over.\n\n");
exit(0);
}
Example Output
decdiv()
The decdiv() function divides two decimal type values.
Syntax
Usage
The quotient can be the same as either n1 or n2.
Return Codes
Example
The file decdiv.ec in the demo directory contains the following sample program.
if (x = deccvasc(string2, strlen(string2), &num2))
{
printf("Error %d in converting string2 to DECIMAL\n", x);
exit(1);
}
if (x = decdiv(&num1, &num2, &dvd))
{
printf("Error %d in converting divide num1 by num2\n", x);
exit(1);
}
if (x = dectoasc(&dvd, result, sizeof(result), -1))
{
printf("Error %d in converting dividend to string\n", x);
exit(1);
}
result[40] = '\0';
printf("\t%s / %s = %s\n", string1, string2, result);
printf("\nDECDIV Sample Program over.\n\n");
exit(0);
}
Example Output
dececvt() and decfcvt()
The dececvt() and decfcvt() functions are analogous to the subroutines under ECVT(3) in section three of the UNIX Programmer's Manual. The dececvt() function works in the same fashion as the ecvt(3) function, and the decfcvt() function works in the same fashion as the fcvt(3) function. They both convert a decimal type number to a C char type value.
Syntax
Usage
The dececvt() function converts the decimal value to which np points into a
null-terminated string of ndigit ASCII digits and returns a pointer to the string. A subsequent call to this function overwrites the string.
The dececvt() function rounds low-order digits.
The decfcvt() function is identical to dececvt(), except that ndigit specifies the number of digits to the right of the decimal point instead of the total number of digits.
Let dec_val point to a decimal value of 12345.67 and suppress all arguments except ndigit. The following table shows the values that the dececvt() function returns for four different ndigit values.
For more examples of dec_val and ndigit values, see the sample output of the dececvt.ec demo program on page 4-32.
dececvt() Example
The file dececvt.ec in the demo directory contains the following sample program.
dececvt() Example Output
decfcvt() Example
The file decfcvt.ec in the demo directory contains the following sample program.
/*
* decfcvt.ec *
The following program converts a series of DECIMAL numbers to strings of
ASCII digits with 3 digits to the right of the decimal point. For each
conversion it displays the resulting string, the position of the decimal
point from the beginning of the string and the sign value.
*/
#include <stdio.h>
EXEC SQL include decimal;
char *strings[] =
{
"210203.204",
"4894",
"443.334899312",
"-12344455",
0
};
main()
{
int x;
dec_t num;
int i = 0, f, sign;
char *dp, *decfcvt();
printf("DECFCVT Sample ESQL Program running.\n\n");
while(strings[i])
{
if (x = deccvasc(strings[i], strlen(strings[i]), &num))
{
printf("Error %d in converting string [%s] to DECIMAL\n",
x, strings[i]);
break;
}
dp = decfcvt(&num, 3, &f, &sign); /* to ASCII string */
/* display result */
printf("Input string[%d]: %s\n", i, strings[i]);
printf(" Output of decfcvt: %c%*.*s.%s decpt: %d sign: %d\n\n",
(sign ? '-' : '+'), f, f, dp, dp+f, f, sign);
++i; /* next string */
}
printf("\nDECFCVT Sample Program over.\n\n");
}
decfcvt() Example Output
decmul()
The decmul() function multiplies two decimal type values.
Syntax
Usage
The product can be the same as either n1 or n2.
Return Codes
Example
The file decmul.ec file in the demo directory contains the following sample program.
if (x = decmul(&num1, &num2, &mpx))
{
printf("Error %d in converting multiply\n", x);
exit(1);
}
if (x = dectoasc(&mpx, result, sizeof(result), -1))
{
printf("Error %d in converting mpx to display string\n", x);
exit(1);
}
result[40] = '\0';
printf("\t%s * %s = %s\n", string1, string2, result);
printf("\nDECMUL Sample Program over.\n\n");
exit(0);
}
Example Output
decround()
The decround() function rounds a decimal type number to fractional digits.
Syntax
Usage
The rounding factor is 5 ¥ 10-s-1. To round a value, the decround() function adds the rounding factor to a positive number or subtracts this factor from a negative number. It then truncates to s digits, as the following table shows
.
Example
The file decround.ec in the demo directory contains the following sample program.
/*
* decround.ec *
The following program rounds a DECIMAL type number six times and displays
the result of each operation.
*/
#include <stdio.h>
EXEC SQL include decimal;
char string[] = "-12345.038572";
char result[41];
main()
{
int x;
int i = 6; /* number of decimal places to start with */
dec_t num1;
printf("DECROUND Sample ESQL Program running.\n\n");
printf("String = %s\n", string);
while(i)
{
if (x = deccvasc(string, strlen(string), &num1))
{
printf("Error %d in converting string to DECIMAL\n", x);
break;
}
decround(&num1, i);
if (x = dectoasc(&num1, result, sizeof(result), -1))
{
printf("Error %d in converting result to string\n", x);
break;
}
result[40] = '\0';
printf(" Rounded to %d Fractional Digits: %s\n", i--, result);
}
printf("\nDECROUND Sample Program over.\n\n");
}
Example Output
decsub()
The decsub() function subtracts two decimal type values.
Syntax
Usage
The difference can be the same as either n1 or n2.
Return Codes
Example
The file decsub.ec in the demo directory contains the following sample program.
/*
* decsub.ec *
The following program subtracts two DECIMAL numbers and displays the result.
*/
#include <stdio.h>
EXEC SQL include decimal;
char string1[] = "1000.038782";
char string2[] = "480";
char result[41];
main()
{
int x;
dec_t num1, num2, diff;
printf("DECSUB Sample ESQL Program running.\n\n");
if (x = deccvasc(string1, strlen(string1), &num1))
{
printf("Error %d in converting string1 to DECIMAL\n", x);
exit(1);
}
if (x = deccvasc(string2, strlen(string2), &num2))
{
printf("Error %d in converting string2 to DECIMAL\n", x);
exit(1);
}
if (x = decsub(&num1, &num2, &diff))
{
printf("Error %d in subtracting decimals\n", x);
exit(1);
}
Example Output
dectoasc()
The dectoasc() function converts a decimal type number to a C char type value.
Syntax
Usage
If right = -1, the decimal value of *np determines the number of decimal places.
If the decimal number does not fit into a character string of length len, dectoasc() converts the number to an exponential notation. If the number still does not fit, dectoasc() fills the string with asterisks. If the number is shorter than the string, dectoasc() left-justifies the number and pads it on the right with blanks.
Because the character string that dectoasc() returns is not null terminated, your program must add a null character to the string before you print it.
Return Codes
Example
The file dectoasc.ec in the demo directory contains the following sample program.
/*
* dectoasc.ec *
The following program converts DECIMAL numbers to strings of varying sizes.
*/
#include <stdio.h>
EXEC SQL include decimal;
#define END sizeof(result)
char string1[] = "-12345.038782";
char string2[] = "480";
char result[40];
main()
{
int x;
dec_t num1, num2;
printf("DECTOASC Sample ESQL Program running.\n\n");
printf("String Decimal Value 1 = %s\n", string1);
if (x = deccvasc(string1, strlen(string1), &num1))
{
printf("Error %d in converting string1 to DECIMAL\n", x);
exit(1);
}
printf("String Decimal Value 2 = %s\n", string2);
if (x = deccvasc(string2, strlen(string2), &num2))
{
printf("Error %d in converting string2 to DECIMAL\n", x);
exit(1);
}
printf("\nConverting Decimal back to ASCII\n");
printf(" Executing: dectoasc(&num1, result, 5, -1)\n");
if (x = dectoasc(&num1, result, 5, -1))
printf("\tError %d in converting DECIMAL1 to string\n", x);
else
{
result[5] = '\0'; /* null terminate */
printf("\tResult ='%s'\n", result);
}
printf("Executing: dectoasc(&num1, result, 10, -1)\n");
if (x = dectoasc(&num1, result, 10, -1))
printf("Error %d in converting DECIMAL1 to string\n", x);
else
{
result[10] = '\0'; /* null terminate */
printf("\tResult = '%s'\n", result);
}
printf("Executing: dectoasc(&num2, result, END, 3)\n");
if (x = dectoasc(&num2, result, END, 3))
printf("\tError %d in converting DECIMAL2 to string\n", x);
else
{
result[END-1] = '\0'; /* null terminate */
printf("\tResult = '%s'\n", result);
}
printf("\nDECTOASC Sample Program over.\n\n")
}
Example Output
dectodbl()
The dectodbl() function converts a decimal type number into a C double type number.
Syntax
Usage
The floating-point format of the host computer can result in loss of precision in the conversion of a decimal type number to a double type number.
Return Codes
Example
The file dectodbl.ec file in the demo directory contains the following sample program.
/*
* dectodbl.ec *
The following program converts two DECIMAL numbers to doubles and displays
the results.
*/
#include <stdio.h>
EXEC SQL include decimal;
char string1[] = "2949.3829398204382";
char string2[] = "3238299493";
char result[40];
main()
{
int x;
double d = 0;
dec_t num;
printf("DECTODBL Sample ESQL Program running.\n\n");
if (x = deccvasc(string1, strlen(string1), &num))
{
printf("Error %d in converting string1 to DECIMAL\n", x);
exit(1);
}
if (x = dectodbl(&num, &d))
{
printf("Error %d in converting DECIMAL1 to double\n", x);
exit(1);
}
printf("String 1 = %s\n", string1);
printf("Double value = %.15f\n", d);
if (x = deccvasc(string2, strlen(string2), &num))
{
printf("Error %d in converting string2 to DECIMAL\n", x);
exit(1);
}
if (x = dectodbl(&num, &d))
{
printf("Error %d in converting DECIMAL2 to double\n", x);
exit(1);
}
printf("String 2 = %s\n", string2);
printf("Double value = %f\n", d);
printf("\nDECTODBL Sample Program over.\n\n");
exit(0);
}
Example Output
dectoint()
The dectoint() function converts a decimal type number into a C int type number.
Syntax
Usage
The dectoint() library function converts a decimal value to a C integer. The size of a C integer depends on the hardware and operating system of the computer you are using. Therefore, the dectoint() function equates an integer value with the SQL SMALLINT data type. The valid range of a SMALLINT is between 32767 and -32767. To convert larger decimal values to larger integers, use the dectolong() library function.
Return Codes
Example
The file dectoint.ec in the demo directory contains the following sample program.
/*
* dectoint.ec *
The following program converts two DECIMAL numbers to integers and
displays the result of each conversion.
*/
#include <stdio.h>
EXEC SQL include decimal;
char string1 [] = "32767";
char string2 [] = "32768";
main()
{
int x;
int n = 0;
dec_t num;
printf("DECTOINT Sample ESQL Program running.\n\n)";
printf("String 1 = %s\n", string1);
if (x = deccvasc(string1,strlen(string1), &num))
{
printf(" Error %d in converting string1 to decimal\n", x);
exit(1);
}
if (x = dectoint(&num, &n))
printf(" Error %d in converting decimal to int\n", x);
else
printf(" Result = %d\n", n);
printf("\nString 2 = %s\n", string2);
if (x = deccvasc(string2, strlen(string2), &num))
{
printf(" Error %d in converting string2 to decimal\n", x);
exit(1);
}
if (x = dectoint(&num, &n))
printf(" Error %d in converting decimal to int\n", x);
else
printf(" Result = %d\n", n);
printf("\nDECTOINT Sample Program over.\n\n");
exit(0);
}
Example Output
dectolong()
The dectolong() function converts a decimal type number into a C long type number.
Syntax
Return Codes
Example
The file dectolong.ec in the demo directory contains the following sample program.
/*
* dectolong.ec *
The following program converts two DECIMAL numbers to longs and displays
the return value and the result for each conversion.
*/
#include <stdio.h>
EXEC SQL include decimal;
char string1[] = "2147483647";
char string2[] = "2147483648";
main()
{
int x;
long n = 0;
dec_t num;
printf("DECTOLONG Sample ESQL Program running.\n\n");
printf("String 1 = %s\n", string1);
if (x = deccvasc(string1, strlen(string1), &num))
{
printf(" Error %d in converting string1 to DECIMAL\n", x);
exit(1);
}
if (x = dectolong(&num, &n))
printf(" Error %d in converting DECIMAL1 to long\n", x);
else
printf(" Result = %ld\n", n);
printf("\nString 2 = %s\n", string2);
if (x = deccvasc(string2, strlen(string2), &num))
{
printf(" Error %d in converting string2 to DECIMAL\n", x);
exit(1);
}
if (x = dectolong(&num, &n))
printf(" Error %d in converting DECIMAL2 to long\n", x);
else
printf(" Result = %ld\n", n);
printf("\nDECTOLONG Sample Program over.\n\n");
exit(0);
}
Example Output
dectrunc()
The dectrunc() function truncates a rounded decimal type number to fractional digits.
Syntax
Usage
The following table shows the sample output from dectrunc() with various inputs.
Example
The file dectrunc.ec in the demo directory contains the following sample program.
/*
* dectrunc.ec *
The following program truncates a DECIMAL number six times and displays each
result.
*/
#include <stdio.h>
EXEC SQL include decimal;
char string[] = "-12345.038572";
char result[41];
main()
{
int x;
int i = 6; /* number of decimal places to start with */
dec_t num1;
printf("DECTRUNC Sample ESQL Program running.\n\n");
printf("String = %s\n", string);
while(i)
{
if (x = deccvasc(string, strlen(string), &num1))
{
printf("Error %d in converting string to DECIMAL\n", x);
break;
}
dectrunc(&num1, i);
if (x = dectoasc(&num1, result, sizeof(result), -1))
{
printf("Error %d in converting result to string\n", x);
break;
}
result[40] = '\0';
printf(" Truncated to %d Fractional Digits: %s\n", i--, result);
}
printf("\nDECTRUNC Sample Program over.\n\n");
}
Example Output
|
