dsr Wed Nov 22 17:22:06 2006 UTC
Modified files:
/phpdoc/en/reference/sam constants.xml reference.xml
Log:
Updates for release 0.2.0
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sam/constants.xml?r1=1.1&r2=1.2&diff_format=u
Index: phpdoc/en/reference/sam/constants.xml
diff -u phpdoc/en/reference/sam/constants.xml:1.1
phpdoc/en/reference/sam/constants.xml:1.2
--- phpdoc/en/reference/sam/constants.xml:1.1 Mon Nov 13 16:57:27 2006
+++ phpdoc/en/reference/sam/constants.xml Wed Nov 22 17:22:06 2006
@@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
<section id="mq.constants">
&reftitle.constants;
&extension.constants;
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sam/reference.xml?r1=1.1&r2=1.2&diff_format=u
Index: phpdoc/en/reference/sam/reference.xml
diff -u phpdoc/en/reference/sam/reference.xml:1.1
phpdoc/en/reference/sam/reference.xml:1.2
--- phpdoc/en/reference/sam/reference.xml:1.1 Mon Nov 13 16:57:27 2006
+++ phpdoc/en/reference/sam/reference.xml Wed Nov 22 17:22:06 2006
@@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
<reference id="ref.sam">
<title>SAM - Simple Asynchronous Messaging</title>
<titleabbrev>SAM</titleabbrev>
@@ -23,9 +23,192 @@
<section id='sam.installation'>
&reftitle.install;
- <para>
- This should be the installation section.
- </para>
+ <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>
</section> <!-- id=sam.installation -->
<section id='sam.usage'>
@@ -47,12 +230,14 @@
</para>
<para>
<example>
- <title>Creating a connection and connecting to a local Messaging Server
using all defaults</title>
+ <title>Creating a connection and connecting to a remote WebSphere
MQSeries Messaging Server</title>
<programlisting role='php'>
<![CDATA[
<?php
$conn = new SAMConnection();
- $conn->connect(SAM_WMQ);
+ $conn->connect(SAM_WMQ, array(SAM_HOST => myhost.mycompany.com,
+ SAM_PORT => 1506,
+ SAM_BROKER => mybroker));
?>
]]>
</programlisting>
@@ -60,14 +245,14 @@
</para>
<para>
<example>
- <title>Creating a connection and connecting to a remote Messaging
Server</title>
+ <title>Creating a connection and connecting to a remote WebSphere
Application Server</title>
<programlisting role='php'>
<![CDATA[
<?php
$conn = new SAMConnection();
- $conn->connect(SAM_WMQ, array(SAM_HOST => myhost.mycompany.com,
- SAM_PORT => 1506,
- SAM_BROKER => mybroker));
+ $conn->connect(SAM_WMQ, array(SAM_ENDPOINTS =>
'localhost:7278:BootstrapBasicMessaging',
+ SAM_BUS => 'Bus1',
+ SAM_TARGETCHAIN => 'InboundBasicMessaging'));
?>
]]>
</programlisting>
@@ -123,7 +308,7 @@
<programlisting role="php">
<![CDATA[
<?php
- $msg->header->myPropertyName = (3.14159, SAM_FLOAT);
+ $msg->header->myPropertyName = array(3.14159, SAM_FLOAT);
?>
]]>
</programlisting>
@@ -168,7 +353,7 @@
// The Send failed!
echo "Send failed ($conn->errno) $conn->error";
} else {
- $resp = $conn->receive('queue://receive/test', array(SAM_SELECT =>
$correlid));
+ $resp = $conn->receive('queue://receive/test', array(SAM_CORRELID =>
$correlid));
}
?>
]]>
@@ -279,6 +464,12 @@
</listitem>
<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>
+ <listitem>
+ <para>
<link linkend='function.SAM-Connection-receive'>receive</link>
- a method that receives a message from a queue or subscription.
</para>
