# OS_JamMessage

## Syntax

      #include <nitro/os.h>

      BOOL OS_JamMessage(
           OSMessageQueue*   mq,
           OSMessage         msg,
           s32             flags);

## Arguments

mq | Pointer to the message queue
msg | Transmission message
flags | When `OS_MESSAGE_BLOCK` is set, `OS_JamMessage` blocks the full queue. When `OS_MESSAGE_NOBLOCK` is set, `OS_JamMessage` returns whether or not the queue is full.

## Return Values

`TRUE` is returned when the message is successfully sent. `FALSE` is returned when the queue is full and `OS_MESSAGE_NOBLOCK` is specified.

## Description

`OS_JamMessage()` is similar to `OS_SendMessage` except that it inserts a message at the beginning of the specified message queue. Call this function when sending high-priority messages.

If `OS_MESSAGE_BLOCK` is set in `flags` and the queue is full, the thread that called this function is temporarily stopped. This thread immediately restarts when a receiving thread operates to remove messages from the queue. Be aware that if there are any other sending threads with a higher priority, those will operate first and the queue may fill up again. In such a case, this thread will be suspended again until the receiving thread makes an opening in the message queue.

When `OS_MESSAGE_NOBLOCK` is set in `flags`, the calling thread is returned to immediately. When the queue is not full, `TRUE` is returned. If the queue is full, `FALSE` is returned.

## See Also

`OS_InitMessageQueue`, `OS_SendMessage`, `OS_ReceiveMessage`

## Revision History

2003/12/01 Initial version.

CONFIDENTIAL