mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-27 14:28:56 +00:00
66b884c24c
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@225233 c90b9560-bf6c-de11-be94-00142212c4b1
200 lines
6.9 KiB
XML
200 lines
6.9 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.4 $ -->
|
|
<refentry id='function.SAM-Connection-send'>
|
|
<refnamediv>
|
|
<refname>SAMConnection::send()</refname>
|
|
<refpurpose>
|
|
Send a message to a queue or publish an item to a topic.
|
|
</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<para>
|
|
The "send" method is used to send a message to a specific queue or to publish to a specific topic. The method returns a correlation id that can be used as a selector to identify reply or response messages when these are requested.
|
|
</para>
|
|
<classsynopsis>
|
|
<ooclass><classname>SAMConnection</classname></ooclass>
|
|
<methodsynopsis>
|
|
<type>string</type><methodname>send</methodname>
|
|
<methodparam><type>string</type><parameter>target</parameter></methodparam>
|
|
<methodparam><type>SAMMessage</type><parameter>msg</parameter></methodparam>
|
|
<methodparam choice='opt'><type>array</type><parameter>properties</parameter></methodparam>
|
|
</methodsynopsis>
|
|
</classsynopsis>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>target</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
If sending a message, the identity of the queue (queue://queuename) or if publishing to a topic the identity of the topic (topic://topicname) to which the message is to be delivered.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>msg</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The message to be sent or published.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>properties</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
An optional associative array of properties describing other parameters to control the receive operation.
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Property name</entry>
|
|
<entry>Possible values</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>SAM_DELIVERYMODE</entry>
|
|
<entry>
|
|
Indicates whether the messaging server should enusre delivery or whether it is acceptable for messages
|
|
to be lost in the case of system failures. The value of this property may be set to either SAM_PERSISTENT, to
|
|
indicate that message loss is not acceptable, or SAM_NON_PERSISTENT, if message loss is acceptable.
|
|
The resulting behaviour of the send will vary depending on the capabilities of the messaging server the
|
|
PHP script is currently connected to. If the server does not support persistent messages and SAM_PERSISTENT
|
|
is specified the send request will fail with an error indication showing the capability is not available.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>SAM_PRIORITY</entry>
|
|
<entry>
|
|
A numeric value between 0 and 9 indicating the desired message delivery priority. A priority value of 0
|
|
indicates the lowest priority while 9 indicates highest priority. If no priority is specified
|
|
a default will be assigned which is dependent on the messaging server being used.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>SAM_CORRELID</entry>
|
|
<entry>
|
|
A string to be assigned as a correlation id for this message. If no value is given the messaging server
|
|
may assign a value automatically.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>SAM_TIMETOLIVE</entry>
|
|
<entry>
|
|
A time in milliseconds indicating how long the messaging server should retain the message on a queue before
|
|
discarding it. The default value is 0 indicating the message should be retained indefinitely.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>SAM_WMQ_TARGET_CLIENT</entry>
|
|
<entry>
|
|
This property is only valid when using WebSphere MQ and indicates whether or not an RFH2 header should be
|
|
included with the message. This option may be set to either 'jms' or 'mq'. The default is 'jms' which means
|
|
that an RFH2 header is included. If the value 'mq' is specified then no RFH2 is included with the message.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
A correlation id string that can be used in a subsequent receive call as a selector to obtain any reply or response that has been requested or &false; if an error occurred.
|
|
Note: a correlation id will only be returned for a successful send to a queue destination (queue://xxxx) in which case it
|
|
will reflect the message identitiy of the message on the queue. In the case of a send being used to publish data to a
|
|
topic the return value will be &true; as no correlation id is availabe for return.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<para>
|
|
<example>
|
|
<title>Send a message to a queue</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$msg = new SAMMessage('This is a simple text message');
|
|
$correlId = $conn->send('queue://send/test', $msg);
|
|
if (!$correlId) {
|
|
// The send failed!
|
|
echo "Send failed ($conn->errno) $conn->error";
|
|
}
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Publish a message to a topic</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$msg = new SAMMessage('This is a simple text item');
|
|
if (!$conn->send('topic://test', $msg)) {
|
|
// The Send failed!
|
|
echo "Send failed ($conn->errno) $conn->error";
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Send a request and receive a response</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$msg = new SAMMessage('This is a simple text message');
|
|
$msg->header->SAM_REPLY_TO = 'queue://receive/test';
|
|
$correlid = $conn->send('queue://send/test', $msg);
|
|
|
|
if (!$correlid) {
|
|
// The Send failed!
|
|
echo "Send failed ($conn->errno) $conn->error";
|
|
} else {
|
|
$resp = $conn->receive('queue://receive/test', array(SAM_CORRELID => $correlid));
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</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
|
|
-->
|