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;
}

Related Functions

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