Text to number and back
A file, a screen and a command line all send COBOL text. A numeric field holds a value, and the two are not the same thing: an amount arrives as the characters " 12.34 " and has to become the number 12.34. The language has two ways to do it, a function and a MOVE, and they do not behave the same way.
NUMVAL reads a number out of text
FUNCTION NUMVAL takes an alphanumeric item and returns its numeric value. Leading and trailing spaces are ignored, a sign and a decimal point are understood, and the result goes into a numeric field with the picture of that field:
IDENTIFICATION DIVISION.
PROGRAM-ID. NUMVAL.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 TEXT-F PIC X(10) VALUE " 12.34 ".
01 MONEY-F PIC X(12) VALUE "$1,234.50".
01 AMT-F PIC 9(4)V99.
01 TOT-F PIC 9(5)V99.
01 OUT-F PIC Z(3)9.99.
PROCEDURE DIVISION.
COMPUTE AMT-F = FUNCTION NUMVAL(TEXT-F).
DISPLAY "plain [" TEXT-F "] -> " AMT-F.
COMPUTE TOT-F = FUNCTION NUMVAL-C(MONEY-F).
DISPLAY "money [" MONEY-F "] -> " TOT-F.
MOVE TOT-F TO OUT-F.
DISPLAY "printed [" OUT-F "]".
STOP RUN.
cobc -x -free -Wall -o numval numval.cob
./numval
plain [ 12.34 ] -> 0012.34
money [$1,234.50 ] -> 01234.50
printed [1234.50]
The first line prints the field in its picture: five digits before the point and two after it, with the leading zero a number does not need. The function itself did not add anything to the value; the picture of AMT-F did.
NUMVAL-C and the printed number
Money arrives with a currency sign and thousands separators. FUNCTION NUMVAL-C is the same function with one extra argument: the currency sign, given as a literal, which makes $1,234.50 a number. The commas are ignored by both functions. Without the second argument the call reads NUMVAL-C(MONEY-F) and the dollar sign makes the value zero, so the signature matters.
The way back is not a function but a picture. OUT-F is PIC Z(3)9.99: the Z positions hold spaces instead of leading zeros, so the same number that printed as 01234.50 prints as 1234.50. The edited pictures are the subject of the lesson on edited output; the point here is that a numeric field holds a value and the picture decides how it is written.
MOVE is not NUMVAL
A MOVE from an alphanumeric field into a numeric one also converts, but by another rule: it reads the digit characters from the left, stops at the first character that is not a digit, and fills the rest of the field with zeros.
IDENTIFICATION DIVISION.
PROGRAM-ID. TEXTMOVE.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 CODE-F PIC X(6) VALUE "12AB".
01 NUM-F PIC 9(4).
PROCEDURE DIVISION.
MOVE CODE-F TO NUM-F.
DISPLAY "code [" CODE-F "] moved -> [" NUM-F "]".
MOVE " 7 " TO CODE-F.
MOVE CODE-F TO NUM-F.
DISPLAY "code [" CODE-F "] moved -> [" NUM-F "]".
STOP RUN.
cobc -x -free -Wall -o textmove textmove.cob
./textmove
code [12AB ] moved -> [0012]
code [ 7 ] moved -> [0007]
The letters after the digits were dropped without a word, and the spaces around the seven were skipped. A MOVE is therefore safe for a field that holds a number with padding and dangerous for a code that starts with digits, because it is happy with half a value.
A literal on the right of such a move is another matter: the compiler sees the characters and warns, and the bytes go into the field as they are.
IDENTIFICATION DIVISION.
PROGRAM-ID. LITBAD.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 NUM-F PIC 9(4).
PROCEDURE DIVISION.
MOVE "12AB" TO NUM-F.
DISPLAY "moved [" NUM-F "]".
STOP RUN.
cobc -x -free -Wall -o litbad litbad.cob
./litbad
litbad.cob:9: warning: numeric value is expected [-Wtyping]
7 |
8 | PROCEDURE DIVISION.
9 > MOVE "12AB" TO NUM-F.
10 | DISPLAY "moved [" NUM-F "]".
11 | STOP RUN.
litbad.cob:6: note: 'NUM-F' defined here as PIC 9(4) [-Wtyping]
4 | DATA DIVISION.
5 | WORKING-STORAGE SECTION.
6 > 01 NUM-F PIC 9(4).
7 |
8 | PROCEDURE DIVISION.
moved [12AB]
The build printed a warning and the program printed the four characters, because the field now holds bytes that are not a number at all. The lesson on warnings and errors reads a diagnostic of this shape line by line; the rule to take away is that a literal moved into a numeric field is a mistake the compiler reports, and a field moved into one is a mistake it cannot see.
A number that does not fit
A twelve-digit text and a receiving field of four digits are a SIZE ERROR, and the clause of that name catches it. The receiving field is left at zero, not at a truncated value:
IDENTIFICATION DIVISION.
PROGRAM-ID. BIG.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 BIG-F PIC X(12) VALUE "123456789012".
01 SM-F PIC 9(4).
PROCEDURE DIVISION.
COMPUTE SM-F = FUNCTION NUMVAL(BIG-F)
ON SIZE ERROR
DISPLAY "does not fit in 4 digits"
NOT ON SIZE ERROR
DISPLAY "value " SM-F
END-COMPUTE.
DISPLAY "after the failed statement: [" SM-F "]".
STOP RUN.
cobc -x -free -Wall -o big big.cob
./big
does not fit in 4 digits
after the failed statement: [0000]
A conversion without that clause is the case the lesson on ON SIZE ERROR covers in full. Here it is the reason a program that reads amounts from a file checks the size of the field before it trusts the value: the number in the file is not under the control of the program.
What NUMVAL accepts
The functions are more forgiving than a reader would expect. A letter stops the numeric value, a space inside the digits is skipped, and a trailing letter after the digits is ignored:
IDENTIFICATION DIVISION.
PROGRAM-ID. JUNK.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 A-F PIC X(6) VALUE "12A".
01 B-F PIC X(6) VALUE "A12".
01 C-F PIC X(6) VALUE "1 2".
01 N-F PIC 9(4).
PROCEDURE DIVISION.
COMPUTE N-F = FUNCTION NUMVAL(A-F).
DISPLAY "12A -> " N-F.
COMPUTE N-F = FUNCTION NUMVAL(B-F).
DISPLAY "A12 -> " N-F.
COMPUTE N-F = FUNCTION NUMVAL(C-F).
DISPLAY "1 2 -> " N-F.
STOP RUN.
cobc -x -free -Wall -o junk junk.cob
./junk
12A -> 0012
A12 -> 0012
1 2 -> 0012
Three different pieces of junk gave the same twelve, and no clause reported anything, because the function did what it is defined to do: it found digits. The next lesson parses a line with UNSTRING and tests every field before it is used, which is the only way to know that a value came from a number at all.
Exercises
- Read "-12.5" with NUMVAL into PIC S9(3)V9 and print it. Which sign appears?
- Change the currency sign in the NUMVAL-C call to "EUR" and read "EUR1,234.50". What does the amount become, and why?
- Move a text field holding " 9.5" into a PIC 9(2) field. Which digits arrive, and what happens to the fraction?
- Convert a text of nine digits into PIC 9(9), then into PIC 9(6) with ON SIZE ERROR. Which of the two runs reports the error?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does
FUNCTION NUMVALreturn for a text field holding " 12.34 "?Answer
The number 12.34, because the spaces around it are ignored
NUMVAL skips the surrounding spaces and reads the sign, the digits and the decimal point.
-
What does
FUNCTION NUMVAL-Cneed thatNUMVALdoes not?Answer
The currency sign as its second argument
NUMVAL-C takes the currency symbol as an argument and ignores the thousands separators on its own.
-
How does a MOVE from a
PIC X(6)field into aPIC 9(4)field convert its value?Answer
It reads digits from the left, stops at the first non-digit and fills the rest with zeros
The move converts the leading digit characters, pads the remaining positions with zeros and ignores whatever follows the first non-digit.
-
What is in the receiving field after a conversion that raised ON SIZE ERROR?
Answer
Zeros: the statement did not store a truncated value
A size error leaves the receiving field at zero, which the program on this page prints after the handler ran.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 T-F PIC X(5) VALUE " 42 ". 01 N-F PIC 9(3). PROCEDURE DIVISION. COMPUTE N-F = FUNCTION NUMVAL(T-F). DISPLAY "[" N-F "]". STOP RUN.Answer
[042]
The value is 42 and the picture is three digits, so DISPLAY writes a leading zero.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 T-F PIC X(6) VALUE "7.5". 01 N-F PIC 9(2)V9. PROCEDURE DIVISION. COMPUTE N-F = FUNCTION NUMVAL(T-F). DISPLAY N-F. STOP RUN.Answer
07.5
NUMVAL reads 7.5 and the receiving picture has two integer digits and one decimal, so the output is 07.5.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 M-F PIC X(8) VALUE "$1,250". 01 N-F PIC 9(5). PROCEDURE DIVISION. COMPUTE N-F = FUNCTION NUMVAL-C(M-F). DISPLAY N-F. STOP RUN.Answer
01250
The dollar sign is the currency argument and the comma is ignored, so the value is 1250 in a five-digit field.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 T-F PIC X(4) VALUE "12AB". 01 N-F PIC 9(2). PROCEDURE DIVISION. MOVE T-F TO N-F. DISPLAY N-F. STOP RUN.Answer
12
The move converts the leading digits 12 and stops at the letter, so the two-digit field holds 12.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q9. DATA DIVISION. WORKING-STORAGE SECTION. 01 T-F PIC X(4) VALUE "AB12". 01 N-F PIC 9(2). PROCEDURE DIVISION. MOVE T-F TO N-F. DISPLAY "[" N-F "]". STOP RUN.Answer
[00]
The first character is not a digit, so no digit is read at all and the field holds zeros.
-
A program reads a code field "12AB" with NUMVAL and gets 12, with no error. What should it do instead?
Answer
Test that the field holds only digits before it converts it
NUMVAL stops at the first non-digit without reporting it, and a MOVE does the same, so the field has to be validated character by character.
The code on this page was built with cobc (GnuCOBOL) 3.2.0 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev