DosStartTimer
Description
Starts an asynchronous, repeated-interval timer.
Syntax
#define INCL_DOSDATETIME
#include <os2.h>
ULONG msec; /* The time, in milliseconds, that will elapse between postings
of the event semaphore specified by hsem. */
HSEM hsem; /* The handle of the event semaphore that is posted each time msec elapses. */
PHTIMER phtimer; /* A pointer to the timer handle. */
APIRET ulrc; /* Return Code. */
ulrc = 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
ulrc (APIRET) - returns
DosStartTimer returns one of the following values:
- 0 NO_ERROR
- 323 ERROR_TS_SEMHANDLE
- 324 ERROR_TS_NOTIMER
For a full list of error codes, see Errors.
Remarks
DosStartTimer starts an asynchronous, repeated-interval timer, and posts an event semaphore each time the specified time interval expires.
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.
- 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.)
These factors usually cause the timer interval to be longer than requested; however, it will generally be within a few clock ticks.
Example Code
This example sets up a periodic interval timer of 2 seconds, and lets it run for a while.
#define INCL_DOSSEMAPHORES /* Semaphore values */
#define INCL_DOSDATETIME /* Timer support */
#define INCL_DOSERRORS /* DOS error values */
#include <os2.h>
#include <stdio.h>
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;
}