A user signal routine is registered in the program unit or in the Start-Exit with the function KCX_REG_USER_SIGNAL_HANDLER, i.e. user-specific signal handling is only activated once this is done.
KCX_UN_REG_USER_SIGNAL_HANDLER is used to deregister it and thus deactivate it.
Function KCX_REG_USER_SIGNAL_HANDLER
The function KCX_REG_USER_SIGNAL_HANDLER requires a function pointer that points to a user signal routine as an argument. In other words, the argument must be of the “PROCEDURE-POINTER” type and is automatically transferred using a reference, i.e. as the address of this pointer.
Note
For using theses functions, your COBOL Compiler version must support the COBOL data type "PROCEDURE-POINTER".
Micro Focus Visual Cobol 2.2 or higher supports this data type, for example.
WORKING-STORAGE section.
01 install-address-4-sig usage procedure-pointer.
PROCEDURE DIVISION USING KCKBC KCSPAB.
set install-address-4-sig to entry "MFCBLOOP-SIGNAL".
CALL "KCX_REG_USER_SIGNAL_HANDLER" USING install-address-4-sig.
Function KCX_UN_REG_USER_SIGNAL_HANDLER
Calling KCX_UN_REG_USER_SIGNAL_HANDLER from the application program deregisters, i.e. deactivates, the current user signal routine in openUTM. From this point onwards, the default openUTM error handling is activated.
The function is called without parameters.
Programming the signal routine
The user signal routine is always assigned three arguments:
Param-1
The system signal number as a binary variable 4 bytes in length, i.e. data type "PIC 9(9) COMP-5" .
Param-2
“Printable” explanation of the system signal number, e.g. “Segmentation fault” for signal 11, maximum 255 bytes long and ending with a null byte.
Param-3
Stack information, multi-line and maximum 4096 bytes long, ending with a null byte.
The user signal routine should only initiate “clear-up actions” and terminate the program with PEND RE:
KDCS call RSET
KDCS call MPUT NE with error info from the user signal routine parameters
KDCS call PEND RE with KCRN="Follow-up TAC"
Notes
The function may not be exited using "GOBACK" or "EXIT PROGRAM".
When calling the user signal routine in COBOL, it is possible that the MICRO Focus COBOL runtime system will detect a recursion and reject the call.
If this happens, the suffix “IS RECURSIVE” must be added to the definition of the PROGRAM-ID in the user program unit, e.g.:
PROGRAM-ID. MFCBLOOP IS RECURSIVE.
WORKING-STORAGE section. 01 signal-number-print pic 9(9). LINKAGE SECTION. 01 utm-stack-string pic x(4096). 01 utm-signal-string pic x(255). 01 utm-signal-number pic 9(9) COMP-5. PROCEDURE DIVISION USING KCKBC KCSPAB. ENTRY 'MFCBLOOP-SIGNAL' USING utm-signal-number utm-signal-string utm-stack-string. MOVE utm-signal-number to signal-number-print. DISPLAY "UTM-SIGNAL-NUMBER IS "signal-number-print.
This is followed by the KDCS calls RSET, MPUT and PEND RE.
Example of parameters transferred to a user signal routine
utm-signal-number: 11
utm-signal-string: "Segmentation fault"
utm-stack-string:
#6 0x00007f712cf3103f in KCSSIGNAL () from /opt/lib/utm70a00/sys/libwork.so
#7 <signal handler called>
#8 0x00007f712e6aff30 in MFCBNULL () at MFCBNULL.c:17
#9 0x00007f712e27b418 in MFCBCALL_INIT-OP () at MFCBCALL.cbl:81
#10 0x00007f712e27b267 in MFCBCALL_INIT-OP () at MFCBCALL.cbl:59
#11 0x00007f712e27ae6a in MFCBCALL () from /home/user/filebase/utmcob.so
#12 0x00007f712e904b97 in KDCCCOB2 () from /home/user/filebase/proot.so
#13 0x00007f712cf2f7e3 in KDCHLLC () from /opt/lib/utm70a00/libwork.so
#14 0x00007f712cf8e37c in START_TEILPROGRAM () from /opt/lib/utm70a00/sys/libwork.so
#15 0x00007f712cf83658 in KDCRTMM () from /opt/lib/utm70a00/sys/libwork.so
#16 0x00007f712cf91cc3 in KDCRTSI () from /opt/lib/utm70a00/libwork.so
#17 0x00007f712cf2f36c in KDCRTST () from /opt/lib/utm70a00/libwork.so
#18 0x00007f712e90487d in kcxmnt () from /home/user/filebase/proot.so
#19 0x000000000040207c in main ()