mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 16:38:54 +00:00

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@343888 c90b9560-bf6c-de11-be94-00142212c4b1
234 lines
7.2 KiB
XML
234 lines
7.2 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<refentry xml:id='samconnection.send' xmlns="http://docbook.org/ns/docbook">
|
|
<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;
|
|
<methodsynopsis>
|
|
<type>string</type><methodname>SAMConnection::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>
|
|
<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>
|
|
</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 (<literal>queue://queuename</literal>)
|
|
or if publishing to a topic the identity of the topic
|
|
(<literal>topic://topicname</literal>) 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 ensure 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
|
|
<constant>SAM_PERSISTENT</constant>, to indicate that message
|
|
loss is not acceptable, or
|
|
<constant>SAM_NON_PERSISTENT</constant>, 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 <constant>SAM_PERSISTENT</constant> 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.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
A correlation id will only be returned for a successful send to a queue
|
|
destination (<literal>queue://xxxx</literal>) in which case it will reflect the message
|
|
identity 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 available for return.
|
|
</para>
|
|
</note>
|
|
</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>
|
|
|
|
<refsect1 role="seealso">
|
|
&reftitle.seealso;
|
|
<para>
|
|
<simplelist>
|
|
<member><xref linkend="samconnection.receive" /></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
|
|
-->
|