# OS_SetVAlarm

## Syntax

      #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 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

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

CONFIDENTIAL