mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-19 02:18:56 +00:00
685a03b4b3
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@263467 c90b9560-bf6c-de11-be94-00142212c4b1
314 lines
11 KiB
XML
314 lines
11 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.11 $ -->
|
|
<refentry xml:id='function.samconnection-connect' xmlns="http://docbook.org/ns/docbook">
|
|
<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>mqtt</entry>
|
|
<entry>SAM_MQTT</entry>
|
|
<entry>Use the MQTT (MQ Telemetry Transport) protocol connecting as a client to a server.</entry>
|
|
</row>
|
|
<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>
|
|
The name of the broker or queue manager running on the messaging server.
|
|
<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,
|
|
1506 for SAM_WPM,
|
|
or 1883 for SAM_MQTT
|
|
</entry>
|
|
<entry>
|
|
The port number on which to attempt communication with the messaging server.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>SAM_EXPIRE_AFTER</entry>
|
|
<entry>0</entry>
|
|
<entry>
|
|
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>
|
|
Warning: Not yet implemented!
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>SAM_MESSAGE_PERSISTENCE</entry>
|
|
<entry>none</entry>
|
|
<entry>
|
|
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>
|
|
Warning: Not yet implemented!
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>SAM_MQTT_CLEANSTART</entry>
|
|
<entry>&false;</entry>
|
|
<entry>
|
|
Optional connect option to indicate to an MQTT server that all previous connection data
|
|
for this client should be removed and that subscriptions should be deleted when the client
|
|
disconnects explicitly or unexpectedly. Setting the value to &true; causes SAM to discard
|
|
any subscription already in place for the client when it connects and also to discard
|
|
subscription when the client disconnects. Setting the option to &false;, or using the
|
|
default, allows subscriptions to be durable and survive across client disconnects.
|
|
</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
|
|
-->
|