# OS_SetVAlarm

## C Specification

      #include <nitro/os.h>

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

## Description

Sets up a one-time V-count alarm

`handler` is called when the V-Count reaches the value specified by `count`. However, You can specify how long the function can wait to permit when you cannot call the exact specified V-count with other count alarms or interrupts by using the `delay` argument. For example, at `count=100` and `delay=5`, V-Count is called if it is possible to call it by `105`, even if it was not possible to call it by `100`. When you specify `0`, it is only called by 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. VAlarms that weren't called are not called until the specified V-count of the next frame. For details, see the explanation of VAlarm in the Overview.

`handler` is an `OSVAlarmHandler` function type defined by the following:

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

When `handler` is called, it takes `arg` as an argument.

If `alarm` is specified for the pointer to the `OSAlarm` structure which the V count alarm 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.

## Arguments

`alarm` | Pointer to the V-Count alarm structure that sets up a 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 the V-Count alarm is called

## Return Values

None

## See Also

`OS_InitVAlarm`, `OS_CancelVAlarm`, `OS_SetPeriodicVAlarm`, `OS_SetVAlarmTag` , `OS_SetOneTimeVAlarm`

## Revision History

10/22/2004 Added `delay` to the Arguments list and made a note referring to `OS_InitVAlarm()` for details
08/30/2004 Added description that the V alarm structure that has been set is not usable
02/24/2004 Initial version