dos12.hlp (Table of Contents; Topic list)
Important Notice
The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.
DosTimerStart (1.2)
Function Group  Overview                          Up Next Previous
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSDATETIME
 
USHORT DosTimerStart(ulTime, hsem, phtimer)
ULONG ulTime;       /* time before semaphore is cleared     */
HSEM hsem;          /* system-semaphore handle              */
PHTIMER phtimer;    /* pointer to variable for timer handle */
 
The DosTimerStart function creates a timer that counts for a specified
number of milliseconds, then clears the specified semaphore. The function
repeats this process continually, counting the time and clearing the
semaphore, until the process stops it by using the DosTimerStop function.
The timer handle is used in the DosTimerStop function to cancel the timer.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
ulTime     Specifies the time (in milliseconds) before the semaphore is
           cleared.
 
hsem       Identifies the system semaphore that signals the end of the
           timer. This handle must have been created previously by using the
           DosCreateSem function, and it must have been created with the
           CSEM_PUBLIC flag.
 
phtimer    Points to the variable that receives the timer handle.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:
 
     ERROR_TS_NOTIMER
     ERROR_TS_SEMHANDLE
 
Comments
 
The timer runs asynchronously──that is, while the timer counts the time, the
function returns to let the process continue to execute other tasks.
 
The given semaphore must be a system semaphore. If the process uses the
semaphore to determine when data is available, it must use the DosSemSet
function to set the semaphore before calling the DosTimerStart function.
 
If necessary, the DosTimerStart function rounds up the ulTime parameter to
the next clock tick.
 
The timer may clear the semaphore several times before a process that is
waiting for the semaphore resumes execution. If the process requires an
accurate count of the time it waited, it should retrieve the current system
time from the global information segment before and after waiting for the
semaphore and compare these times.
 
See Also
 
DosCreateSem, DosGetInfoSeg, DosSemSet, DosTimerStop