NUM

Numeric

This numeric function converts any string value that contains a number into its numeric form.

Syntax

NUM (string-value[,ERR=line-ref|,ERC=error-code])

NUM (string-value,NTP=numeric-type [,SIZ=precision]
[,ERR=line-ref|,ERC=error-code])

string-value

is any string that results in a valid numeric value.

numeric-type

is the data type accepted as valid input to a numeric data element.

precision

specifies precision, which may cause the numeric value to be rounded.

line-ref

is the program line number or label to branch to if an error is produced by this function.

error-code

is a programmer-defined error code. Valid values are positive or negative whole numbers.

Remarks

Valid numeric	types (NTP) are as follows:
0	Fixed point positive/negative numbers
1	Fixed point positive numbers
2	Fixed point negative numbers
3	Binary positive/negative numbers
4	Binary positive numbers
5	Binary negative numbers
6	Packed decimal numbers
7	Informix decimal numbers
8	IEEE single precision floating point
9	IEEE double precision floating point
10	BCD signed
11	BCD unsigned
12	BCD no sign byte
13	ASCII sign stored in the high four bits of last byte
14	ASCII sign leading separate
15	ASCII sign trailing separate

For numeric-types 0-2, valid numeric characters include the digits 0 through 9, a leading + or B, a maximum of one decimal point, E (for floating exponential forms), and spaces. The string-value must contain, however, at least one occurrence of a digit 0 through 9.

For numeric-types 3 through 15, the string-value is converted into a number from formats defined by other languages.

Starting with release level 8.2, NUM can process numeric types that have been foreign to Thoroughbred Basic in previous releases.

Starting with release level 8.2.2, numeric type 7 accepts a string of all binary zeroes as a zero value.

Starting with release level 8.2.2, for numeric types 8 and 9, the string “$FF$” (binary 255) is accepted as a zero value.

Starting with release level 8.2.2, this function will properly evaluate strings that contain numeric values where periods and commas have been reversed by the SET CMASK directive.

If an attempt is made to convert an invalid string-value, an ERR=26 results.

Numeric types 3, 4, 5, 6, 10, 11, 12, 13, 14, and 15 are decimal implied. The decimal is not stored, but calculated for input and output based on the Dictionary-IV format definition.

Data files storing numeric values using types 8 and 9 may not be portable from one environment to another. The storage of a number on one environment may be physically backwards for another. You may use PRM IEEESWAP in order to reverse the natural ordering of the bytes. This is helpful when WRITEing files with IEEE numbers on one machine, and READing the file on another machine that has the reverse byte ordering. This parameter may be deactivated.

The SIZ= parameter enables you to specify precision, which causes rounding to occur after converting a string to a numeric value. Valid values are .01 through .15, which specify precision of 0 through 14. This feature is available starting with release level 8.3.1.

Examples

NUM ("1234")

returns the numeric value 1234.

NUM (A$)

If A$ = “12.34” returns the numeric value 12.34.

LET X = NUM (C$)

If C$ = “.24E+5” then X is assigned the value 24000.

LET X = NUM (B$, ERR=8000)

If B$ = “$12.34” produces an error since “$” is not a legal numeric character, and statement 8000 is executed.

NUM ("12       34")

returns the value 1234.

NUM ("12,345")

produces an error because the comma is not a legal numeric character.

NUM (Y$)

If Y$=“123456789012345”, an error is produced because the numeric result of this function exceeds the 14-digit maximum for numbers.

NUM ("12-"); NUM ("-"); NUM ("12.31.88")

produces errors.

NUM ($02182E$, NTP=6)

produces 12345.

NUM ($012345C$, NTP=10)

produces 12345.

NUM("12345+", NTP=15)

produces 12345.

SET CMASK ".=,";
N$=STR(12345.67),
X=NUM(N$)

X will be assigned the value 12345,67 because N$ contains the value “12345,67” and “,” is a legal numeric character when periods and commas have been reversed.

SET CMASK ".=,";
N$=STR(12345.67:"###,###.00"),
X=NUM(N$)

will produce an error because N$ contains the value “12.345,67” and “.” is not a legal numeric character when periods and commas have been reversed.

N = NUM($3039$, NTP=3, SIZ=.05)

assigns the value 1.2345 to N.

See also

STR function Information on formats in the Thoroughbred Dictionary-IV Reference Manual or Dictionary-IV on-line help system

From the Thoroughbred Basic Language Reference, Volume II: F–Q, version 8.9.1. Open this page in the PDF