mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-18 18:08:54 +00:00
ba08db8805
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@334758 c90b9560-bf6c-de11-be94-00142212c4b1
361 lines
12 KiB
XML
361 lines
12 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
|
|
<chapter xml:id="sam.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
&reftitle.setup;
|
|
|
|
<!-- {{{ Requirements -->
|
|
<section xml:id="sam.requirements">
|
|
&reftitle.required;
|
|
<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 <link xlink:href="&url.ibm.ia94;">
|
|
Introducing XMS - The IBM Message Service API</link>.
|
|
</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 (<link xlink:href="&url.ibm.mqc6;">MQC6</link>).
|
|
</para>
|
|
<para>
|
|
If you are only aiming to experiment with sending messages to and from
|
|
WebSphere Application Server queues using the <literal>WebSphere Platform
|
|
Messaging protocol (WPM)</literal> 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 <envar>PATH</envar> environment variable so that Apache and PHP can
|
|
find the dependent .DLLs/libraries.
|
|
</para>
|
|
</section>
|
|
<!-- }}} -->
|
|
|
|
<!-- {{{ Installation -->
|
|
<section xml:id="sam.installation">
|
|
&reftitle.install;
|
|
<para>
|
|
&pecl.info;
|
|
<link xlink:href="&url.pecl.package;sam">&url.pecl.package;sam</link>.
|
|
</para>
|
|
<para>
|
|
The SAM framework and MQTT support can be built and used without any other prerequisites.
|
|
Support for protocols other than MQTT is provided via a set of libraries and some client
|
|
side code referred to as XMS.
|
|
</para>
|
|
<para>
|
|
If you only intend to use the built-in MQTT support then you can build and
|
|
configure SAM as an extension or simply refer to
|
|
<filename>php_sam.php</filename> with a <function>require</function> or
|
|
<function>require_once</function> clause in your PHP script. In this case
|
|
you need only install the code without building the extension using the pear
|
|
installer:
|
|
<screen>
|
|
<![CDATA[
|
|
pecl install -B SAM
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
|
|
<!-- {{{ Linux -->
|
|
<section xml: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[
|
|
pecl 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>
|
|
If you intend to use the XMS support to access the IBM Messaging and Queuing family
|
|
you must also enable the SAM XMS extension.
|
|
<screen>
|
|
<![CDATA[
|
|
extension=sam_xms.so
|
|
]]>
|
|
</screen>
|
|
</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
|
|
SVN and build manually as above.
|
|
</para>
|
|
</section>
|
|
<!-- }}} -->
|
|
<!-- {{{ Windows -->
|
|
<section xml:id="sam.installation.windows">
|
|
<title>Windows installation steps</title>
|
|
<para>
|
|
You will probably need to build the sam extension for Windows as there
|
|
are only a limited range of pre-built binaries available from the SAM website.
|
|
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
|
|
<literal>SDK Microsoft Windows Platform</literal> which again can be
|
|
downloaded from the Microsoft web site.
|
|
</para>
|
|
<para>
|
|
Obtain the SAM extension source using pear (pecl download sam) or by using
|
|
SVN 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 <screen>menu->all programs->microsoft platform SDK for windows->
|
|
open build environment window->windows 200 build environment->
|
|
set windows 2000 build environment (retail)</screen>
|
|
</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
|
|
<command>vcvars32.bat</command> in the window.
|
|
</para>
|
|
<para>
|
|
Change directory to your working directory e.g.
|
|
cd <filename>c:\php-build</filename>. Then
|
|
make sure the win32build tools are accessible by adding them to the
|
|
<envar>PATH</envar> environment variable:
|
|
<screen>
|
|
<![CDATA[
|
|
set PATH=..\win32build\bin;%PATH%
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
Run the <command>buildconf.bat</command> command. This should rebuild the
|
|
<filename>configure.js</filename> file.
|
|
</para>
|
|
<para>
|
|
Run the <command>cscript</command> command with the appropriate options. To build just the
|
|
SAM extension framework and MQTT support use:
|
|
<screen>
|
|
<![CDATA[
|
|
cscript /nologo configure.js --with-sam
|
|
]]>
|
|
</screen>
|
|
To build the SAM framework and the XMS support use:
|
|
<screen>
|
|
<![CDATA[
|
|
cscript /nologo configure.js --with-sam --with-sam_xms="c:\program files\ibm\xms"
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
The additional parameter passed for sam_xms is the installation path to the
|
|
XMS libraries and runtime that were installed as described under prerequisites
|
|
at the top of this page.
|
|
</para>
|
|
<para>
|
|
You can specify whatever other <command>cscript</command> 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 for the SAM framework!
|
|
<screen>
|
|
<![CDATA[
|
|
nmake php_sam.dll
|
|
]]>
|
|
</screen>
|
|
Also if you are using the XMS support you must make the sam_xms extensions:
|
|
<screen>
|
|
<![CDATA[
|
|
nmake php_sam_xms.dll
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
If you have used Visual Studio 2005 to build the DLLs please see below for additional steps that
|
|
must be carried out before proceeding further.
|
|
</para>
|
|
<para>
|
|
The DLLs created (<filename>php_sam.dll</filename> and optionally
|
|
<filename>php_sam_xms.dll</filename>) can now be copied to the subdirectory
|
|
appropriate for your PHP set-up. Make sure that the module(s) are loaded by
|
|
PHP, by adding following line to &php.ini;:
|
|
<screen>
|
|
<![CDATA[
|
|
extension=php_sam.dll
|
|
]]>
|
|
</screen>
|
|
If you intend to use the XMS support to access the IBM Messaging and Queuing family
|
|
you must also enable the SAM XMS extension.
|
|
<screen>
|
|
<![CDATA[
|
|
extension=php_sam_xms.dll
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</section>
|
|
<!-- }}} -->
|
|
<!-- {{{ VS2005 -->
|
|
<section xml: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 <filename>php_sam.dll</filename> 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
|
|
<filename>php_sam.dll</filename> 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>
|
|
If you are using the XMS capabilities you will need to do the same with the
|
|
SAM XMS DLL:
|
|
<screen>
|
|
<![CDATA[
|
|
mt.exe -manifest php_sam_xms.dll.manifest -outputresource:php_sam_xms.dll;2
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
If you build the SAM extension using the compiler and libraries 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
|
|
<link xlink:href="&url.ms.crt;">runtime package</link>.
|
|
</para>
|
|
</section>
|
|
<!-- }}} -->
|
|
</section>
|
|
<!-- }}} -->
|
|
|
|
<!-- {{{ Configuration -->
|
|
<section xml:id="sam.configuration">
|
|
&reftitle.runtime;
|
|
<section xml:id="sam.configuration.mapping">
|
|
<title>Protocol support and mapping</title>
|
|
<para>
|
|
The SAM framework can be extended to support other messaging protocols and connection mechanisms. To add
|
|
support for a new protocol or connection library a support class has to be defined, either as a C extension
|
|
or as a PHP script, and a "factory" script must be created. The support class must implement all the
|
|
methods of the SAMConnection class though it should not inherit from SAMConnection. The factory script
|
|
will be called by the SAM framework to create an instance of the implemented class. The way SAM chooses
|
|
which factory to call is based on the protocol specified as the first parameter of the "connect" call.
|
|
</para>
|
|
<para>
|
|
By default the built-in MQTT support will be used if a connect call specifies a protocol of SAM_MQTT ("mqtt"), for
|
|
any other protocol SAM will attempt to use the XMS support extension. To add support for additional
|
|
protocols or to modify the default behavior entries may be added to &php.ini; in the [sam] section. The
|
|
default mapping is equivalent to the following entries:
|
|
<screen>
|
|
<![CDATA[
|
|
[sam]
|
|
sam.factory.mqtt=mqtt
|
|
sam.factory.wmq=xms
|
|
sam.factory.wmq:client=xms
|
|
sam.factory.wmq:bindings=xms
|
|
sam.factory.wpm=xms
|
|
sam.factory.rtt=xms
|
|
]]>
|
|
</screen>
|
|
As can be seen from these examples the entries take the form of "sam.factory.pppp=xxx" where pppp is the protocol
|
|
string specified on the connect call and xxx is a factory suffix. Note: SAM defines constants for these protocol
|
|
strings such that <literal>SAM_WMQ=wmq</literal>,
|
|
<literal>SAM_WPM=wpm</literal>, <literal>SAM_RTT=rtt</literal>,
|
|
<literal>SAM_MQTT=mqtt</literal>, etc.
|
|
</para>
|
|
<para>
|
|
When identifying the support code to use on a connect call SAM looks up the protocol name in the &php.ini; entries
|
|
and then invokes a factory script named <filename>sam_factory_xxx.php</filename>. If no entry is found the support will default to XMS.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
<!-- }}} -->
|
|
|
|
<!-- {{{ Resources -->
|
|
<section xml:id="sam.resources">
|
|
&reftitle.resources;
|
|
&no.resource;
|
|
</section>
|
|
<!-- }}} -->
|
|
|
|
</chapter>
|
|
|
|
<!-- 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:"~/.phpdoc/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
|
|
-->
|
|
|