1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
|
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 297028 $ -->
<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:"~/.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
-->
|
