DosHoldSignal

This call temporarily disables or enables signal processing for the current process.

Syntax
DosHoldSignal (ActionCode)

Parameters

 * ActionCode (USHORT) - input : Disables or enables signals intended for the current process.
 * 0 - Signals are enabled
 * 1 - Signals are disabled.

Return Code

 * rc (USHORT) - return:Return code descriptions are:
 * 0 NO_ERROR
 * 1 ERROR_INVALID_FUNCTION

Remarks
DosHoldSignal with ActionCode = 1 causes signal processing (except central processing errors and numeric processor errors) to be postponed until a DosHoldSignal with ActionCode = 0 is issued. Any signals that occur while processing is disabled are recognized, but not accepted until signal recognition is enabled.

To allow for nesting of requests, a count of the number of outstanding DosHoldSignal requests with ActionCode = 1 are maintained.

DosHoldSignal is used by library routines, subsystems, and similar code that lock critical sections or temporarily reserve resources needed to prevent a signal from terminating a task. A process can have only one signal handling address for each signal. Dynalink routines should not have a signal handler (which might override a handler established by a calling process).

Signals can be held for a short period and should be released and re-held, if necessary. Their guidelines for proper use are similar to hardware interrupt counterparts such as the CLI/STI instructions.

Family API Considerations
Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following restriction applies to DosHoldSignal when coding for the DOS mode:

The only signal recognized in the DOS mode is SIGINTR (Ctrl-C) and SIGBREAK. Only SIGINTR and SIGBREAK are turned off by this call.

C

 * 1) define INCL_DOSSIGNALS

USHORT rc = DosHoldSignal(ActionCode);

USHORT ActionCode;    /* Indicate to Disable/Enable Signals */ USHORT rc;            /* return code */ 

MASM
 EXTRN DosHoldSignal:FAR INCL_DOSSIGNALS    EQU 1

PUSH  WORD    ActionCode    ;Indicate to Disable/Enable Signals CALL  DosHoldSignal

Returns NONE 

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. 
 * 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); } 