# OS_SetVAlarm

## C Specification

      #include <nitro/os.h>

      void OS_SetVAlarm(
      OSVAlarm*           alarm ,
      s16                 count ,
      s16              delay ,
      OSVAlarmHandler     handler ,
      void*           arg );

## Arguments

alarm | Pointer to the V count alarm structure for setting V count alarm
count | The V Count value at which the V Count alarm is actuated (the handler is called)
delay | The maximum permissible number of V Counts for delay
handler | The V count alarm handler
arg | The argument when calling the V count alarm handler

## Return Values

None.

## Description

Sets up a one-time V count alarm

`handler` is called when the V Count reaches the value specified by `count`. The V count alarm handler `handler` is an `OSVAlarmHandler` function type defined by the following:

`typedef void (*OSVAlarmHandler)( void*);`

handler is called from the OS V-count interrupt handler. Therefore, interrupts are prohibited. When the `handler` is called, it takes `arg` as an argument.

It is possible to specify the amount of permissible delay with delay when the handler cannot be called on the specified V count because of another count alarm or interrupt. For example, at count=100 and delay=5, V count is called if it is possible to call it by count 105, even if it was not possible to call it by count 100. When you specify `0`, the alarm is called only at the specified V count. If `OS_VALARM_DELAY_MAX`, it is always called when a call is possible for the specified V count and subsequent V counts. The V alarm that was not called will be postponed until the specified V count in the next frame. For details, see the description in VAlarm Overview.

If `alarm` is specified for the pointer to the `OSAlarm` structure in which the V count has been set, it stops with `OS_Panic()`.

The following example sets the V Count alarm, calls `handle` when the next V Count = 100, and displays "`handler called. arg=0x12345678`".

> Example:
> `#define COUNT 100
> #define DELAY 1100
> #define ARG 0x12345678
> OSVAlarm alarm;
> main()
> {
> :
> OS_InitVAlarm(); OS_CreateVAlarm( &alarm ); OS_SetVAlarm( &alarm , COUNT , handler , (void*)ARG );}
> void handler( void* arg )
> {
> OS_Printf( "handler called. arg=0x%x\n", arg );
> }`

Note: Prior to NITRO-SDK 2.0 RC1, this function took only four arguments and you could not specify the delay. Internally, it was treated as delay=10. But the `OS_SetOneTimeVAlarm()` function was added for your use if you prefer the old format over this new one.

## See Also

`OS_InitVAlarm, OS_CancelVAlarm, OS_SetPeriodicVAlarm, OS_SetVAlarmTag
OS_SetOneTimeVAlarm
`

## Revision History

03/08/2005 Standardized the Japanese word for "interrupt"
10/22/2004 Added delay to the arguments. 08/30/2004 Added description that the V alarm structure that has been set is not usable
02/24/2004 Initial version