View source for DosSendSignal

[[image:legacy.png]]
This function has been eliminated since OS/2 2.0 [https://books.google.com.ec/books?id=u7WbsmbttwYC&pg=PT372&lpg=PT372&dq#v=onepage&q&f=false]


==Description==
This call sends either a SIGINTR or a SIGBREAK signal to a process within a specified process tree.
==Syntax==
<PRE>
 DosSendSignal

    (PID, SigNumber)
</PRE>

==Parameters==
;  PID (USHORT) - input : Root process ID of the subtree. It is not necessary that this process be alive, but it is necessary that this process be a direct child process of the process that issues this call. 

; SigNumber (USHORT) - input : Signal to send. It may be:

 '''Value        Definition'''
 1        (SIGINTR) Ctrl-C
 4        (SIGBREAK) Ctrl-Break.

==Return Code==
 rc (USHORT) - return

Return code descriptions are:

* 0          NO_ERROR 
* 1          ERROR_INVALID_FUNCTION 
* 156        ERROR_SIGNAL_REFUSED 
* 205        ERROR_NO_SIGNAL_SENT 
* 209        ERROR_INVALID_SIGNAL_NUMBER 
* 303        ERROR_INVALID_PROCID

==Remarks==
The process that receives the signal is the most distant descendent process among those processes in the tree that have a handler installed for the signal.

The process tree is searched in descending order for processes having a handler installed for the specified signal. If there is at least one eligible process in the tree, the signal is sent to the process that is the most distant descendent process among the eligible processes. The selected process may have descendents, but none of them have the handler installed for the signal. If there is more than one most distant descendent eligible process, the signal is sent to one of them; which one is indeterminate.

Presentation Manager applications may not establish signal handlers for Ctrl-C and Ctrl-Break. Establishing a signal handler for Ctrl-C and Ctrl-Break is supported for VIO-Windowable and full-screen applications. 
==Example Code==
=== C Binding===
<PRE>
#define INCL_DOSSIGNALS

USHORT  rc = DosSendSignal(PID, SigNumber);

USHORT           PID;           /* PID of root of subtree */
USHORT           SigNumber;     /* Signal Number to send */

USHORT           rc;            /* return code */
</PRE>
'''Example'''

The following example illustrates the use of the Ctrl-C (SIGINTR) signal to signal time-critical events. Process1 invokes process2, which establishes a signal handler named CtrlC_Handler() and waits, by blocking on a reserved RAM semaphore, for a signal from process1. A portion of process2 is immune to signalling. 

<PRE>
/***** process1.c *****/

#define INCL_DOSPROCESS
#define INCL_DOSSIGNALS

#include <os2.h>

#define SLEEPTIME       200L              /* Sleep interval */
#define START_PROGRAM   "process2.exe"    /* Program name */


main()
{
  CHAR          ObjFail[50];
  PSZ           Args;
  PSZ           Envs;
  RESULTCODES   ReturnCodes;
  USHORT        rc;

  /* Start process2 and check its PID */
  if(!(DosExecPgm(ObjFail,               /* Object name buffer */
                  sizeof(ObjFail),       /* Length of obj. name buffer */
                  EXEC_ASYNC,            /* Execution flag */
                  Args,                  /* Ptr. to argument string */
                  Envs,                  /* Ptr. to environment string */
                  &ReturnCodes,          /* Ptr. to resultcodes
                                                 struct. */
                  START_PROGRAM)))       /* Name of program file */
    printf("Process2 started.\n");
  printf("Process2 ID is %d\n", ReturnCodes.codeTerminate);

  /* Sleep to give time slice to process2 */
  DosSleep(SLEEPTIME);                   /* Sleep interval */

  /*** After process2 sets signal handler, send process2 a signal ***/
  if(!(rc = DosSendSignal(ReturnCodes.codeTerminate,  /* PID of process2 */
                          SIG_CTRLC)))                /* Signal to send */
    printf("Ctrl-C signal sent from Process1 to Process2.\n");
}

/* ----- process2.c ----- */

#define INCL_DOSPROCESS
#define INCL_DOSSIGNALS
#define INCL_DOSERRORS

#include <os2.h>

#define SLEEPTIME         50L
#define TIMEOUT           5000L


VOID APIENTRY CtrlC_Handler(arg1, arg2)    /** Define signal handler **/
  USHORT      arg1;
  USHORT      arg2;
{
  printf("Handler for Ctrl-C now running.\n");
  return;
}


main()
{
  ULONG            RamSem = 0L;   /* Allocate and initialize Ram Semaphore */
  ULONG far        *RamSemHandle = &RamSem;  /* Ram Semaphore handle */
  USHORT           rc;

  /* Establish signal handler */
  if(!(rc=DosSetSigHandler((PFNSIGHANDLER) CtrlC_Handler,
                           NULL,          /* Previous handler - ignored */
                           NULL,          /* Previous action - ignored */
                           SIGA_ACCEPT,   /* Request type */
                           SIG_CTRLC)))   /* Signal number */
    printf("Process2 has set Ctrl-C handler.\n");
  else
    /* Error processing on rc */;
  /* Get semaphore for first time */
  if(!(rc=DosSemRequest(RamSemHandle,       /* Semaphore handle */
                        TIMEOUT)))          /* Timeout interval */
    printf("Semaphore obtained.\n");

  /*** Disable and then enable signal-handling ***/
  if(!(rc=DosHoldSignal(HLDSIG_DISABLE)))   /** Action code - disable **/
  {
    printf("Signalling DISABLED.\n");

    /* Do signal-proof work here */
    if(!(rc=DosHoldSignal(HLDSIG_ENABLE)))  /** Action code - enable **/
      printf("Signalling ENABLED.\n");
  }
  /* At this point, process1 may have sent a Ctrl-C signal. */
  /* Try to obtain semaphore again -- resulting in Timeout. */
  /* The Timeout, however, may be interrupted by the signal. */

  printf("Process2 will now wait on a Ramsem for a while.\n");
  if((rc=DosSemRequest(RamSemHandle,     /* Semaphore handle */
                       TIMEOUT))         /* Timeout interval */
     == ERROR_INTERRUPT)
  printf("Process2 interrupted while waiting, rc is %d.\n", rc);
}

</PRE>
===MASM Binding===
<PRE>
EXTRN  DosSendSignal:FAR
INCL_DOSSIGNALS     EQU 1

PUSH   WORD    PID           ;PID of root of subtree
PUSH   WORD    SigNumber     ;Signal Number to send
CALL   DosSendSignal

Returns WORD
</PRE>

==Related Functions==
* 

[[Category:The OS/2 API Project]]