php-doc-en/reference/sam/functions/SAM-Connection-connect.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.5 $ -->
<refentry id='function.samconnection-connect'>
 <refnamediv>
  <refname>SAMConnection->connect()</refname>
  <refpurpose>
   Establishes a connection to a Messaging Server
  </refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <classsynopsis>
   <ooclass><classname>SAMConnection</classname></ooclass>
   <methodsynopsis>
    <type>bool</type><methodname>connect</methodname>
    <methodparam><type>string</type><parameter>protocol</parameter></methodparam>
    <methodparam choice='opt'><type>array</type><parameter>properties</parameter></methodparam>
   </methodsynopsis>
  </classsynopsis>
  <para>
   Calling the "connect" method on a SAMConnection object connects the PHP
   script to a messaging server. No messages can be sent or received until a
   connection is made.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>protocol</parameter></term>
     <listitem>
      <para>
       A structured string identifying the protocol to be used when
       attempting to connect to the messaging server. The supported protocols
       are represented by constants which are normally used but if required
       the string may be composed dynamically by the script.
       The string is made up of 2 parts, the first being the protocol
       identifier and the second a protocol option. The two parts are
       seperated by a colon (:) character. Acceptable values are described by
       the following table:
       <informaltable>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>Protocol string</entry>
           <entry>Constant</entry>
           <entry>Usage</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry>wmq</entry>
           <entry>SAM_WMQ</entry>
           <entry>
            Use the IBM MQSeries protocol connecting as a client to a remote
            messaging server. This is equivalent to "wmq:client" 
            (SAM_WMQ_CLIENT). At least a broker name (SAM_BROKER) must be
            specified in the options array.
           </entry>
          </row>
          <row>
           <entry>wmq:client</entry>
           <entry>SAM_WMQ_CLIENT</entry>
           <entry>
            Use the IBM MQSeries protocol connecting as a client to a remote
            messaging server. At least a broker name (SAM_BROKER) must be
            specified in the options array.
           </entry>
          </row>
          <row>
           <entry>wmq:bindings</entry>
           <entry>SAM_WMQ_BINDINGS</entry>
           <entry>
            Use the IBM MQSeries protocol connecting to a local messaging
            server and communicating via shared memory. At least a broker
            name (SAM_BROKER) must be specified in the options array.
           </entry>
          </row>
          <row>
           <entry>wpm</entry>
           <entry>SAM_WPM</entry>
           <entry>
            Use the IBM WebSphere Platform Messaging protocol to connect to
            the messaging infrastructure of a WebSphere Application server or
            cluster. A bus name must be specified in the options array
            (SAM_BUS) and endpoint and target chain may also be specified.
           </entry>
          </row>
          <row>
           <entry>rtt</entry>
           <entry>SAM_RTT</entry>
           <entry>
            Use the IBM Realtime transport protocol to connect to the
            messaging infrastructure.
           </entry>
          </row>
         </tbody>
        </tgroup>
       </informaltable>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>properties</parameter></term>
     <listitem>
      <para>
       An optional associative array of properties to describe the details of
       the connection required. The following table lists the available
       property names and accepted values:
       <informaltable>
        <tgroup cols="3">
         <thead>
          <row>
           <entry>Property name</entry>
           <entry>default</entry>
           <entry>Usage</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry>SAM_BROKER</entry>
           <entry>none</entry>
           <entry>
            <para>
             The name of the broker or queue manager running on the messaging
             server.
            </para>
            <para>
             This property must be set if using one of the variants of the
             WebSphere MQSeries protocol (SAM_WMQ, SAM_WMQ_CLIENT,
             SAM_WMQ_BINDINGS).
            </para>
           </entry>
          </row>
          <row>
           <entry>SAM_HOST</entry>
           <entry>localhost</entry>
           <entry>
            The hostname of the machine on which the messaging server is
            running.
           </entry>
          </row>
          <row>
           <entry>SAM_PORT</entry>
           <entry>1414 for SAM_WMQ
            or 1506 for SAM_WPM
           </entry>
           <entry>
            The port number on which to attempt communication with the
            messaging server.
           </entry>
          </row>
          <row>
           <entry>SAM_CLIENT_ID</entry>
           <entry>none</entry>
           <entry>
            <para>
             A string used to uniquely identify the client when accessing
             subscriptions.
            </para>
            <para>
             Warning: Not yet implemented!
            </para>
           </entry>
          </row>
          <row>
           <entry>SAM_EXPIRE_AFTER</entry>
           <entry>0</entry>
           <entry>
            <para>
             Time in milliseconds after which a message is deemed to have
             expired and can be deleted from queues. The default value is 0
             indicating the message never expires.
            </para>
            <para>
             Warning: Not yet implemented!
            </para>
           </entry>
          </row>
          <row>
           <entry>SAM_MESSAGE_PERSISTENCE</entry>
           <entry>none</entry>
           <entry>
            <para>
             Selects whether messages are made persistent during delivery. 
             The value may be SAM_PERSISTENT or SAM_NON_PERSISTENT. The
             default is dependant on the connection type and capabilities
             of the Messaging Server to which the connection is made.
            </para>
            <para>
             Warning: Not yet implemented!
            </para>
           </entry>
          </row>
          <row>
           <entry>SAM_PASSWORD</entry>
           <entry>none</entry>
           <entry>
            The password to be used when the Messaging Server to which the
            connection is being made requires authentication.
           </entry>
          </row>
          <row>
           <entry>SAM_TRANSACTIONS</entry>
           <entry>SAM_AUTO</entry>
           <entry>
            Indicates how transactions are handled on this connection. The
            value may be SAM_AUTO (the default) to allow automatic handling
            on a per operation basis or SAM_MANUAL to allow the PHP script
            to control the transaction boundaries. If SAM_MANUAL is used any
            in-flight transactions will be rolled back if the script is
            terminated or the connection is closed without a commit being
            executed.
           </entry>
          </row>
          <row>
           <entry>SAM_USERID</entry>
           <entry>none</entry>
           <entry>
            The user id to be used when the Messaging Server to which the
            connection is being made requires authentication.
           </entry>
          </row>
          <row>
           <entry>SAM_WPM_DUR_SUB_HOME</entry>
           <entry>none</entry>
           <entry>
            The name of the messaging engine where durable subscriptions
            are managed. (WPM ONLY).
           </entry>
          </row>
         </tbody>
        </tgroup>
       </informaltable>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   This method returns &false; if an error occurs.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>
     Creating a connection to a Messaging Server using the IBM MQSeries
     protocol (WMQ)
    </title>
    <programlisting role="php">
<![CDATA[
<?php

$conn->connect(SAM_WMQ, array(SAM_HOST => 'Myhost.myco.com', SAM_PORT => 1506, SAM_BROKER => 'MyBroker'));

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>
     Creating a connection with application transaction control and default
     host and port values
    </title>
    <programlisting role="php">
<![CDATA[
<?php

$conn->connect(SAM_WMQ, array(SAM_BROKER => 'MyBroker', SAM_TRANSACTIONS => SAM_MANUAL));

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>
     Creating a connection to a Messaging Server using the IBM WebSphere
     Platform Messaging protocol (WPM)
    </title>
    <programlisting role="php">
<![CDATA[
<?php

$conn->connect(SAM_WPM, array(SAM_ENDPOINTS => 'localhost:7278:BootstrapBasicMessaging',
                              SAM_BUS => 'Bus1', SAM_TARGETCHAIN => 'InboundBasicMessaging'));

?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><xref linkend="function.samconnection-isconnected" /></member>
    <member><xref linkend="function.samconnection-disconnect" /></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>

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