DosEnterCritSec

Disables thread switching for the current process.

Syntax
DosEnterCritSec

Return Code

 * ulrc (APIRET) - returns:DosEnterCritSec returns one of the following values:
 * 0 NO_ERROR
 * 309 ERROR_INVALID_THREADID
 * 484 ERROR_CRITSEC_OVERFLOW

Remarks
DosEnterCritSec causes all other threads in the process to block themselves and give up their time slice. After a DosEnterCritSec request is made, no functions should be called that depend on another thread to do processing until DosExitCritSec has completed. Great care should be taken when using compiler runtime functions and other OS/2 functions after a DosEnterCritSec request has been made, since the underlying processing of the called function may require processing by another thread and thus cause a deadlock.

A thread can also execute code without having to give up time slices to other threads in its process if it requests a priority class that is higher than those of the other threads. A thread's priority is examined with DosGetInfoBlocks, and changed with DosSetPriority.

A count is maintained of the number of times DosEnterCritSec is issued without a corresponding DosExitCritSec. The count is incremented by DosEnterCritSec and decremented by DosExitCritSec. Normal thread dispatching is not restored until the count is zero. The outstanding DosEnterCritSec count is maintained in a word. If an overflow occurs, the count is set to the maximum value, no operation is performed, and the request returns with ERROR_CRITSEC_OVERFLOW.

If a signal occurs, thread 1 begins execution to process the signal even though another thread in the process has a DosEnterCritSec active. Thread 1 of a process is its initial thread of execution, not a thread created with DosCreateThread. Any processing done by thread 1 to satisfy the signal must not include accessing the critical resource intended to be protected by DosEnterCritSec.

Note: This function is very powerful and must be used with caution! It should be used only in a most cooperative environment where the state of all threads in known. While in the critical section, do not call other compiler runtime or OS/2 functions that could start another thread that it would depend on running before being able to return.

DosQueryThreadContext can be used to obtain the context of other threads in the process once they have been blocked by DosEnterCritSec.

ERROR_INVALID_THREADID is returned when an invalid attempt is made to enter a critical section of code in a signal handler or exception handler.

ERROR_INVALID_THREADID is also returned when a dynamic link library (DLL) routine incorrectly issues DosEnterCritSec.