Cancel handlers provide control

Cancel handlers allow you to get control for cleanup and recovery actions when call stack entries are terminated by something other than a normal return. For example: system request "2", "C"ancel response to inquiry message, abnormal session end (shutting off an RF unit or terminal session), or someone ending a batch job with the EndJob command. Another use would be a constant batch job. You could register a cancel handler that submits a job to batch invoking a program to restart this job. This way, if the job is canceled for any reason, the program is automatically restarted.

ILE Cancel handlers must be registered at run time using bindable APIs. Registration (CEERTX) specifies the name of the procedures to get control when cancellation occurs. Once registered, the cancel handler remains in effect until the call stack entry is removed, or until CEEUTX is called to disable it.

In the example below, in the case of an abnormal end, all that needs to be done is to update 1 field in 1 file. Also, this particular cancel handler resides in the same source as the registering procedure, so it has access to data defined in the main procedure.

If your ILE RPG procedure is called by an ILE CL procedure in the same activation group, and the caller is monitoring for status or notify messages, then your ILE CL caller may get control prematurely because of a notify or status message that the ILE RPG procedure was trying to ignore.

To avoid this problem you can either make sure that the caller is in a different activation group for the ILE RPG procedure or enable an ILE condition handler in the RPG procedure. In the handler, if the message is one that you want to ignore, indicate that the message should be handled.

Online information is available at The RPG Source and
ILE RPG for AS/400 Programmer's Guide

Questions:

Do I have to unregister the cancel handler?
No, the handler is associated with the stack entry; therefore, when it ends the knowledge of the handler ends. Stack entries in ILE are procedures.

Can a cancel handler be used for any procedure?
Yes, you can use one for any procedure, not just your main program. Please note that the cancel handler applies only to the procedure that it is registered in.

What other uses would there be for a cancel handler?
It's great way to ensure that you delete temporary objects, remove locks, free storage, etc. You can safely use cancel handlers. Simplify your cancel handlers so that they only unlock or release resources and do not attempt to acquire any new resources or locks.

What happens if the cancel handler fails?
In the event that the cancel handler itself fails, the system prevents an infinite loop by ending the cancel handler.

*************** Beginning of data ***************************** 
 /if not defined(pCanClHdlr)                                   
 /define pCanClHdlr                                            
 ************************************************************* 
 * Name: pCanClHdlr    Libr: SRVPGMLIB                        
 * Text: Register/ Unregister ILE cancel handler (IBM: CEERTX)  
 ************************************************************* 
 *Parameter definition for the CEERTX API                      
D CanclHdlrPtr    S               *   PROCPTR                  
D                                     INZ(%paddr('CANCLHDLR')) 
 *Register                                                     
D RegCanClHdlr    PR                  EXTPROC('CEERTX')        
D   pCanclHdlr                    *    PROCPTR                 
D   errInfo                       *    CONST OPTIONS(*OMIT)    
D   FeedBack                    12     OPTIONS(*OMIT)          
 *Unregister                                                   
D UnRegCanClHdlr  PR                  EXTPROC('CEEUTX')        
D   pCanclHdlr                    *    PROCPTR                 
D   FeedBack                    12     OPTIONS(*OMIT)          
D       PR                                           
D   DataPtr                       *   OPTIONS(*OMIT)  
D                                     CONST           
  /endif      

Program example:

  ** FILE DEFINITION SECTION                                   
  ****************************************************         
 FDSBCCU1D  CF   E             WORKSTN                         
 FDSIPBM4L  IF   E           K DISK    RENAME(DSIPBMR:IPBM4)    
        : 
 /copy qCpySrc,pCanclHdlr       
        : 
****************************************************       
 ** MAIN TRANSACTION CONTROL                                
 ****************************************************       
 *Register cancel handler at the beginning of the main 
 *By making a prototyped call to the CEERTX API.            
 *Used to clean up records during abnormal end. 
 *The 2nd is optional and could point to a data structure 
 *that would contain the necessary data to end the program.          
C                   CALLP     REGCANCLHDLR(CanClHdlrPtr:    
C                             *OMIT : *OMIT)                
        :       : 
 *Calling IBM API to unregister cancel handler (end of main)       
 *Clean up records  
 *Put this right befor EVAL *INLR = *ON                                          
C                   CALLP     UNREGCANCLHDLR(CanClHdlrPtr:    
C                             *OMIT)                          
C                   EVAL      *INLR = *ON                     
C                   RETURN                                  
  ****************************************************     
        : 
*End of last subroutine.......   
C                   ENDSR                            
****************************************************              
*Procedure Interface Must be at end of program.                   **************************************************** 
*Control happens when abnormal end occurs.                                          
 P CanClHdlr       B                                                          
 D CanClHdlr       PI                                                         
 D   DataPtr                       *   OPTIONS (*OMIT)                        
 D                                     CONST                                 
  *Action to take during abnormal end                               
  *Updating file to release for use next time.                         
 C     BCCSN         CHAIN     DSBCCC1P                                      
 C                   EVAL      BCUSTS = ' '                                   
 C                   UPDATE    DSBCCCR                                        
 P                 E                                                                  
 ****************** End of data ****************