archived-doc-es/reference/sam/SAMConnection/send.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 0d604bbc9d3b741d53e7fac26f5b24c306751e9a Maintainer: regiemix Status: ready -->
<!-- Reviewed: no -->

<refentry xml:id='samconnection.send' xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>SAMConnection::send</refname>
  <refpurpose>
   Envía un mensaje a una cola o lo publica en un asunto.
  </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>
   El método "send" se utiliza para enviar un mensaje a una cola específica o 
   publicarlo en un asunto específico. El método devuelve el identificador de correlación, que puede 
   ser utilizado como un selector para identificar los mensajes respondidos cuando éstos
   sean solicitados.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>target</parameter></term>
     <listitem>
      <para>
       Si enviamos un mensaje, esta será la identidad de la cola (<literal>queue://queuename</literal>)
       o si lo publicamos en un asunto, la identidad del asunto 
       (<literal>topic://topicname</literal>) al cual el mensaje va a ser enviado.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>msg</parameter></term>
     <listitem>
      <para>
        El mensaje a enviar o publicar.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>properties</parameter></term>
     <listitem>
      <para>
       Un array asociativo opcional de propiedades que describen otros
       parámetros para controlar la operación de recepción.
       <informaltable>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>Nombre de la propiedad</entry>
           <entry>Valores posibles</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry>SAM_DELIVERYMODE</entry>
           <entry>
            Indica si el servidor de mensajería debe asegurar la entrega o
            si es aceptable que los mensajes se pierdan en caso de
            fallo de sistema. El valor de esta propiedad debe fijarse a 
            <constant>SAM_PERSISTENT</constant>, para indicar que la pérdida
            del mensaje no es aceptable, o 
            <constant>SAM_NON_PERSISTENT</constant>, si la pérdida del mensaje es
            aceptable. El comportamiento resultante del envío variará
            dependiendo de las funcionalidades del servidor de mensajería al que esté conectado
            actualmente el script PHP. Si el servidor no soporta
            los mensajes persistentes y <constant>SAM_PERSISTENT</constant> es 
            especificado, la petición de envío fallará con un error
            indicando que la funcionalidad no está disponible.
           </entry>
          </row>
          <row>
           <entry>SAM_PRIORITY</entry>
           <entry>
            Un valor numérico entre 0 y 9 que indica la prioridad de envío del mensaje
            deseada. Un valor de prioridad de 0 indica la menor
            prioridad mientras que 9 indica la mayor prioridad. Si no se especifica prioridad,
            se asignará un valor por defecto que dependerá del
            servidor de mensajería que está siendo utilizado.
           </entry>
          </row>
          <row>
           <entry>SAM_CORRELID</entry>
           <entry>
            Una cadena a asignar como el identificador de correlación para este mensaje. Si
            no se especifica ningún valor, el servidor de mensajería puede asignar un valor
            automáticamente.
           </entry>
          </row>
          <row>
           <entry>SAM_TIMETOLIVE</entry>
           <entry>
            La duración en milisegundos que indica cuanto tiempo el servidor de mensajería
            debe retener el mensaje en una cola antes de descartarlo. El
            valor por defecto es 0 indicando que el mensaje debe retenerse 
            indefinidamente.
           </entry>
          </row>
          <row>
           <entry>SAM_WMQ_TARGET_CLIENT</entry>
           <entry>
            Esta propiedad es válida únicamente cuando se utilice WebSphere MQ e indica
            si la cabecera RFH2 debe incluirse o no dentro del
            mensaje. Esta opción puede definirse con 'jms' o 'mq'. El
            valor por defecto es 'jms' que significa que se incluye una cabecera RFH2.
            Si se especifica el valor 'mq' entonces no se incluye RFH2 en el 
            mensaje. 
           </entry>
          </row>
         </tbody>
        </tgroup>
       </informaltable>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Una cadena con el identificador de correlación que puede utilizarse en una llamada de recepción, como 
   selector para obtener todas las respuestas solicitadas o &false;
   en caso de error.
  </para>
  <note>
   <para>
    Un identificador de correlación sólo será devuelto por un envío con éxito a la cola
    de destinación (<literal>queue://xxxx</literal>) y en ese caso reflejará la identidad 
    del mensaje de la cola. En caso de un envio que esté siendo utilizado 
    para publicar datos en un asunto, el valor de retorno será &true; puesto que ningún
    identificador de correlación estará disponible para ser devuelto.
   </para>
  </note>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Enviar un mensaje a una cola</title>
    <programlisting role="php">
<![CDATA[
<?php
$msg = new SAMMessage('Este es un mensaje simple');
$correlId = $conn->send('queue://send/test', $msg);
if (!$correlId) {
    // El envío falló!
    echo "Envío fallido ($conn->errno) $conn->error";
}

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Publicar un mensaje en un asunto</title>
    <programlisting role="php">
<![CDATA[
<?php
$msg = new SAMMessage('Este es un mensaje simple');
if (!$conn->send('topic://test', $msg)) {
    // El envío falló!
    echo "Envío fallido ($conn->errno) $conn->error";
}
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>Enviar una solicitud y recibir una respuesta</title>
    <programlisting role="php">
<![CDATA[
<?php
$msg = new SAMMessage('Este es un mensaje simple');
$msg->header->SAM_REPLY_TO = 'queue://receive/test';
$correlid = $conn->send('queue://send/test', $msg);

if (!$correlid) {
    // El envío falló!
    echo "Envío fallido ($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
-->