2006-11-13 16:57:51 +00:00
<?xml version='1.0' encoding='iso-8859-1'?>
2006-11-22 17:22:06 +00:00
<!-- $Revision: 1.2 $ -->
2006-11-13 16:57:51 +00:00
<reference id= "ref.sam" >
<title > SAM - Simple Asynchronous Messaging</title>
<titleabbrev > SAM</titleabbrev>
<partintro >
<section id= "sam.intro" >
&reftitle.intro;
<para >
<!-- This warns that the extension is experimental -->
&warn.experimental;
<!-- This is the paragraph text -->
</para>
<para >
This extension provides access to the functionality of messaging and queueing systems, such
as the IBM WebSphere MQSeries family of products, from PHP scripts. The interface is designed
to make it extremely simple to do the more commonly required tasks such as deliver simple text
messages to queues while still allowing skilled users to do more complex messaging operations.
For many users the complexities of setting up numerous options can be simply ignored.
</para>
</section> <!-- id=sam.intro -->
<section id= 'sam.installation' >
&reftitle.install;
2006-11-22 17:22:06 +00:00
<section id= 'sam.installation.prerequisites' >
<title > Prerequisites</title>
<para >
The SAM extension interfaces to the IBM Messaging and Queuing middleware products using
a set of libraries and some client side code referred to as XMS. This package is
available as a free download in the guise of IBM support pack IA94. There is a description
of this package and download links in the article <ulink url= "&url.ibm.ia94;" > Introducing XMS - The IBM Message Service API</ulink> .
</para>
<para >
If you intend to use SAM to access the Messaging and Queuing infrastructure within
WebSphere MQ then you will also need to have installed a local MQ queue manager or
installed the WebSphere MQ clients package. The clients package is freely available
as a support pack (<ulink url= "&url.ibm.mqc6;" > MQC6</ulink> ).
</para>
<para >
If you are only aiming to experiment with sending messages to and from WebSphere Application
Server queues using the WebSphere Platform Messaging protocol (WPM) then you do not need
to install the MQC6 package.
</para>
<para >
After installing these packages you will need to ensure the XMS binary and, if you are
using it, the MQ client bin directory are included in the PATH environment variable
so that Apache and PHP can find the dependent .DLLs/libraries.
</para>
</section>
<section id= 'sam.installation.linux' >
<title > Linux installation steps</title>
<para >
The sam extension is supplied as a PECL module, which
you should be able to download and install in one step as follows:
<screen >
< ![CDATA[
pear install sam
]]>
</screen>
(Depending on your php environment, you will probably need to be root to do this.)
</para>
<para >
Make sure that the module is loaded by PHP, by adding following line to
&php.ini;
:
<screen >
< ![CDATA[
extension=sam.so
]]>
</screen>
</para>
<para >
to your php.ini file.
</para>
<para >
If you cannot use the PEAR installer, you can download the extension and build
it manually:
<screen >
< ![CDATA[
pear download sam #downloads sam-<version > .tgz
tar -xzf sam-<version > .tgz
cd sam-<version >
phpize
./configure
make
make install #you may need to be root for this step
]]>
</screen>
</para>
<para >
To work with the very latest source, you'll need to extract it from cvs and
build manually as above.
</para>
</section>
<section id= 'sam.installation.windows' >
<title > Windows installation steps</title>
<para >
Currently you will need to build the sam extension for Windows as there
are no pre-built binaries. The extension can be built using the standard
Windows extension build procedures.
</para>
<para >
You will need the PHP source tree for the version of PHP you wish to build
the SAM extension against which you can obtain from php.net. This should be
unpacked into a working directory of your choice.
</para>
<para >
You will also need the libraries and headers used by PHP extensions available
from http://www.php.net/extra/win32build.zip and this should be unzipped so
that is in your working directory.
</para>
<para >
You should have something like:
<screen >
< ![CDATA[
c:\php-build\-
|
|---php-5.0.5--|---build
| |---ext
| |--- ...
|
|---win32build--|---bin
|---include
|---lib
]]>
</screen>
</para>
<para >
You will need a compiler such as the free version of Visual Studio C++
Express from the Microsoft web site. Also you need the Microsoft Windows
Platform SDK which again can be downloaded from the Microsoft web site.
</para>
<para >
Obtain the SAM extension source using pear (pear download sam) or by using
CVS and copy the files to a new "sam" directory under the "ext" directory
in your PHP source tree.
</para>
<para >
To build the extension open a build environment window by going to the
start menu->all programs->microsoft platform SDK for windows->
open build environment window->windows 200 build environment->
set windows 2000 build environment (retail)
</para>
<para >
This should open a command prompt with all the environment variables set
up to access the platform SDK etc. You then need to set the environment
variables for Visual Studio by issuing the command "vcvars32.bat" in the
window.
</para>
<para >
Change directory to your working directory e.g. cd c:\php-build. Then
make sure the win32build tools are accessible by adding them to the PATH
environment variable:
<screen >
< ![CDATA[
set PATH=..\win32build\bin;%PATH%
]]>
</screen>
</para>
<para >
Run the buildconf.bat command. This should rebuild the configure.js file.
</para>
<para >
Run the cscript command:
<screen >
< ![CDATA[
cscript /nologo configure.js --with-sam="c:\program files\ibm\xms"
]]>
</screen>
</para>
<para >
The additional parameter passed for sam is the installation path to the
XMS libraries and runtime that were installed as described under prerequisites
at the top of this file.
</para>
<para >
You can specify whatever other cscript parameters you require to include or
exclude items from the php build or select options.
</para>
<para >
Assuming all has gone well so far you can now finally run a make!
<screen >
< ![CDATA[
nmake php_sam.dll
]]>
</screen>
</para>
</section>
<section id= 'sam.installation.VS2005' >
<title > Additional steps for Visual Studio 2005</title>
<para >
If you build the SAM extension with the Microsoft Visual Studio 2005 compiler and
tools you need to perform an additional step in the build process to ensure the
php_sam.dll is able to link with the C runtime libraries at runtime. This step
includes the dependancy manifest into the DLL. Switch to the directory where the
php_sam.dll has been generated (usually Release_TS or Debug_TS below the php
source directory) and issue the following magic incantation:
<screen >
< ![CDATA[
mt.exe -manifest php_sam.dll.manifest -outputresource:php_sam.dll;2
]]>
</screen>
</para>
<para >
If you build the SAM extension using the compiler and libaries from Microsoft Visual Studio 2005
you will also need to ensure that the runtime components are installed on the system on
which you intend to use SAM. This can be accomplished by installing Visual Studio 2005 or
by using the freely distributable <ulink url= "&url.ms.crt;" > runtime package</ulink> .
</para>
</section>
2006-11-13 16:57:51 +00:00
</section> <!-- id=sam.installation -->
<section id= 'sam.usage' >
<title > API Usage</title>
<section id= 'sam.connections' >
<title > Connections</title>
<para >
In order to perform any messaging and queueing functions a connection must be established
with a messaging server by creating a SAMConnection object and calling its "connect"
method, with a set of connection properties, to connect the PHP script to the messaging
server. Until such time as the SAMConnection object is destroyed the connection
will be maintained and available for use. All SAMConnection objects are destroyed when
the PHP script exits.
</para>
<para >
A set of default properties may be used in connecting to a messaging server but as a
minimum the PHP script must specify a protocol to be used.
</para>
<para >
<example >
2006-11-22 17:22:06 +00:00
<title > Creating a connection and connecting to a remote WebSphere MQSeries Messaging Server</title>
2006-11-13 16:57:51 +00:00
<programlisting role= 'php' >
< ![CDATA[
< ?php
$conn = new SAMConnection();
2006-11-22 17:22:06 +00:00
$conn->connect(SAM_WMQ, array(SAM_HOST => myhost.mycompany.com,
SAM_PORT => 1506,
SAM_BROKER => mybroker));
2006-11-13 16:57:51 +00:00
?>
]]>
</programlisting>
</example>
</para>
<para >
<example >
2006-11-22 17:22:06 +00:00
<title > Creating a connection and connecting to a remote WebSphere Application Server</title>
2006-11-13 16:57:51 +00:00
<programlisting role= 'php' >
< ![CDATA[
< ?php
$conn = new SAMConnection();
2006-11-22 17:22:06 +00:00
$conn->connect(SAM_WMQ, array(SAM_ENDPOINTS => 'localhost:7278:BootstrapBasicMessaging',
SAM_BUS => 'Bus1',
SAM_TARGETCHAIN => 'InboundBasicMessaging'));
2006-11-13 16:57:51 +00:00
?>
]]>
</programlisting>
</example>
</para>
</section> <!-- id=sam.connections -->
<section id= 'sam.messages' >
<title > Messages</title>
<para >
Messages sent to and received from queues are represented by the SAMMessage object. The
SAMMessage object encapsulates the body of the message (if one exists) and the header
properties associated with the message. A SAMMessage object
is either supplied as a parameter to a messaging operation or returned as a result.
</para>
<para >
<example >
<title > Creating a message with a simple text body</title>
<programlisting role= "php" >
< ![CDATA[
< ?php
$msg = new SAMMessage('This is a simple text message');
?>
]]>
</programlisting>
</example>
</para>
<para >
Messages may have header properties associated with them that provide control over the
transport of the message or further information to the receiving application. By default
message properties are delivered to the underlying messaging system as strings and in
this case they may be set with the following simple syntax:
</para>
<para >
<example >
<title > Setting a text format property using the default syntax</title>
<programlisting role= "php" >
< ![CDATA[
< ?php
$msg->header->myPropertyName = 'textData';
?>
]]>
</programlisting>
</example>
</para>
<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:
</para>
<para >
<example >
<title > Setting a property using a type hint</title>
<programlisting role= "php" >
< ![CDATA[
< ?php
2006-11-22 17:22:06 +00:00
$msg->header->myPropertyName = array(3.14159, SAM_FLOAT);
2006-11-13 16:57:51 +00:00
?>
]]>
</programlisting>
</example>
</para>
<para >
Properties may also be extracted from the header of a message.
</para>
<para >
<example >
<title > Retrieving a property from a message header</title>
<programlisting role= "php" >
< ![CDATA[
< ?php
$myProperty = $msg->header->myPropertyName;
?>
]]>
</programlisting>
</example>
</para>
</section> <!-- id=sam.messages -->
<section id= 'sam.operations' >
<title > Messaging operations</title>
<para >
All messaging operations are performed through calls to methods on the connection object.
To add a message to a queue the "send" method is used, to obtain a message from a queue the
"receive" method is used. Other methods provide publish and subscribe functionality and
control of transaction boundaries.
</para>
<para >
<example >
<title > Adding a message to a queue and receiving a response</title>
<programlisting role= "php" >
< ![CDATA[
< ?php
$msg = new SAMMessage('This is a simple text message');
$msg->header->SAM_REPLY_TO = 'queue://receive/test';
$correlid = $conn->send('queue://send/test', $msg);
if (!$correlid) {
// The Send failed!
echo "Send failed ($conn->errno) $conn->error";
} else {
2006-11-22 17:22:06 +00:00
$resp = $conn->receive('queue://receive/test', array(SAM_CORRELID => $correlid));
2006-11-13 16:57:51 +00:00
}
?>
]]>
</programlisting>
</example>
</para>
</section> <!-- id=sam.operations -->
<section id= 'sam.errors' >
<title > Error handling</title>
<para >
All SAMConnection methods that provide access to messaging operations return &false;
if an error occurred in processing the request. In addition the SAMConnection object
has two properties, "errno" and "error", that provide respectively the error number and
text description of the last error to occur on the connection.
</para>
<para >
<example >
<title > Handling an error from a method that returns no result</title>
<programlisting role= "php" >
< ![CDATA[
< ?php
if (!$conn->commit()) {
// The commit failed!
echo "Commit failed ($conn->errno) $conn->error";
}
?>
]]>
</programlisting>
</example>
</para>
<para >
<example >
<title > Handling an error from a method that returns a result</title>
<programlisting role= "php" >
< ![CDATA[
< ?php
$correlid = $conn->send('queue://send/test', $msg);
if (!$correlid) {
// The Send failed!
echo "Send failed ($conn->errno) $conn->error";
} else {
...
}
?>
]]>
</programlisting>
</example>
</para>
</section> <!-- id=sam.errors -->
</section> <!-- id=sam.usage -->
<!-- class definition section -->
<section id= 'sam.classes' >
&reftitle.classes;
<!-- Connection class *************************************************** -->
<section id= 'sam.class.Connection' >
<title > <classname > SAMConnection</classname> </title>
<para >
Object representing a connection to a Messaging Server
</para>
<section id= 'sam.class.Connection.constructor' >
&reftitle.constructor;
<itemizedlist >
<listitem >
<para >
<link linkend= 'function.SAM-Connection-constructor' > new SAMConnection</link> - construct a new connection object to allow connection to a messaging infrastructure.
</para>
</listitem>
</itemizedlist>
</section> <!-- id=sam.class.Connection.constructor -->
<section id= 'sam.class.Connection.methods' >
&reftitle.methods;
<itemizedlist >
<listitem >
<para >
<link linkend= 'function.SAM-Connection-commit' > commit</link>
- a method that commits (successfully completes) an in-flight unit of work.
</para>
</listitem>
<listitem >
<para >
<link linkend= 'function.SAM-Connection-connect' > connect</link>
- a method that connects a PHP script to a messaging server.
</para>
</listitem>
<listitem >
<para >
<link linkend= 'function.SAM-Connection-disconnect' > disconnect</link>
- a method that disconnects a PHP script from a messaging server.
</para>
</listitem>
<listitem >
<para >
<link linkend= 'function.SAM-Connection-isConnected' > isConnected</link>
- a method that checks whether a PHP script is connected to a messaging server.
</para>
</listitem>
<listitem >
<para >
<link linkend= 'function.SAM-Connection-peek' > peek</link>
- a method that receives a message from a queue without removing it from the queue.
</para>
</listitem>
2006-11-22 17:22:06 +00:00
<listitem >
<para >
<link linkend= 'function.SAM-Connection-peekAll' > peekAll</link>
- a method that receives one or messages from a queue without removing them from the queue.
</para>
</listitem>
2006-11-13 16:57:51 +00:00
<listitem >
<para >
<link linkend= 'function.SAM-Connection-receive' > receive</link>
- a method that receives a message from a queue or subscription.
</para>
</listitem>
<listitem >
<para >
<link linkend= 'function.SAM-Connection-remove' > remove</link>
- a method that removes a message from a queue.
</para>
</listitem>
<listitem >
<para >
<link linkend= 'function.SAM-Connection-rollback' > rollback</link>
- a method that cancels (rolls back) an in-flight unit of work.
</para>
</listitem>
<listitem >
<para >
<link linkend= 'function.SAM-Connection-send' > send</link>
- a method that sends a message to a queue or posts to a topic
</para>
</listitem>
<listitem >
<para >
<link linkend= 'function.SAM-Connection-subscribe' > subscribe</link>
- a method that creates a subscription to one or more topics
</para>
</listitem>
<listitem >
<para >
<link linkend= 'function.SAM-Connection-unsubscribe' > unsubscribe</link>
- a method that destroys a subscription to one or more topics
</para>
</listitem>
</itemizedlist>
</section> <!-- id=sam.class.Connection.methods -->
<section id= 'sam.class.Connection.properties' >
&reftitle.properties;
<itemizedlist >
<listitem >
<para >
<link linkend= 'function.SAM-Connection-errno' > errno</link> - the numeric error code
for the last encountered error on this connection. This property is set to 0 if the last
operation was successful.
</para>
</listitem>
<listitem >
<para >
<link linkend= 'function.SAM-Connection-error' > error</link> - the text description
for the last encountered error on this connection
</para>
</listitem>
</itemizedlist>
</section> <!-- id=sam.class.Connection.properties -->
</section> <!-- id=sam.class.Connection -->
<!-- Message class *************************************************** -->
<section id= 'sam.class.Message' >
<title > <classname > SAMMessage</classname> </title>
<para >
Object representing a message to be sent or received
</para>
<section id= 'sam.class.Message.constructor' >
&reftitle.constructor;
<itemizedlist >
<listitem >
<para >
<link linkend= 'function.SAM-Message-constructor' > new SAMMessage</link> - construct a
new message.
</para>
</listitem>
</itemizedlist>
</section> <!-- id=sam.class.Message.constructor -->
<section id= 'sam.class.Message.properties' >
&reftitle.properties;
<itemizedlist >
<listitem >
<para >
<link linkend= 'function.SAM-Message-body' > body</link> - the body of the message.
</para>
</listitem>
<listitem >
<para >
<link linkend= 'function.SAM-Message-header' > header</link> - the header properties of the message.
</para>
</listitem>
</itemizedlist>
</section> <!-- id=sam.class.Message.methods -->
</section> <!-- id=sam.class.Message -->
</section> <!-- id=sam.classes -->
<!-- Include the stuff from constants.xml? -->
&reference.sam.constants;
</partintro>
<!-- This seems to create the table of contents -->
&reference.sam.functions;
</reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
