DosTimerAsync

This function has been renamed to "DosAsyncTimer". [1]

Description

This call starts a timer that runs asynchronously to the thread issuing the request and clears a system semaphore when the specified interval expires.

Syntax

 DosTimerAsync

    (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 DosTimerAsync is called.

Handle (PHTIMER) - output

Address of the timer handle. This handle may be passed to DosTimerStop to stop this timer before its time interval expires.

Return Code

rc (USHORT) - return

Return code descriptions are:

• 0 NO_ERROR
• 323 ERROR_TS_SEMHANDLE
• 324 ERROR_TS_NOTIMER

Remarks

DosTimerAsync is used to wait for a single asynchronous time. The thread waits for the time out by issuing a DosSemWait.

This function is the asynchronous analog of DosSleep. This function allows a thread to start a timer while it is performing another task. This timer can be canceled by calling the DosTimerStop function with the timer handle returned by DosTimerAsync.

If another time out is needed, the semaphore is set and DosTimerAsync is reissued. To ensure reliable detection of the timer expiration, the system semaphore should be set prior to calling DosTimerAsync.

To set a periodic interval timer, see DosTimerStart.

Example Code

C Binding

#define INCL_DOSDATETIME

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

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

USHORT           rc;            /* return 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");
}

MASM Binding

EXTRN  DosTimerAsync: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   DosTimerAsync

Returns WORD