DosStartTimer

DosStartTimer starts an asynchronous, repeated-interval timer, and posts an event semaphore each time the specified time interval expires.

Syntax
DosStartTimer(msec, hsem, phtimer)

Parameters

 * msec (ULONG) - input : The time, in milliseconds, that will elapse between postings of the event semaphore specified by hsem.
 * The system rounds this value up to the next clock tick.


 * hsem (HSEM) - input : The handle of the event semaphore that is posted each time msec elapses.
 * This semaphore must be a shared event semaphore. It should be reset between postings by calling DosResetEventSem.


 * phtimer (PHTIMER) - output : A pointer to the timer handle.
 * This handle can be passed to DosStopTimer to stop the repeated-interval timer.

Return Code
For a full list of error codes, see Errors.
 * ulrc (APIRET) - returns:DosStartTimer returns one of the following values:
 * 0 NO_ERROR
 * 323 ERROR_TS_SEMHANDLE
 * 324 ERROR_TS_NOTIMER

Remarks
Time intervals for DosStartTimer, DosAsyncTimer, and DosSleep are specified in milliseconds; however, it is important to recognize that the actual duration of the specified time interval will be affected by two factors:
 * First, the system clock keeps track of time in less precise units known as clock ticks. The duration of a clock tick depends on the frequency of the system-clock interrupt that is used by your computer. (To determine the duration of the clock tick on your computer, issue DosQuerySysInfo and examine the timer-interval field.)
 * Because clock ticks are less precise than millisecond values, any time interval that is specified in milliseconds will be rounded up to the next clock tick.

These factors usually cause the timer interval to be longer than requested; however, it will generally be within a few clock ticks.
 * Second, because the system is a priority-based, multitasking operating system, there is no guarantee that a thread will resume immediately after the timer interval expires. If a higher-priority process or thread is running, or if a hardware interrupt occurs, the timed thread blocks. (To minimize the inaccuracy caused by preemptive scheduling, an application can dedicate a thread to managing time-critical tasks and then raise that thread to a higher priority.)

Example Code
This example sets up a periodic interval timer of 2 seconds, and lets it run for a while. 
 * 1) define INCL_DOSSEMAPHORES  /* Semaphore values */
 * 2) define INCL_DOSDATETIME    /* Timer support    */
 * 3) define INCL_DOSERRORS      /* DOS error values */
 * 4) include 
 * 5) include 

int main(VOID) {

HEV    hevEvent1     = 0;                   /* Event semaphore handle    */ HTIMER htimerEvent1  = 0;                   /* Timer handle              */ APIRET rc            = NO_ERROR;            /* Return code               */ ULONG  ulPostCount   = 0;                   /* Semaphore post count      */ ULONG  i             = 0;                   /* A loop index              */

rc = DosCreateEventSem(NULL,          /* Unnamed semaphore            */                           &hevEvent1,     /* Handle of semaphore returned */                           DC_SEM_SHARED,  /* Indicate a shared semaphore  */                           FALSE);         /* Put in RESET state           */ if (rc != NO_ERROR) { printf("DosCreateEventSem error: return code = %u\n", rc); return 1; }   rc = DosStartTimer(2000L,              /* 2 second interval            */                       (HSEM) hevEvent1,   /* Semaphore to post            */                       &htimerEvent1);     /* Timer handler (returned)     */ if (rc != NO_ERROR) { printf("DosStartTimer error: return code = %u\n", rc); return 1; }

for (i = 1 ; i < 6 ; i++) {

rc = DosWaitEventSem(hevEvent1,15000L); /* Wait 15 seconds for timer */ if (rc != NO_ERROR) { printf("DosWaitEventSem error: return code = %u\n", rc); return 1; }

rc = DosResetEventSem(hevEvent1,      /* Reset the semaphore         */                            &ulPostCount);   /* And get count (should be 1) */ if (rc != NO_ERROR) { printf("DosWaitEventSem error: return code = %u\n", rc); return 1; }

printf("Iteration %u: ulPostCount = %u\n", i, ulPostCount);

} /* for loop */

rc = DosStopTimer(htimerEvent1);      /* Stop the timer             */ if (rc != NO_ERROR) { printf("DosCloseEventSem error: return code = %u\n", rc); return 1; }

rc = DosCloseEventSem(hevEvent1);     /* Get rid of semaphore       */ if (rc != NO_ERROR) { printf("DosCloseEventSem error: return code = %u\n", rc); return 1; }

return NO_ERROR; } 

Related Functions

 * DosAsyncTimer
 * DosCreateEventSem
 * DosGetDateTime
 * DosOpenEventSem
 * DosResetEventSem
 * DosSetDateTime
 * DosSleep
 * DosStopTimer
 * DosWaitEventSem