Museum

   =========================================================================
                       M I C R O  F O C U S  C O B O L

                                   V3.2.20

                           Running Under The DG/UX
                           Operating System Version 5.4.3
                           On The AViiON
   =========================================================================

                           SIGNAL HANDLING
                           ===============

   This document should be considered as additional information for the
   section "Mixing C and COBOL Programs" in the Chapter "Mixed Language
   Programming" in the COBOL User Guide. It describes the Micro Focus
   support for two routines, cobpostsighandler and cobremovesighandler,
   that you can use to complement or override the default signal handling
   used by the run-time system.

   TABLE OF CONTENTS
   =================
   OVERVIEW
   OPERATION
       Example

   OVERVIEW
   ========
   If you are mixing COBOL and C applications, you may experience problems
   when using the C routine signal(signal, handler);. If you use this C
   routine before invoking a COBOL program, your C signal handler is
   overridden. Additionally, with this C routine, only one handler is
   allowed per signal.

   This COBOL system provides two routines that you can use to complement or
   override the default signal handling used by the run-time system (RTS):
   cobpostsighandler and cobremovesighandler.

   These routines, which are used from a C program, are used to set up
   alternate signal handling within the RTS. They allow multiple handlers
   per signal and allow you to prioritize use of these handlers.

   OPERATION
   =========
   These routines have the form:

   sighandler = cobpostsighandler (signal, priority, handler) ;

   where:

       signal      specifies the signal, as defined in your signal.h file
                   in your /user/include directory.

       priority    specifies the priority of <handler>. This must be set
                   to a value of either 128 or 126. If set to 128,
                   <handler> overrides (or is processed before) the
                   default RTS handlers; If set to 126, <handler> is
                   processed after the default RTS handlers.

       handler     is the name of your signal handler. This must be a C
                   function.

   cobremovesighandler (sighandler) ;

   where:

       sighandler  specifies the signal handler assiged using the previous
                   cobpostsighandler.

   You should be aware of the following when using the cobpostsighandler
   and/or cobremovesighandler routines:

   o   Certain signals are generated by the operating system when a serious
       error has occurred. Catching these signals would cause unexpected and
       potentially dangerous results. You must not catch any of the
       following signals:

           SIGBUS
           SIGSEGV
           SIGEMT
           SIGILL
           SIGIOT / SIGABRT
           SIGSYS
           SIGFPE
           SIGTRAP

   o   Preventing the RTS processing certain signals could stop certain
       RTS functionality working. If you catch any of these signals, your
       signal handler MUST return a non-zero value so that the RTS's default
       handler is also executed. The signals concerned are:

           SIGCHLD,
           SIGPIPE,
           SIGUSR1,
           SIGCONT,
           SIGTSTP,
           SIGTTIN,
           SIGTTOU

   Notes:
   o   The cobpostsighandler and cobremovesighandler functions are only
       available with Micro Focus COBOL for UNIX systems. They will
       eventually be replaced by other functions.

   o   Micro Focus reserves the right to change their default signal
       handlers or use extra signals in the future.

   Example
   =======
   The following example illustrates how a handler for the SIGALRM signal
   could be set up.

       #include <stdio.h>
       #include <signal.h>

        int
        mysigcatch(sig)
        int sig;
        {

                cobprintf("Here is new signal handler\n");

                  return(0);  /* Do not process any further handlers */
        }

        void
        mysigexit(sighand)
        void *sighand;
        {
                cobprintf("Cancelling handler\n");
                cobremovesighandler(sighand);     /* Remove the handler */
        }

        main(argc, argv)
        int argc;
        char *argv6Y;
        {
                void *sighandle;

                 extern void *cobpostsighandler();

                 sighandle = cobpostsighandler(SIGALRM, 128, mysigcatch);
                 cobfunc("cobolprog", argc, argv); /* call a cobol program
                                                  using cobfunc function */
                 alarm(1);
                 pause();
                 sleep(4);
                 mysigexit(sighandle);
                 cobexit(0);                 /* Cobexit - close down COBOL
                                                run-time environment */
         }

   =========================================================================
   Micro Focus is a registered trademark of Micro Focus Limited.
   UNIX is a registered trademark of X/Open Company Ltd.
   =========================================================================
   @(#)Vrn/signals.1/3.2.00/29Mar94/nrV
   Copyright (C) 1993-94 Micro Focus Limited