DosSendSignal

This call sends either a SIGINTR or a SIGBREAK signal to a process within a specified process tree.

Syntax
DosSendSignal (PID, SigNumber)

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:
 * 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.

C

 * 1) 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 */ 

MASM
 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 

Example Code
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.  /***** process1.c *****/


 * 1) define INCL_DOSPROCESS
 * 2) define INCL_DOSSIGNALS


 * 1) include 


 * 1) define SLEEPTIME      200L              /* Sleep interval */
 * 2) 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 - */


 * 1) define INCL_DOSPROCESS
 * 2) define INCL_DOSSIGNALS
 * 3) define INCL_DOSERRORS


 * 1) include 


 * 1) define SLEEPTIME        50L
 * 2) 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); } 