What's the use of `NOT ON OVERFLOW` in COBOL?

Question

From my understanding when using UNSTRING, the use of ON OVERFLOW [INSTRUCTION] will be useful if there would be an overflow in the use of the UNSTRING.

But if there is no overflow, why would you use NOT ON OVERFLOW [INSTRUCTION] ?

The only possible utility to the NOT ON OVERFLOW [INSTRUCTION] would be to pass an instruction if there is no overflow but what would be the use of that if you already had the expected result from the UNSTRING ?

Is there any concrete example of how this could be useful in this example :

IDENTIFICATION DIVISION.
PROGRAM-ID. YOUR-PROGRAM-NAME.
DATA DIVISION.
FILE SECTION.


WORKING-STORAGE SECTION.
    01 WS-VAR1 PIC A(11) VALUE "Hello World".
    01 WS-VAR2 PIC A(5).
    01 WS-VAR3 PIC A(5).
    01 WS-COMPTEUR PIC 9 VALUE 2.

PROCEDURE DIVISION.
MAIN-PROCEDURE.
    INTO WS-VAR2 WS-VAR3
    WITH POINTER WS-COMPTEUR
    ON OVERFLOW DISPLAY "This string is too large"
    END-UNSTRING.

    DISPLAY WS-VAR2
    DISPLAY WS-VAR3.
    STOP RUN.
END PROGRAM YOUR-PROGRAM-NAME.

Even when I read IBM documentation, it doesn't give me much explanation as to what could be used in this instance but to display a message ?

IBM Documentation : link

Answer 1

From my understanding when using UNSTRING, the use of ON OVERFLOW phrase will be useful if there would be an overflow in the use of the UNSTRING.

But if there is no overflow, why would you use NOT ON OVERFLOW phrase ?

The only possible utility to the NOT ON OVERFLOW phrase would be to pass an instruction if there is no overflow but what would be the use of that if you already had the expected result from the UNSTRING ?

In COBOL 74 there was no NOT ON OVERFLOW phrase. Therefore, it was necessary to use either a GO TO statement or set a flag for testing in an immediately following IF statement. The NOT ON OVERFLOW phrase and END-UNSTRING were added in COBOL 85 to to improve program structure.

For your example, I made some changes to first display WS-VAR1 then the result of the UNSTRING. Note that the OVERFLOW condition concerns the number of items and not the length of the text. I ran three tests to show the results

   IDENTIFICATION DIVISION.
   PROGRAM-ID. YOUR-PROGRAM-NAME.
   DATA DIVISION.
   WORKING-STORAGE SECTION.
   01 WS-VAR1 PIC A(11) VALUE "Hello World".
   01 WS-VAR2 PIC A(5).
   01 WS-VAR3 PIC A(5).
   PROCEDURE DIVISION.
   MAIN-PROCEDURE.
       MOVE SPACE TO WS-VAR2 WS-VAR3
       DISPLAY WS-VAR1
       UNSTRING WS-VAR1
       DELIMITED SPACE
       INTO WS-VAR2 WS-VAR3
       ON OVERFLOW
           DISPLAY
               "Incorrect number of items in WS-VAR1 - expected 2"
       NOT ON OVERFLOW
           DISPLAY WS-VAR2
           DISPLAY WS-VAR3
       END-UNSTRING
       STOP RUN.
   END PROGRAM YOUR-PROGRAM-NAME.

Results:

Hello World
Hello
World
--
Hello
Incorrect number of items in WS-VAR1 - expected 2
--
Hello W rld
Incorrect number of items in WS-VAR1 - expected 2

As may be seen in the code, ON OVERFLOW is used for error processing; NOT ON OVERFLOW is used for normal processing. Without the improved structure from NOT ON OVERFLOW, normal processing would immediately follow the error processing, unless one used the previously mentioned COBOL 74 type processing.

Note that DELIMITED ALL SPACE gives a different result than that shown for one case, above. [Ignore the --]

--
Hello
Hello

--

Answer 2

You can use the "NOT ON OVERFLOW " statement if you need to call a PROCEDURE to validate this sentence for example SORT-COLORS.

MOVE 0 TO COUNT-1.   

UNSTRING COLOR-LIST   
   DELIMITED BY ":" OR "/" OR ALL SPACE   
*DELIMIT-1 and COUNT-1 will hold only   
*the values associated with COLOR-1.   
   INTO COLOR-1   
         DELIMITER IN DELIMIT-1   
         COUNT IN COUNT-1,   
         COLOR-2,   
         COLOR-3,   
         COLOR-4   
   ON OVERFLOW    
      DISPLAY "overflow: unstring colors"   
   NOT ON OVERFLOW   
*do when UNSTRING succeeds.   
      PERFORM **SORT-COLORS**   
END-UNSTRING.   
*COLOR-1 = "RED   "   
*COLOR-2 = "BLUE  "   
*COLOR-3 = "GREEN "   
*COLOR-4 = "YELLOW"   
*DELIMIT-1 = ":  "   
*COUNT-1 = 3 count-1 holds the number of characters in RED   

You can see more examples on this link https://supportline.microfocus.com/documentation/acucorpproducts/docs/v6_online_doc/gtman3/gt36141.htm

On practice if youy need to discovery if your command(unsting) are executed with sucess withou a IF you can use this statement to define it.

An example using your aplication

IDENTIFICATION DIVISION.
PROGRAM-ID. YOUR-PROGRAM-NAME.
DATA DIVISION.
FILE SECTION.


WORKING-STORAGE SECTION.
    01 WS-VAR1 PIC A(11) VALUE "Hello World".
    01 WS-VAR2 PIC A(5).
    01 WS-VAR3 PIC A(5).
    01 WS-COMPTEUR PIC 9 VALUE 2.

PROCEDURE DIVISION.
MAIN-PROCEDURE.
    INTO WS-VAR2 WS-VAR3
    WITH POINTER WS-COMPTEUR
    ON OVERFLOW 
        PERFORM RT-SEND-ERROR-MAIL
    NOT ON OVERFLOW 
        PERFORM RT-SEND-SUCESS-MAIL
    END-UNSTRING.

    DISPLAY WS-VAR2
    DISPLAY WS-VAR3.
    STOP RUN.
END PROGRAM YOUR-PROGRAM-NAME.