DosAsyncTimer
Starts an asynchronous, single-interval timer.
Syntax
DosAsyncTimer(msec, hsem, phtimer)
Parameters
- msec (ULONG) - input
- The time, in milliseconds, before the event semaphore specified by hsem is posted.
- (The system rounds this value up to the next clock tick.)
- hsem (HSEM) - input
- The handle of an event semaphore that will be posted when the time specified by msec has elapsed.
- This semaphore must be a shared event semaphore, and should be reset before issuing DosAsyncTimer.
- phtimer (PHTIMER) - output
- A pointer to the timer handle.
- This handle can be passed to DosStopTimer to stop the timer before its time interval expires.
Return Code
- ulrc (APIRET) - returns
- DosAsyncTimer 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
DosAsyncTimer starts a single-interval timer. The timer runs asynchronously to the calling thread, and posts an event semaphore when the specified time interval expires.
Time intervals for DosAsyncTimer, DosStartTimer, 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, 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 the asyncronous timer to 7 seconds. After this time, it posts a message to an event semaphore.
#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) {
PSZ szSemName = "\\SEM32\\TIMER\\THREAD1\\EVENT1"; /* Semaphore name */
HEV hevEvent1 = 0; /* Event semaphore handle */
HTIMER htimerEvent1 = 0; /* Timer handle */
APIRET rc = NO_ERROR; /* Return code */
rc = DosCreateEventSem(szSemName, /* Name of semaphore to create */
&hevEvent1, /* Handle of semaphore returned */
DC_SEM_SHARED, /* Shared semaphore */
FALSE); /* Semaphore is in RESET state */
if (rc != NO_ERROR) {
printf("DosCreateEventSem error: return code = %u\n", rc);
return 1; }
rc = DosAsyncTimer(7000L, /* 7 second interval */
(HSEM) hevEvent1, /* Semaphore to post */
&htimerEvent1); /* Timer handler (returned) */
if (rc != NO_ERROR) {
printf("DosAsyncTimer error: return code = %u\n", rc);
return 1;
} else {
printf("Timer will expire in about 7 seconds...\n");
}
/* ... add your other processing here... */
rc = DosWaitEventSem(hevEvent1, /* Wait for AsyncTimer event */
(ULONG) SEM_INDEFINITE_WAIT); /* As long as it takes */
if (rc != NO_ERROR) {
printf("DosWaitEventSem 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", rc);
return 1;
}
return NO_ERROR;
}
