Home The Company Publications Products Links Tips Jobs

Example of an Error Routine

Using *ERROR-TA, USR0020N, and USR2010N

By Dieter W. Storr

Last update: 30 June 2006


How can I write a central error routine and including the long name of the error text?


At first, all programs should have an ON ERROR statement, which uses *ERROR-TA and calling a central error routine, for example:
1440 *                         
1450 ON ERROR                  
1460   *ERROR-TA := 'NPPERROR' 
1470 END-ERROR                 
1480 *                         

When ON ERROR block entered for execution, program is interrupted and can only be resumed with RETRY. Exit ON ERROR block with FETCH, STOP, TERMINATE, RETRY, or ESCAPE ROUTINE.

Each module of subroutine built with CALLNAT, PERFORM, or FETCH RETURN may contain an ON ERROR statement. If error occurs, Natural traces back to select first ON ERROR statement for processing; if none found, program terminates.

Applicable system variables: *ERROR-NR and *ERROR-LINE.

This system variable *ERROR-TA (A8) contains the name of the program, which is to receive control in the event of an error condition.

When an error occurs, Natural will execute a STACK TOP DATA statement and place at the top of the stack the following information, which can be used as INPUT data by an error transaction: Error number (N4 if SG=OFF; N5 if SG=ON), Line number (N4), Status (A1), Program name (A8), Level (N2). If the Status is "L", the Line number will be "0". The Status may be one of the following:

  • C = Command processing error.
  • L = Logon error.
  • O = Object time error.
  • S = Non-correctable Syntax error.
  • R = Error on Remote server (in conjunction with Natural RPC).

Central Error Routine

The central error routine, for example NPPERROR, receives the error information from the stack via *ERROR-TA by using the statement "INPUT ERR-NR ERR-LINE ERR-STAT ERR-PGM ERR-LVL." It can be used from online and batch and reads additional information with USR0020N (error text) and USR2010N (DB error information).

* NAT-PAD   Program Administration and Documentation    
* NPPERROR:   NAT-PAD Central Error Routine                            
* Input:      ERR-NR ERR-LINE ERR-STAT ERR-PGM ERR-LVL                 
* Subroutine: CALLNAT 'USR0020N' PARM-AREA RETURN-AREA                 
*             CALLNAT 'USR2010N' DB_ERR_STR
* Date        Name      Change and Enhancements    
* -------------------------------------------------------------------- 
* 10/31/1998  D.Storr   data base information user exit USR0610N        
*                       DB_DBID and DB_FNR from B1 to B2               
* 03/18/1999  D.Storr   Back to B1 - Georg Schmitt SAG-DA:             
*                       For 2 byte DBID,FNR please use USR2010N.       
* 03/23/1999  D.Storr   Changed USR0610N to USR2010N                    
* ------------------------(C) www.storrconsulting.com ---------- 
1 ERR-NR       (N4)                                                   
1 ERR-LINE     (N4)                                                   
1 ERR-STAT     (A1)                                                   
1 ERR-PGM      (A8)                                                   
1 ERR-LVL      (N2)                                                   
1 INFO         (A78)                                                  
1 PARM-AREA              /* Parameters for CALLNAT                    
  2 TYPE         (A1)    /* U or N ( User or NATURAL messages )       
  2 APPLICATION  (A8)    /* Must not be blank for type = 'U'          
  2 #ERROR-NUMBER (N4)   /* 1 thru 9999                               
  2 LANG-CODE    (A1)    /* E,G,F,S,I,D and 1,2,3,4,5,6,7,8,9 allowed 
  2 RESPONSE     (N4)    /* Error during execution of USR0020N        
1 RETURN-AREA            /* Contains the message texts                
  2 S-FOUND (L) INIT   /*  TRUE means 'Short text found'       
  2 L-FOUND (L) INIT   /*  TRUE means 'Long text found'        
  2 SHORT-TEXT (A65)     INIT     <'<<< Short text not found >>>'>    
  2 LONG-TEXT (A78/1:20) INIT ALL <'<<< Long text not found >>>'>  
01 DB_ERR_STR       (A16)                                          
01 REDEFINE DB_ERR_STR                                             
  02 DB_STATUS      (A1)                                           
  02 DB_TYPE        (A1)                                           
  02 DB_DBID        (B2)                                           
  02 DB_FNR         (B2)                                           
  02 DB_COMMAND     (A2)                                           
  02 DB_RESP        (B2)                                           
  02 DB_SUBCODE     (B2)                                           
  02 DB_ADD1F2B     (B2)                                           
1 #TERM             (I4) INIT <999>                                
SET KEY ALL                                                        
SET CONTROL 'MB'                                                   
SET CONTROL 'YN'                                                     
SET KEY PF3 NAMED 'end'                                              
SET KEY PF12 NAMED 'term'                                            
MOVE 'N'        TO TYPE            /* NATURAL system messages      
MOVE 'NAT'      TO APPLICATION     /* Current application          
MOVE ERR-NR     TO #ERROR-NUMBER   /* Recent error code            
* MOVE 2          TO LANG-CODE       /* language code German         
MOVE 1          TO LANG-CODE       /* language code English        
CALLNAT 'USR0020N' PARM-AREA RETURN-AREA                           
IF RESPONSE > 0                                                    
  DECIDE ON FIRST VALUE OF RESPONSE                                
    VALUE 1    MOVE 'Wrong message type'   TO INFO                 
    VALUE 2    MOVE 'Wrong application'    TO INFO                 
    VALUE 3    MOVE 'Wrong error number'   TO INFO                 
    VALUE 4    MOVE 'Wrong language code'  TO INFO         
    NONE VALUE                                             
      COMPRESS 'Return code of USR0020N:' RESPONSE TO INFO 
  IF S-FOUND                                               
    MOVE SHORT-TEXT TO INFO                                
    IF L-FOUND                                             
      MOVE LONG-TEXT (1) TO INFO                           
IF *DEVICE NE 'BATCH'                     
  BACKOUT TRANSACTION                   
  INPUT USING MAP 'NPMERROR'   /* map similar to batch
  IF *PF-KEY = 'PF12'                                             
  IF *PF-KEY = 'PF3'                        
  WRITE 'Error occurred during program execution'       
    /   '---------------------------------------'     
    /     'Program     :' ERR-PGM                                 
    /     'Line number :' ERR-LINE                                
    /     'Error number:' ERR-NR                                  
    /     INFO                                                    
  WRITE /// 'Status Type   DBID   FNR CMD Resp Subc ADD1'   
    / 2X DB_STATUS                                       
    5X DB_TYPE                                           
    4X DB_DBID        (EM=HHHH)                          
    3X DB_FNR         (EM=HHHH)                          
    2X DB_COMMAND                                        
    1X DB_RESP        (EM=HHHH)                          
    1X DB_SUBCODE     (EM=HHHH)                          
    1X DB_ADD1F2B     (EM=HHHH)                          
  BACKOUT TRANSACTION                                    
  TERMINATE #TERM                                        

Online Error Report

17:03:52                   *** N A T - P A D ***                    2006-06-28
DIETER                         Error Report                         NATPAD  
The following error occurred in your application                              
             Program     : STR-PAIN                                            
             Line        : 730                                                 
             Error number: 1302                                                
Division by zero not permitted by parameter ZD=ON.                            
 Status  Type  DBID    FNR  CMD Resp  Subc  ADD1                              
               0000   0000      0000  0000  0000                              
                  end                                                   term

Top Page

Back to NATURAL Tips, Tricks, Techniques -- Overview