DosTimerStart

This call starts a periodic interval timer that runs asynchronously to the thread issuing the request. The semaphore is continually cleared at the specified time interval until the timer is turned off by DosTimerStop.

Syntax

DosTimerStart (TimeInterval, SemHandle, Handle) 

Parameters

TimeInterval (ULONG) - input

Number of milliseconds (rounded up to the next clock tick) that passes before the semaphore is cleared.

SemHandle (HSEM) - input

Handle of the system semaphore used to communicate the time out to the calling thread. This semaphore should be set by DosSemSet before the next clear by the timer.

Handle (PHTIMER) - output

Address of the timer handle. This handle may be passed to DosTimerStop to stop the periodic timer.

Return Code

rc (USHORT) - return

Return code descriptions are:

• 0 NO_ERROR
• 323 ERROR_TS_SEMHANDLE
• 324 ERROR_TS_NOTIMER

Remarks

DosTimerStart allows a timer to start and run asynchronously to a thread. A timer interval is canceled by using the timer handle in the DosTimerStop call. This prevents the semaphore indicated in the DosTimerStart call from being sent notifications.

The application detects the expirations of the timer when the semaphore is set prior to the next expiration of the timer. When an application waits for this semaphore to clear, more than one clearing of the timer may occur before the application resumes execution. If it is necessary to determine the actual elapsed time, the Global Information Segment milliseconds field can be saved by a DosGetInfoSeg request before calling DosTimerStart. This saved value is compared to the current value when the process resumes.

Bindings

C

#define INCL_DOSDATETIME

USHORT  rc = DosTimerStart(TimeInterval, SemHandle, Handle);

ULONG   TimeInterval;  /* Interval size (in milliseconds) */
HSEM    SemHandle;     /* System semaphore handle */
PHTIMER Handle;        /* Timer handle (returned) */

USHORT  rc;            /* return code */

MASM

EXTRN  DosTimerStart:FAR
INCL_DOSDATETIME    EQU 1

PUSH   DWORD   TimeInterval  ;Interval size (in milliseconds)
PUSH   DWORD   SemHandle     ;System semaphore handle
PUSH@  WORD    Handle        ;Timer handle (returned)
CALL   DosTimerStart

Returns WORD

Example Code

The following example sets an asynchronous one-shot timer for one second. It then sets an asynchronous recurring timer with a one-second interval, reporting each time an interval elapses. Finally, it stops the recurring timer.

#define INCL_DOSDATETIME
#define INCL_DOSSEMAPHORES

#include <os2.h>

#define SEM_NAME        "\\SEM\\timer.sem"  /* Semaphore name */
#define TIME_INTERVAL   1000L               /* Timer interval (in milliseconds) */

main()
{
  HSEM      SemHandle;
  HTIMER    TimerHandle;
  USHORT    i;
  USHORT    rc;

  /* Create system semaphore to be used by timers */
  DosCreateSem(CSEM_PUBLIC,        /* Ownership - nonexclusive */
               &SemHandle,         /* Semaphore handle (returned) */
               SEM_NAME);          /* Semaphore name */

  /* Set the semaphore, then start a one-shot timer */
  if(!DosSemSet(SemHandle))        /* Semaphore handle */
    printf("Semaphore set.\n");
  if(!(rc=DosTimerAsync(TIME_INTERVAL,    /* Timer interval */
                        SemHandle,        /* Semaphore handle */
                        &TimerHandle)))   /* Timer handle (returned) */
    printf("One shot timer for %f seconds started.\n", TIME_INTERVAL/1000.0);

  /* Report when timer expires (other work may be done here) */
  if(!DosSemWait(SemHandle,               /* Semaphore handle */
                 SEM_INDEFINITE_WAIT))    /* Timeout period - indefinite */
    printf("Time interval has elapsed.\n");

  /* Start a recurring timer */
  if(!(rc=DosTimerStart(TIME_INTERVAL,    /* Timer interval */
                        SemHandle,        /* Semaphore handle */
                        &TimerHandle)))   /* Timer handle (returned) */
    printf("Recurring timer with %f second interval started.\n",
           TIME_INTERVAL/1000.0);
  /*  */
  for(i=1; i<4; i++)
    if(!DosSemSetWait(SemHandle,             /* Semaphore handle */
                      SEM_INDEFINITE_WAIT))  /* Timeout period - indefinite */
      printf("Recurring timer cleared semaphore %d times.\n", i);
  if(!(rc=DosTimerStop(TimerHandle)))        /* Timer handle */
    printf("Recurring timer has been stopped.\n");
}

Related Functions

• DosTimerStop