Difference between revisions of "DosHoldSignal"
m (Ak120 moved page OS2 API:CPI:LEGACY:DosHoldSignal to DosHoldSignal) |
m |
||
(4 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
− | |||
− | |||
− | |||
− | |||
This call temporarily disables or enables signal processing for the current process. | This call temporarily disables or enables signal processing for the current process. | ||
==Syntax== | ==Syntax== | ||
− | + | DosHoldSignal (ActionCode) | |
− | DosHoldSignal | + | |
− | |||
− | |||
==Parameters== | ==Parameters== | ||
− | ; | + | ;ActionCode (USHORT) - input : Disables or enables signals intended for the current process. |
− | + | ::0 - Signals are enabled | |
− | + | ::1 - Signals are disabled. | |
− | + | ||
− | + | ||
==Return Code== | ==Return Code== | ||
− | + | ;rc (USHORT) - return:Return code descriptions are: | |
− | + | *0 NO_ERROR | |
− | Return code descriptions are: | + | *1 ERROR_INVALID_FUNCTION |
− | + | ||
− | * 0 | + | |
− | * 1 | + | |
==Remarks== | ==Remarks== | ||
Line 34: | Line 22: | ||
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. | 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=== | ===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: | 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. | + | The only signal recognized in the DOS mode is SIGINTR (Ctrl-C) and SIGBREAK. Only SIGINTR and SIGBREAK are turned off by this call. |
− | + | ==Bindings== | |
− | == | + | ===C === |
− | ===C | + | |
<PRE> | <PRE> | ||
#define INCL_DOSSIGNALS | #define INCL_DOSSIGNALS | ||
Line 50: | Line 35: | ||
USHORT rc = DosHoldSignal(ActionCode); | USHORT rc = DosHoldSignal(ActionCode); | ||
− | USHORT | + | USHORT ActionCode; /* Indicate to Disable/Enable Signals */ |
+ | USHORT rc; /* return code */ | ||
+ | </PRE> | ||
− | + | ===MASM=== | |
+ | <PRE> | ||
+ | EXTRN DosHoldSignal:FAR | ||
+ | INCL_DOSSIGNALS EQU 1 | ||
+ | |||
+ | PUSH WORD ActionCode ;Indicate to Disable/Enable Signals | ||
+ | CALL DosHoldSignal | ||
+ | |||
+ | Returns NONE | ||
</PRE> | </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. | 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> | <PRE> | ||
#define INCL_DOSPROCESS | #define INCL_DOSPROCESS | ||
Line 66: | Line 60: | ||
#define SLEEPTIME 200L /* Sleep interval */ | #define SLEEPTIME 200L /* Sleep interval */ | ||
#define START_PROGRAM "process2.exe" /* Program name */ | #define START_PROGRAM "process2.exe" /* Program name */ | ||
− | |||
main() | main() | ||
Line 95: | Line 88: | ||
printf("Ctrl-C signal sent from Process1 to Process2.\n"); | printf("Ctrl-C signal sent from Process1 to Process2.\n"); | ||
} | } | ||
− | + | </PRE> | |
+ | <PRE> | ||
/* ----- process2.c ----- */ | /* ----- process2.c ----- */ | ||
Line 106: | Line 100: | ||
#define SLEEPTIME 50L | #define SLEEPTIME 50L | ||
#define TIMEOUT 5000L | #define TIMEOUT 5000L | ||
− | |||
VOID APIENTRY CtrlC_Handler(arg1, arg2) /** Define signal handler **/ | VOID APIENTRY CtrlC_Handler(arg1, arg2) /** Define signal handler **/ | ||
Line 118: | Line 111: | ||
main() | main() | ||
{ | { | ||
− | ULONG | + | ULONG RamSem = 0L; /* Allocate and initialize Ram Semaphore */ |
− | + | ULONG far *RamSemHandle = &RamSem; /* Ram Semaphore handle */ | |
− | ULONG far | + | USHORT rc; |
− | USHORT | + | |
/* Establish signal handler */ | /* Establish signal handler */ | ||
Line 157: | Line 149: | ||
printf("Process2 interrupted while waiting, rc is %d.\n", rc); | printf("Process2 interrupted while waiting, rc is %d.\n", rc); | ||
} | } | ||
− | |||
</PRE> | </PRE> | ||
− | + | [[Category:Dos16]] | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | [[Category: | + |
Latest revision as of 02:38, 26 January 2020
This call temporarily disables or enables signal processing for the current process.
Contents
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.
Bindings
C
#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.
#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); }