1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<HTML>
3<HEAD>
4<META http-equiv="Content-Type" content="text/html; charset=windows-1252">
5<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder Version 7.0.0.0 for Windows">
6<META http-equiv="Content-Style-Type" content="text/css">
7<TITLE>OS_JamMessage</TITLE>
8<LINK rel="stylesheet" href="../../css/nitro.css" type="text/css">
9</HEAD>
10<BODY>
11<H1 align="left">OS_JamMessage <IMG src="../../image/NTR.gif" align="middle"><IMG src="../../image/TWL.gif" align="middle"></H1>
12<H2>Syntax</H2>
13<DL>
14  <DD>
15  <PRE><CODE>#include &lt;nitro/os.h&gt;</CODE></PRE>
16  <PRE><CODE>BOOL OS_JamMessage(
17     OSMessageQueue*   mq,
18     OSMessage         msg,
19     s32             flags);
20  </CODE></PRE>
21
22</DL>
23<H2>Arguments</H2>
24<TABLE border="1" width="100%">
25  <TBODY>
26    <TR>
27      <TD width="13%"><EM><STRONG>mq</STRONG></EM></TD>
28      <TD width="87%">Pointer to the message queue</TD>
29    </TR>
30    <TR>
31      <TD width="13%"><EM><STRONG>msg</STRONG></EM></TD>
32      <TD width="87%">Transmission message</TD>
33    </TR>
34    <TR>
35      <TD><EM><STRONG>flags</STRONG></EM></TD>
36      <TD>When <code>OS_MESSAGE_BLOCK</code> is set, <code>OS_JamMessage</code> blocks the full queue. When <code>OS_MESSAGE_NOBLOCK</code> is set, <code>OS_JamMessage</code> returns whether or not the queue is full.</TD>
37    </TR>
38  </TBODY>
39</TABLE>
40
41<H2>Return Values</H2>
42<P>
43<code>TRUE</code> is returned when the message is successfully sent. <code>FALSE</code> is returned when the queue is full and <code>OS_MESSAGE_NOBLOCK</code> is specified.
44</P>
45
46<H2>Description</H2>
47<P><code>OS_JamMessage()</code> is similar to <code>OS_SendMessage</code> except that it inserts a message at the beginning of the specified message queue. Call this function when sending high-priority messages.</P>
48
49<P>If <code>OS_MESSAGE_BLOCK</code> is set in <em><strong><code>flags</code></strong></em> 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.</P>
50
51<P>When <code>OS_MESSAGE_NOBLOCK</code> is set in <em><strong><code>flags</code></strong></em>, the calling thread is returned to immediately. When the queue is not full, <code>TRUE</code> is returned. If the queue is full, <CODE>FALSE</CODE> is returned.</P>
52<H2>See Also</H2>
53<P><code><a href="OS_InitMessageQueue.html">OS_InitMessageQueue</a></code>, <code><a href="OS_SendMessage.html">OS_SendMessage</a></code>, <code><a href="OS_ReceiveMessage.html">OS_ReceiveMessage</a></code></P>
54<H2>Revision History</H2>
55<P>2003/12/01 Initial version.</P>
56<hr><p>CONFIDENTIAL</p></body>
57</HTML>