<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 295214 $ -->

<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 PATH 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
    PATH 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
-->