<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>The header properties of the message.</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="sammessage.construct.html">SAMMessage::__construct</a></div>
<div class="next" style="text-align: right; float: right;"><a href="book.snmp.html">SNMP</a></div>
<div class="up"><a href="ref.sam.html">SAM Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="sammessage.header" class="refentry">
<div class="refnamediv">
<h1 class="refname">SAMMessage::header</h1>
<p class="verinfo">(PECL sam >= 0.1.0)</p><p class="refpurpose"><span class="refname">SAMMessage::header</span> — <span class="dc-title">
The header properties of the message.
</span></p>
</div>
<div class="refsect1 description" id="refsect1-sammessage.header-description">
<h3 class="title">Description</h3>
<div class="fieldsynopsis"><span class="type">object</span> <var class="varname">$SAMMessage->header</var>;</div>
<p class="para">
The <em>header</em> property is a container for any system or
user properties that area associated with the message.
</p>
<p class="para">
Properties may be assigned by the sender of a message to control the way
the messaging systems handles it or may be assigned by the messaging
system itself to tell the recipient extra information about the message or
the way in which it has been handled.
</p>
<p class="para">
Some properties are understood by SAM in which case constants have been
defined for them. The majority of properties however are ignored by the
SAM implementation and simply passed through to the underlying messaging
systems allowing the application to use messaging specific property names
or to define its own "user" properties.
</p>
<p class="para">
The SAM defined properties are as follows:
<table class="doctable informaltable">
<thead>
<tr>
<th>Property name</th>
<th>Possible values</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td><strong><code>SAM_MESSAGEID</code></strong></td>
<td>
When a message is received this field contains the unique
identifier of the message as allocated by the underlying
messaging system. When sending a message this field is ignored.
</td>
</tr>
<tr>
<td><strong><code>SAM_REPLY_TO</code></strong></td>
<td>
A string providing the identity of the queue on to which
responses to this message should be posted.
</td>
</tr>
<tr>
<td><strong><code>SAM_TYPE</code></strong></td>
<td>
<p class="para">
An indication of the type of message to be sent. The value may be
<strong><code>SAM_TEXT</code></strong> indicating the contents of the
message body is a text string, or <strong><code>SAM_BYTES</code></strong>
indicating the contents of the message body are some application
defined format.
</p>
<p class="para">
The way in which this property is used may depend on the underlying
messaging server. For instance a messaging server that supports the
<em>JMS (Java Message Service)</em> specification may
interpret this value and send messages of type "<em>jms_text</em>"
and "<em>jms_bytes</em>". In addition, if the
<strong><code>SAM_TYPE</code></strong> property is set to <strong><code>SAM_TEXT</code></strong>
the data provided for the message body is expected to be a UTF8 encoded
string.
</p>
</td>
</tr>
</tbody>
</table>
</p>
<p class="para">
When setting the values of properties it is often useful to give a hint as
to the format in which the property should be delivered to the messaging
system. By default property values are delivered as text and the
following simple syntax may be used to set a value:
</p>
<p class="para">
<div class="example" id="example-4543">
<p><strong>Example #1 Setting a text format property using the default syntax</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$msg </span><span style="color: #007700">= new </span><span style="color: #0000BB">SAMMessage</span><span style="color: #007700">();<br /><br /></span><span style="color: #0000BB">$msg</span><span style="color: #007700">-></span><span style="color: #0000BB">header</span><span style="color: #007700">-></span><span style="color: #0000BB">myPropertyName </span><span style="color: #007700">= </span><span style="color: #DD0000">'textData'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="para">
If it is desired to pass type information an alternative syntax may be
used where the value and the type hint are passed in an associative
array:
</p>
<p class="para">
<div class="example" id="example-4544">
<p><strong>Example #2 Setting a text format property using a type hint</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$msg </span><span style="color: #007700">= new </span><span style="color: #0000BB">SAMMessage</span><span style="color: #007700">();<br /><br /></span><span style="color: #0000BB">$msg</span><span style="color: #007700">-></span><span style="color: #0000BB">header</span><span style="color: #007700">-></span><span style="color: #0000BB">myPropertyName </span><span style="color: #007700">= array(</span><span style="color: #DD0000">'textData'</span><span style="color: #007700">, </span><span style="color: #0000BB">SAM_STRING</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="para">
When passing a type hint the type entry should be one of the SAM defined
constant values as defined by the following table:
<table class="doctable informaltable">
<thead>
<tr>
<th>Constant</th>
<th>Type description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td><strong><code>SAM_BOOLEAN</code></strong></td>
<td>
Any value passed will be interpreted as logical true or false.
If the value cannot be interpreted as a PHP boolean value the value
passed to the messaging system is undefined.
</td>
</tr>
<tr>
<td><strong><code>SAM_BYTE</code></strong></td>
<td>
An 8-bit signed integer value. SAM will attempt to convert the
property value specified into a single byte value to pass to the
messaging system. If a string value is passed an attempt will be
made to interpret the string as a numeric value. If the numeric
value cannot be expressed as an 8-bit signed binary value data may
be lost in the conversion.
</td>
</tr>
<tr>
<td><strong><code>SAM_DOUBLE</code></strong></td>
<td>
A long floating point value. SAM will attempt to convert the
property value specified into a floating point value with 15 digits
of precision. If a string value is passed an attempt will be made to
interpret the string as a numeric value. If the passed value cannot
be expressed as a 15 digit floating point value data may be lost in
the conversion.
</td>
</tr>
<tr>
<td><strong><code>SAM_FLOAT</code></strong></td>
<td>
A short floating point value. SAM will attempt to convert the
property value specified into a floating point value with 7 digits of
precision. If a string value is passed an attempt will be made to
interpret the string as a numeric value. If the passed value cannot
be expressed as a 7 digit floating point value data may be lost in
the conversion.
</td>
</tr>
<tr>
<td><strong><code>SAM_INT</code></strong></td>
<td>
An 32-bit signed integer value. SAM will attempt to convert the
property value specified into a 32-bit value to pass to the messaging
system. If a string value is passed an attempt will be made to
interpret the string as a numeric value. If the numeric value cannot
be expressed as an 32-bit signed binary value data may be lost in the
conversion.
</td>
</tr>
<tr>
<td><strong><code>SAM_LONG</code></strong></td>
<td>
An 64-bit signed integer value. SAM will attempt to convert the
property value specified into a 64-bit value to pass to the messaging
system. If a string value is passed an attempt will be made to
interpret the string as a numeric value. If the numeric value cannot
be expressed as an 64-bit signed binary value data may be lost in the
conversion.
</td>
</tr>
<tr>
<td><strong><code>SAM_STRING</code></strong></td>
<td>
SAM will interpret the property value specified as a string and pass
it to the messaging system accordingly.
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 examples" id="refsect1-sammessage.header-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-4545">
<p><strong>Example #3 Setting properties as the sender of a message</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$msg </span><span style="color: #007700">= new </span><span style="color: #0000BB">SAMMessage</span><span style="color: #007700">(</span><span style="color: #DD0000">'This is a test message'</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">// defining SAM specific properties...<br /></span><span style="color: #0000BB">$msg</span><span style="color: #007700">-></span><span style="color: #0000BB">header</span><span style="color: #007700">-></span><span style="color: #0000BB">SAM_REPLY_TO </span><span style="color: #007700">= </span><span style="color: #DD0000">'queue://test/replyQueue'</span><span style="color: #007700">;<br /><br /></span><span style="color: #FF8000">// defining arbitrary properties...<br />//<br />// a default string property<br /></span><span style="color: #0000BB">$msg</span><span style="color: #007700">-></span><span style="color: #0000BB">header</span><span style="color: #007700">-></span><span style="color: #0000BB">myStringProp1 </span><span style="color: #007700">= </span><span style="color: #DD0000">'a string property'</span><span style="color: #007700">;<br /></span><span style="color: #FF8000">// a string property with a type hint<br /></span><span style="color: #0000BB">$msg</span><span style="color: #007700">-></span><span style="color: #0000BB">header</span><span style="color: #007700">-></span><span style="color: #0000BB">myStringProp2 </span><span style="color: #007700">= array(</span><span style="color: #DD0000">'another string property'</span><span style="color: #007700">, </span><span style="color: #0000BB">SAM_STRING</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">// a boolean property<br /></span><span style="color: #0000BB">$msg</span><span style="color: #007700">-></span><span style="color: #0000BB">header</span><span style="color: #007700">-></span><span style="color: #0000BB">myBoolProp </span><span style="color: #007700">= array(</span><span style="color: #0000BB">FALSE</span><span style="color: #007700">, </span><span style="color: #0000BB">SAM_BOOL</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">// numeric format properties<br /></span><span style="color: #0000BB">$msg</span><span style="color: #007700">-></span><span style="color: #0000BB">header</span><span style="color: #007700">-></span><span style="color: #0000BB">myIntProp </span><span style="color: #007700">= array(</span><span style="color: #0000BB">32768</span><span style="color: #007700">, </span><span style="color: #0000BB">SAM_INT</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$msg</span><span style="color: #007700">-></span><span style="color: #0000BB">header</span><span style="color: #007700">-></span><span style="color: #0000BB">myLongProp </span><span style="color: #007700">= array(</span><span style="color: #0000BB">9876543</span><span style="color: #007700">, </span><span style="color: #0000BB">SAM_LONG</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$msg</span><span style="color: #007700">-></span><span style="color: #0000BB">header</span><span style="color: #007700">-></span><span style="color: #0000BB">myByteProp1 </span><span style="color: #007700">= array(</span><span style="color: #0000BB">123</span><span style="color: #007700">, </span><span style="color: #0000BB">SAM_BYTE</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$msg</span><span style="color: #007700">-></span><span style="color: #0000BB">header</span><span style="color: #007700">-></span><span style="color: #0000BB">myByteProp2 </span><span style="color: #007700">= array(</span><span style="color: #DD0000">'12'</span><span style="color: #007700">, </span><span style="color: #0000BB">SAM_BYTE</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$msg</span><span style="color: #007700">-></span><span style="color: #0000BB">header</span><span style="color: #007700">-></span><span style="color: #0000BB">myFloatProp </span><span style="color: #007700">= array(</span><span style="color: #0000BB">3.141592</span><span style="color: #007700">, </span><span style="color: #0000BB">SAM_FLOAT</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$msg</span><span style="color: #007700">-></span><span style="color: #0000BB">header</span><span style="color: #007700">-></span><span style="color: #0000BB">myDoubleProp </span><span style="color: #007700">= array(</span><span style="color: #0000BB">3.14159265358979</span><span style="color: #007700">, </span><span style="color: #0000BB">SAM_DOUBLE</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="example-4546">
<p><strong>Example #4 Retreiving property values from a message</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br /></span><span style="color: #FF8000">// accessing an application specific property<br /></span><span style="color: #0000BB">$intProp </span><span style="color: #007700">= </span><span style="color: #0000BB">$msg</span><span style="color: #007700">-></span><span style="color: #0000BB">header</span><span style="color: #007700">-></span><span style="color: #0000BB">MyIntProp</span><span style="color: #007700">;<br /><br /></span><span style="color: #FF8000">// accessing a messaging system specific property<br /></span><span style="color: #0000BB">$encoding </span><span style="color: #007700">= </span><span style="color: #0000BB">$msg</span><span style="color: #007700">-></span><span style="color: #0000BB">header</span><span style="color: #007700">-></span><span style="color: #0000BB">JMS_IBM_Msgtype</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
</div>
<div class="refsect1 seealso" id="refsect1-sammessage.header-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"><a href="sammessage.body.html" class="xref">SAMMessage::body</a></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="sammessage.construct.html">SAMMessage::__construct</a></div>
<div class="next" style="text-align: right; float: right;"><a href="book.snmp.html">SNMP</a></div>
<div class="up"><a href="ref.sam.html">SAM Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
