doc-fr/reference/sam/functions/SAM-Connection-send.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.8 $ -->
<!-- EN-Revision: 1.8 Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->

<refentry xml:id='function.samconnection-send' xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>SAMConnection->send</refname>
  <refpurpose>Envoie un message à une file d'attente ou le publie sur un sujet</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <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>
  <para>
   La méthode "send" est utilisée pour envoyer un message à une file d'attente spécifique ou le publier
   à un sujet spécifique. La méthode retourne l'identifiant de corrélation qui peut être utilisé comme sélecteur
   pour identifier les messages réponses.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>target</parameter></term>
     <listitem>
      <para>
       Si l'on envoie un message, ce sera l'identité de la file d'attente
       (queue://queuename) ou, si on le publie à un sujet spécifique,
       l'identité du sujet (topic://topicname) auquel le message doit être délivré.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>msg</parameter></term>
     <listitem>
      <para>
       Le message à envoyer ou à publier.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>properties</parameter></term>
     <listitem>
      <para>
       Un tableau associatif optionnel de propriétés décrivant les autres paramètres pour contrôler l'opération.
       <informaltable>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>Nom de la propriété</entry>
           <entry>Valeurs de la propriété</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry>SAM_DELIVERYMODE</entry>
           <entry>
            Indique si le serveur de messagerie doit s'assurer de la délivrance du message ou s'il accepte
            que les messages soient perdus en cas de défaillance du serveur de messagerie. La valeur de cette
            propriété peut être définie soit à SAM_PERSISTENT, pour indiquer que la perte des messages n'est
            pas acceptable, soit à SAM_NON_PERSISTENT si la perte de messages est acceptable.
            Le comportement résultant de l'envoi dépendra des capacités du serveur de messagerie auquel
            est connecté le script PHP. Si le serveur ne supporte pas les messages persistants et que
            SAM_PERSISTENT est spécifié, l'envoi échouera avec une erreur indiquant que la fonctionnalité
            n'est pas disponible.
           </entry>
          </row>
          <row>
           <entry>SAM_PRIORITY</entry>
           <entry>
            Une valeur numérique entre 0 et 9 indique la priorité de délivrance du message. Une valeur de priorité
            de 0 indique une priorité basse, alors que 9 indique une priorité haute. Si aucune priorité n'est
            spécifiée, une valeur par défaut sera passée, dépendant du serveur de messagerie utilisé.
           </entry>
          </row>
          <row>
           <entry>SAM_CORRELID</entry>
           <entry>
            Une chaîne à assigner comme identifiant de corrélation pour ce message. Si aucune valeur n'est
            fournie, le serveur de messagerie peut assigner une valeur automatiquement.
           </entry>
          </row>
          <row>
           <entry>SAM_TIMETOLIVE</entry>
           <entry>
            Une durée, en millisecondes, indiquant combien de temps le serveur de messagerie
            doit retenir le message dans une file d'attente avant de le jeter. La valeur par défaut
            est &zero; indiquant que le message doit être retenu indéfiniment.
           </entry>
          </row>
          <row>
           <entry>SAM_WMQ_TARGET_CLIENT</entry>
           <entry>
            Cette propriété n'est valide que lors de l'utilisation de WebSphere MQ et indique si l'on doit
            inclure un en-tête RFH2 dans le message. Cette option doit être définie à 'jms' ou 'mq'.
            Par défaut, elle vaut 'jms' ce qui signifie que l'en-tête RFH2 est incluse. Si la valeur 'mq' est spécifiée,
            alors, aucun en-tête RFH2 ne sera inclus dans le message.
           </entry>
          </row>
         </tbody>
        </tgroup>
       </informaltable>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Un identifiant de corrélation qui peut être utilisé dans un appel de réception en tant que sélecteur pour
   obtenir toutes les réponses, ou &false; si une erreur survient.
  </para>
  <note>
   <para>
    Note : un identifiant de corrélation ne sera retourné qu'en cas d'un envoi réussi à une file d'attente
    (queue://xxxx) et dans ce cas, sera l'identité du message sur la file d'attente. Si l'envoi est destiné
    à publier des données, la valeur retournée sera &true;, car aucun identifiant de corrélation
    ne sera disponible.
   </para>
  </note>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Envoi d'un message à une file d'attente</title>
    <programlisting role="php">
<![CDATA[
<?php
$msg = new SAMMessage('Ceci est un message simple');
$correlId = $conn->send('queue://send/test', $msg);
if (!$correlId) {
    // L'envoi a échoué !
    echo "L'envoi a échoué : ($conn->errno) $conn->error";
}

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Publication d'un message sur un sujet</title>
    <programlisting role="php">
<![CDATA[
<?php
$msg = new SAMMessage('Ceci est un élément simple');
if (!$conn->send('topic://test', $msg)) {
    // L'envoi a échoué !
    echo "L'envoi a échoué : ($conn->errno) $conn->error";
}
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>Envoi une demande et réceptionne la réponse</title>
    <programlisting role="php">
<![CDATA[
<?php
$msg = new SAMMessage('Ceci est un message simple');
$msg->header->SAM_REPLY_TO = 'queue://receive/test';
$correlid = $conn->send('queue://send/test', $msg);

if (!$correlid) {
    // L'envoi a échoué !
    echo "L'envoi a échoué : ($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="function.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:"../../../../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
-->