cvs: phpdoc /en/reference/sam constants.xml reference.xml /en/reference/sam/functions SAM-Connection-commit.xml SAM-Connection-connect.xml
SAM-Connection-constructor.xml SAM-Connection-disconnect.xml SAM-Connection-errno.xml SAM-Connection-error.xml SAM-Connection-isConnected.xml
SAM-Connection-peek.xml SAM-Connection-peekall.xml SAM-Connection-receive.xml SAM-Connection-remove.xml SAM-Connection-rollback.xml
SAM-Connection-send.xml SAM-Connection-subscribe.xml SAM-Connection-unsubscribe.xml SAM-Message-body.xml SAM-Message-constructor.xml
SAM-Message-header.xml

From:	Mehdi Achour	Date:	Sun, 04 Feb 2007 04:45:43 +0000
Subject:	cvs: phpdoc /en/reference/sam constants.xml reference.xml /en/reference/sam/functions SAM-Connection-commit.xml SAM-Connection-connect.xml SAM-Connection-constructor.xml SAM-Connection-disconnect.xml SAM-Connection-errno.xml SAM-Connection-error.xml SAM-Connection-isConnected.xml SAM-Connection-peek.xml SAM-Connection-peekall.xml SAM-Connection-receive.xml SAM-Connection-remove.xml SAM-Connection-rollback.xml SAM-Connection-send.xml SAM-Connection-subscribe.xml SAM-Connection-unsubscribe.xml SAM-Message-body.xml SAM-Message-constructor.xml SAM-Message-header.xml
Groups:	php.doc
Request:	Send a blank email to phpdoc+get-969375237@lists.php.net to get a copy of this message

didou Sun Feb 4 04:45:43 2007 UTC Modified files: /phpdoc/en/reference/sam constants.xml reference.xml /phpdoc/en/reference/sam/functions SAM-Connection-commit.xml SAM-Connection-connect.xml SAM-Connection-constructor.xml SAM-Connection-disconnect.xml SAM-Connection-errno.xml SAM-Connection-error.xml SAM-Connection-isConnected.xml SAM-Connection-peek.xml SAM-Connection-peekall.xml SAM-Connection-receive.xml SAM-Connection-remove.xml SAM-Connection-rollback.xml SAM-Connection-send.xml SAM-Connection-subscribe.xml SAM-Connection-unsubscribe.xml SAM-Message-body.xml SAM-Message-constructor.xml SAM-Message-header.xml Log: Fix serious WS/indentation/layout issues lower case file id and fix according to object name Also add see also sections

http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sam/constants.xml?r1=1.4&r2=1.5&diff_format=u Index: phpdoc/en/reference/sam/constants.xml diff -u phpdoc/en/reference/sam/constants.xml:1.4 phpdoc/en/reference/sam/constants.xml:1.5 --- phpdoc/en/reference/sam/constants.xml:1.4 Mon Dec 18 16:24:31 2006 +++ phpdoc/en/reference/sam/constants.xml Sun Feb 4 04:45:43 2007 @@ -1,5 +1,5 @@ <?xml version='1.0' encoding='iso-8859-1'?> - + <section id="mq.constants"> &reftitle.constants; &extension.constants; @@ -33,7 +33,8 @@ </term> <listitem> <simpara> - Connect attribute used to set the name of the enterprise service bus to connect to. + Connect attribute used to set the name of the enterprise service bus to + connect to. </simpara> </listitem> </varlistentry> @@ -66,7 +67,8 @@ </term> <listitem> <simpara> - Attribute used on receive, send and remove requests to identify specific messages. + Attribute used on receive, send and remove requests to identify specific + messages. </simpara> </listitem> </varlistentry> @@ -121,7 +123,8 @@ </term> <listitem> <simpara> - Connect attribute used to set the hostname of the required messaging server. + Connect attribute used to set the hostname of the required messaging + server. </simpara> </listitem> </varlistentry> @@ -165,7 +168,8 @@ </term> <listitem> <simpara> - Attribute used on receive and remove requests to identify specific messages. + Attribute used on receive and remove requests to identify specific + messages. </simpara> </listitem> </varlistentry> @@ -176,8 +180,8 @@ </term> <listitem> <simpara> - Connect attribute value used to request messages are not made persistent on the messaging - server. + Connect attribute value used to request messages are not made persistent + on the messaging server. </simpara> </listitem> </varlistentry> @@ -188,8 +192,9 @@ </term> <listitem> <simpara> - Connect attribute used to define the password to be used for the user account being used to - connect to a messaging server that requires authorisation for connections. + Connect attribute used to define the password to be used for the user + account being used to connect to a messaging server that requires + authorisation for connections. </simpara> </listitem> </varlistentry> @@ -200,8 +205,9 @@ </term> <listitem> <simpara> - Connect attribute value used to request messages are made persistent on the messaging server - to protect against loss of messages in the event of failure. + Connect attribute value used to request messages are made persistent + on the messaging server to protect against loss of messages in the + event of failure. </simpara> </listitem> </varlistentry> @@ -212,8 +218,8 @@ </term> <listitem> <simpara> - Connect attribute used to set the port number on which to communicate with the - messaging server. + Connect attribute used to set the port number on which to communicate + with the messaging server. </simpara> </listitem> </varlistentry> @@ -235,8 +241,8 @@ </term> <listitem> <simpara> - Message propery used to specify the queue identity on to which the script expects response - or reply messages to be posted. + Message propery used to specify the queue identity on to which the + script expects response or reply messages to be posted. </simpara> </listitem> </varlistentry> @@ -247,8 +253,8 @@ </term> <listitem> <simpara> - Connect protocol definition for selecting the IBM Realtime Transport protocol for - communication with a business integration messaging server. + Connect protocol definition for selecting the IBM Realtime Transport + protocol for communication with a business integration messaging server. </simpara> </listitem> </varlistentry> @@ -292,7 +298,8 @@ </term> <listitem> <simpara> - Message send option name used to specify the length of time a message should be retained in milliseconds. + Message send option name used to specify the length of time a message + should be retained in milliseconds. </simpara> </listitem> </varlistentry> @@ -303,8 +310,8 @@ </term> <listitem> <simpara> - Connection attribute used to set required transactional behaviour. May be set to SAM_AUTO - (default) or SAM_MANUAL. + Connection attribute used to set required transactional behaviour. May + be set to SAM_AUTO (default) or SAM_MANUAL. </simpara> </listitem> </varlistentry> @@ -327,7 +334,8 @@ </term> <listitem> <simpara> - Receive property used to specify the wait timeout to be used when receiving a message from a queue or subscription. + Receive property used to specify the wait timeout to be used when + receiving a message from a queue or subscription. </simpara> </listitem> </varlistentry> @@ -338,8 +346,8 @@ </term> <listitem> <simpara> - Connect protocol definition for selecting the IBM WebSphere MQSeries protocol for - communication with the desired messaging server. + Connect protocol definition for selecting the IBM WebSphere MQSeries + protocol for communication with the desired messaging server. </simpara> </listitem> </varlistentry> @@ -350,8 +358,8 @@ </term> <listitem> <simpara> - Connect protocol definition for selecting the IBM WebSphere MQSeries protocol for - communication with a local messaging server. + Connect protocol definition for selecting the IBM WebSphere MQSeries + protocol for communication with a local messaging server. </simpara> </listitem> </varlistentry> @@ -362,8 +370,8 @@ </term> <listitem> <simpara> - Connect protocol definition for selecting the IBM WebSphere MQSeries protocol for - communication with a remote messaging server. + Connect protocol definition for selecting the IBM WebSphere MQSeries + protocol for communication with a remote messaging server. </simpara> </listitem> </varlistentry> @@ -374,8 +382,9 @@ </term> <listitem> <simpara> - Option name used on send requests to specify the target client mode. This can either be default to - 'jms' or 'mq'. The default is 'jms' which means an RFH2 header is sent with the message whereas the 'mq' setting + Option name used on send requests to specify the target client mode. + This can either be default to 'jms' or 'mq'. The default is 'jms' which + means an RFH2 header is sent with the message whereas the 'mq' setting means no RFH2 is included. </simpara> </listitem> @@ -387,8 +396,9 @@ </term> <listitem> <simpara> - Connect protocol definition for selecting the IBM WebSphere Platform Messaging protocol for - communication with a WebSphere Application Server messaging server. + Connect protocol definition for selecting the IBM WebSphere Platform + Messaging protocol for communication with a WebSphere Application Server + messaging server. </simpara> </listitem> </varlistentry> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sam/reference.xml?r1=1.4&r2=1.5&diff_format=u Index: phpdoc/en/reference/sam/reference.xml diff -u phpdoc/en/reference/sam/reference.xml:1.4 phpdoc/en/reference/sam/reference.xml:1.5 --- phpdoc/en/reference/sam/reference.xml:1.4 Mon Dec 18 16:24:31 2006 +++ phpdoc/en/reference/sam/reference.xml Sun Feb 4 04:45:43 2007 @@ -1,5 +1,5 @@ <?xml version='1.0' encoding='iso-8859-1'?> - + <reference id="ref.sam"> <title>SAM - Simple Asynchronous Messaging</title> <titleabbrev>SAM</titleabbrev> @@ -8,71 +8,75 @@ <section id="sam.intro"> &reftitle.intro; <para> - This extension provides access to the functionality of messaging and queueing systems, such - as the IBM WebSphere MQSeries family of products, from PHP scripts. The interface is designed - to make it extremely simple to do the more commonly required tasks such as deliver simple text - messages to queues while still allowing skilled users to do more complex messaging operations. - For many users the complexities of setting up numerous options can be simply ignored. + This extension provides access to the functionality of messaging and + queueing systems, such as the IBM WebSphere MQSeries family of products, + from PHP scripts. The interface is designed to make it extremely simple + to do the more commonly required tasks such as deliver simple text + messages to queues while still allowing skilled users to do more complex + messaging operations. For many users the complexities of setting up + numerous options can be simply ignored. </para> - </section>  + </section> <section id='sam.installation'> &reftitle.install; <section id='sam.installation.prerequisites'> <title>Prerequisites</title> <para> -The SAM extension interfaces to the IBM Messaging and Queuing middleware products using -a set of libraries and some client side code referred to as XMS. This package is -available as a free download in the guise of IBM support pack IA94. There is a description -of this package and download links in the article <ulink url="&url.ibm.ia94;">Introducing XMS - The IBM Message Service API</ulink>. - </para> - <para> -If you intend to use SAM to access the Messaging and Queuing infrastructure within -WebSphere MQ then you will also need to have installed a local MQ queue manager or -installed the WebSphere MQ clients package. The clients package is freely available -as a support pack (<ulink url="&url.ibm.mqc6;">MQC6</ulink>). - </para> - <para> -If you are only aiming to experiment with sending messages to and from WebSphere Application -Server queues using the WebSphere Platform Messaging protocol (WPM) then you do not need -to install the MQC6 package. - </para> - <para> -After installing these packages you will need to ensure the XMS binary and, if you are -using it, the MQ client bin directory are included in the PATH environment variable -so that Apache and PHP can find the dependent .DLLs/libraries. + The SAM extension interfaces to the IBM Messaging and Queuing + middleware products using a set of libraries and some client side code + referred to as XMS. This package is available as a free download in + the guise of IBM support pack IA94. There is a description of this + package and download links in the article <ulink url="&url.ibm.ia94;"> + Introducing XMS - The IBM Message Service API</ulink>. + </para> + <para> + If you intend to use SAM to access the Messaging and Queuing + infrastructure within WebSphere MQ then you will also need to have + installed a local MQ queue manager or installed the WebSphere MQ + clients package. The clients package is freely available as a support + pack (<ulink url="&url.ibm.mqc6;">MQC6</ulink>). + </para> + <para> + If you are only aiming to experiment with sending messages to and from + WebSphere Application Server queues using the WebSphere Platform + Messaging protocol (WPM) then you do not need to install the MQC6 + package. + </para> + <para> + After installing these packages you will need to ensure the XMS binary + and, if you are using it, the MQ client bin directory are included in + the PATH environment variable so that Apache and PHP can find the + dependent .DLLs/libraries. </para> </section> <section id='sam.installation.linux'> <title>Linux installation steps</title> <para> -The sam extension is supplied as a PECL module, which -you should be able to download and install in one step as follows: - <screen> - <![CDATA[ + The sam extension is supplied as a PECL module, which + you should be able to download and install in one step as follows: + <screen> +<![CDATA[ pear install sam ]]> - </screen> -(Depending on your php environment, you will probably need to be root to do this.) + </screen> + (Depending on your php environment, you will probably need to be root + to do this.) </para> <para> -Make sure that the module is loaded by PHP, by adding following line to - &php.ini; - : - <screen> - <![CDATA[ + Make sure that the module is loaded by PHP, by adding following line + to &php.ini;: + <screen> +<![CDATA[ extension=sam.so ]]> - </screen> - </para> - <para> -to your php.ini file. + </screen> </para> <para> -If you cannot use the PEAR installer, you can download the extension and build -it manually: + If you cannot use the PEAR installer, you can download the extension + and build it manually: <screen> - <![CDATA[ +<![CDATA[ pear download sam #downloads sam-<version>.tgz tar -xzf sam-<version>.tgz cd sam-<version> @@ -84,31 +88,31 @@ </screen> </para> <para> -To work with the very latest source, you'll need to extract it from cvs and -build manually as above. + To work with the very latest source, you'll need to extract it from + cvs and build manually as above. </para> </section> <section id='sam.installation.windows'> <title>Windows installation steps</title> <para> -Currently you will need to build the sam extension for Windows as there -are no pre-built binaries. The extension can be built using the standard -Windows extension build procedures. + Currently you will need to build the sam extension for Windows as + there are no pre-built binaries. The extension can be built using the + standard Windows extension build procedures. </para> <para> -You will need the PHP source tree for the version of PHP you wish to build -the SAM extension against which you can obtain from php.net. This should be -unpacked into a working directory of your choice. + You will need the PHP source tree for the version of PHP you wish to + build the SAM extension against which you can obtain from php.net. + This should be unpacked into a working directory of your choice. </para> <para> -You will also need the libraries and headers used by PHP extensions available -from http://www.php.net/extra/win32build.zip and this should be unzipped so -that is in your working directory. + You will also need the libraries and headers used by PHP extensions + available from http://www.php.net/extra/win32build.zip and this + should be unzipped so that is in your working directory. </para> <para> -You should have something like: + You should have something like: <screen> - <![CDATA[ +<![CDATA[ c:\php-build\- | |---php-5.0.5--|---build @@ -118,65 +122,66 @@ |---win32build--|---bin |---include |---lib - ]]> +]]> </screen> </para> <para> -You will need a compiler such as the free version of Visual Studio C++ -Express from the Microsoft web site. Also you need the Microsoft Windows -Platform SDK which again can be downloaded from the Microsoft web site. + You will need a compiler such as the free version of Visual Studio C++ + Express from the Microsoft web site. Also you need the Microsoft + Windows Platform SDK which again can be downloaded from the Microsoft web site. </para> <para> -Obtain the SAM extension source using pear (pear download sam) or by using -CVS and copy the files to a new "sam" directory under the "ext" directory -in your PHP source tree. + Obtain the SAM extension source using pear (pear download sam) or by + using CVS and copy the files to a new "sam" directory under the "ext" + directory in your PHP source tree. </para> <para> -To build the extension open a build environment window by going to the -start menu->all programs->microsoft platform SDK for windows-> - open build environment window->windows 200 build environment-> - set windows 2000 build environment (retail) + To build the extension open a build environment window by going to the + start menu->all programs->microsoft platform SDK for windows-> + open build environment window->windows 200 build environment-> + set windows 2000 build environment (retail) </para> <para> -This should open a command prompt with all the environment variables set -up to access the platform SDK etc. You then need to set the environment -variables for Visual Studio by issuing the command "vcvars32.bat" in the -window. + This should open a command prompt with all the environment variables + set up to access the platform SDK etc. You then need to set the + environment variables for Visual Studio by issuing the command + "vcvars32.bat" in the window. </para> <para> -Change directory to your working directory e.g. cd c:\php-build. Then -make sure the win32build tools are accessible by adding them to the PATH -environment variable: - <screen> - <![CDATA[ + Change directory to your working directory e.g. cd c:\php-build. Then + make sure the win32build tools are accessible by adding them to the + PATH environment variable: + <screen> +<![CDATA[ set PATH=..\win32build\bin;%PATH% ]]> - </screen> + </screen> </para> - <para> -Run the buildconf.bat command. This should rebuild the configure.js file. + <para> + Run the buildconf.bat command. This should rebuild the configure.js + file. </para> <para> -Run the cscript command: - <screen> - <![CDATA[ + Run the cscript command: + <screen> +<![CDATA[ cscript /nologo configure.js --with-sam="c:\program files\ibm\xms" ]]> - </screen> + </screen> </para> <para> -The additional parameter passed for sam is the installation path to the -XMS libraries and runtime that were installed as described under prerequisites -at the top of this file. + The additional parameter passed for sam is the installation path to + the XMS libraries and runtime that were installed as described under + prerequisites at the top of this file. </para> <para> -You can specify whatever other cscript parameters you require to include or -exclude items from the php build or select options. + You can specify whatever other cscript parameters you require to + include or exclude items from the php build or select options. </para> <para> -Assuming all has gone well so far you can now finally run a make! - <screen> - <![CDATA[ + Assuming all has gone well so far you can now finally run a make! + <screen> +<![CDATA[ nmake php_sam.dll ]]> </screen> @@ -185,23 +190,27 @@ <section id='sam.installation.VS2005'> <title>Additional steps for Visual Studio 2005</title> <para> -If you build the SAM extension with the Microsoft Visual Studio 2005 compiler and -tools you need to perform an additional step in the build process to ensure the -php_sam.dll is able to link with the C runtime libraries at runtime. This step -includes the dependancy manifest into the DLL. Switch to the directory where the -php_sam.dll has been generated (usually Release_TS or Debug_TS below the php -source directory) and issue the following magic incantation: - <screen> - <![CDATA[ + If you build the SAM extension with the Microsoft Visual Studio 2005 + compiler and tools you need to perform an additional step in the build + process to ensure the <filename>php_sam.dll</filename> is able to link + with the C runtime libraries at runtime. This step includes the + dependancy manifest into the DLL. Switch to the directory where the + <filename>php_sam.dll</filename> has been generated (usually + Release_TS or Debug_TS below the php source directory) and issue the + following magic incantation: + <screen> +<![CDATA[ mt.exe -manifest php_sam.dll.manifest -outputresource:php_sam.dll;2 ]]> - </screen> + </screen> </para> <para> -If you build the SAM extension using the compiler and libaries from Microsoft Visual Studio 2005 -you will also need to ensure that the runtime components are installed on the system on -which you intend to use SAM. This can be accomplished by installing Visual Studio 2005 or -by using the freely distributable <ulink url="&url.ms.crt;">runtime package</ulink>. + If you build the SAM extension using the compiler and libaries from + Microsoft Visual Studio 2005 you will also need to ensure that the + runtime components are installed on the system on which you intend to + use SAM. This can be accomplished by installing Visual Studio 2005 or + by using the freely distributable + <ulink url="&url.ms.crt;">runtime package</ulink>. </para> </section> </section>  @@ -212,29 +221,31 @@ <section id='sam.connections'> <title>Connections</title> <para> - In order to perform any messaging and queueing functions a connection must be established - with a messaging server by creating a SAMConnection object and calling its "connect" - method, with a set of connection properties, to connect the PHP script to the messaging - server. Until such time as the SAMConnection object is destroyed the connection - will be maintained and available for use. All SAMConnection objects are destroyed when - the PHP script exits. + In order to perform any messaging and queueing functions a connection + must be established with a messaging server by creating a SAMConnection + object and calling its "connect" method, with a set of connection + properties, to connect the PHP script to the messaging server. Until + such time as the SAMConnection object is destroyed the connection + will be maintained and available for use. All SAMConnection objects + are destroyed when the PHP script exits. </para> <para> - A set of default properties may be used in connecting to a messaging server but as a - minimum the PHP script must specify a protocol to be used. + A set of default properties may be used in connecting to a messaging + server but as a minimum the PHP script must specify a protocol to be + used. </para> <para> <example> <title>Creating a connection and connecting to a remote WebSphere MQSeries Messaging Server</title> <programlisting role='php'> - <![CDATA[ +<![CDATA[ <?php - $conn = new SAMConnection(); - $conn->connect(SAM_WMQ, array(SAM_HOST => myhost.mycompany.com, - SAM_PORT => 1506, - SAM_BROKER => mybroker)); +$conn = new SAMConnection(); +$conn->connect(SAM_WMQ, array(SAM_HOST => myhost.mycompany.com, + SAM_PORT => 1506, + SAM_BROKER => mybroker)); ?> - ]]> +]]> </programlisting> </example> </para> @@ -242,14 +253,14 @@ <example> <title>Creating a connection and connecting to a remote WebSphere Application Server</title> <programlisting role='php'> - <![CDATA[ +<![CDATA[ <?php - $conn = new SAMConnection(); - $conn->connect(SAM_WMQ, array(SAM_ENDPOINTS => 'localhost:7278:BootstrapBasicMessaging', - SAM_BUS => 'Bus1', - SAM_TARGETCHAIN => 'InboundBasicMessaging')); +$conn = new SAMConnection(); +$conn->connect(SAM_WMQ, array(SAM_ENDPOINTS => 'localhost:7278:BootstrapBasicMessaging', + SAM_BUS => 'Bus1', + SAM_TARGETCHAIN => 'InboundBasicMessaging')); ?> - ]]> +]]> </programlisting> </example> </para> @@ -258,28 +269,30 @@ <section id='sam.messages'> <title>Messages</title> <para> - Messages sent to and received from queues are represented by the SAMMessage object. The - SAMMessage object encapsulates the body of the message (if one exists) and the header - properties associated with the message. A SAMMessage object - is either supplied as a parameter to a messaging operation or returned as a result. + Messages sent to and received from queues are represented by the + SAMMessage object. The SAMMessage object encapsulates the body of + the message (if one exists) and the header properties associated with + the message. A SAMMessage object is either supplied as a parameter to + a messaging operation or returned as a result. </para> <para> <example> <title>Creating a message with a simple text body</title> <programlisting role="php"> - <![CDATA[ +<![CDATA[ <?php - $msg = new SAMMessage('This is a simple text message'); +$msg = new SAMMessage('This is a simple text message'); ?> - ]]> +]]> </programlisting> </example> </para> <para> - Messages may have header properties associated with them that provide control over the - transport of the message or further information to the receiving application. By default - message properties are delivered to the underlying messaging system as strings and in - this case they may be set with the following simple syntax: + Messages may have header properties associated with them that provide + control over the transport of the message or further information to the + receiving application. By default message properties are delivered to + the underlying messaging system as strings and in this case they may be + set with the following simple syntax: </para> <para> <example> @@ -294,8 +307,9 @@ </example> </para> <para> - If it is desired to pass type information an alternative syntax may be used where the - value and the type hint are passed in an associative array: + If it is desired to pass type information an alternative syntax may be + used where the value and the type hint are passed in an associative + array: </para> <para> <example> @@ -329,29 +343,31 @@ <section id='sam.operations'> <title>Messaging operations</title> <para> - All messaging operations are performed through calls to methods on the connection object. - To add a message to a queue the "send" method is used, to obtain a message from a queue the - "receive" method is used. Other methods provide publish and subscribe functionality and - control of transaction boundaries. + All messaging operations are performed through calls to methods on the + connection object. + To add a message to a queue the "send" method is used, to obtain a + message from a queue the "receive" method is used. Other methods + provide publish and subscribe functionality and control of transaction + boundaries. </para> <para> <example> <title>Adding a message to a queue and receiving a response</title> <programlisting role="php"> - <![CDATA[ +<![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)); - } +$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> @@ -359,41 +375,51 @@ <section id='sam.pubsub'> <title>Publish/Subscribe and suscriptions to topics</title> <para> - SAM allows messages to be sent either to queues or, for WebSphere MQ and WPM, to publish/subscribe topics. - A topic desintation is specified to SAM in the usual way, i.e. in the form 'topic://fred', rather than the form - 'queue://AQUEUE' used for point to point operation. To use publish/subscribe it is simply necessary to specify the - correct broker name on the SAMConnect "connect" call and the desired topic in the destination argument to the SAMConnect "send" - and "receive" calls. The PHP interface is otherwise identical to the point to point model. - </para> - <para> - By default, SAM creates non-durable subscriptions when using publish/subscribe. This means that if a client application is - inactive when messages are published to a topic, then it will not receive them when it subsequently restarted. SAM does also - allow durable subscriptions to be made to topics when using WPM or WebSphere MQ publish/subscribe. The purpose of these - subscriptions is to allow data to be received by a client application even if that client was not active at the time - the data was published. - </para> - <para> - Durable subscriptions are specified by using the SAMConnect "subscribe" call. This method takes the destination topic as an - input parameter and returns a subscription identifier that may be used on subsequent "receive" calls. When the subscription - is no longer required the SAMConnection "unsubscribe" method should be used to delete the subscription. + SAM allows messages to be sent either to queues or, for WebSphere MQ + and WPM, to publish/subscribe topics. + A topic desintation is specified to SAM in the usual way, i.e. in the + form 'topic://fred', rather than the form 'queue://AQUEUE' used for + point to point operation. To use publish/subscribe it is simply + necessary to specify the correct broker name on the SAMConnect + "connect" call and the desired topic in the destination argument to + the SAMConnect "send" and "receive" calls. The PHP interface is + otherwise identical to the point to point model. + </para> + <para> + By default, SAM creates non-durable subscriptions when using + publish/subscribe. This means that if a client application is + inactive when messages are published to a topic, then it will not + receive them when it subsequently restarted. SAM does also allow + durable subscriptions to be made to topics when using WPM or WebSphere + MQ publish/subscribe. The purpose of these subscriptions is to allow + data to be received by a client application even if that client was not + active at the time the data was published. + </para> + <para> + Durable subscriptions are specified by using the SAMConnect "subscribe" + call. This method takes the destination topic as an input parameter and + returns a subscription identifier that may be used on subsequent + "receive" calls. When the subscription is no longer required the + SAMConnection "unsubscribe" method should be used to delete the + subscription. </para> <para> <example> <title>Creating a durable subscription to a topic</title> <programlisting role="php"> - <![CDATA[ +<![CDATA[ <?php - $subName = $conn->subscribe('topic://A'); +$subName = $conn->subscribe('topic://A'); - if (!$subName) { - echo "Subscribe failed"; - } else { - # Subscribe was OK - ... - } +if (!$subName) { + echo "Subscribe failed"; +} else { + # Subscribe was OK + // ... +} ?> - ]]> +]]> </programlisting> </example> </para> @@ -401,26 +427,26 @@ <example> <title>Subscribing to a topic using a WebSphere Platform Messaging (WPM) server</title> <programlisting role="php"> - <![CDATA[ +<![CDATA[ <?php - $conn = new SAMConnection(); - // Note: For pub/sub on WPM, when connecting the name of a messaging engine - // to hold the durable subscription (SAM_WPM_DUR_SUB_HOME) must be specified. - $conn->connect(SAM_WMQ, array(SAM_ENDPOINTS => 'localhost:7278:BootstrapBasicMessaging', - SAM_BUS => 'Bus1', - SAM_TARGETCHAIN => 'InboundBasicMessaging' - SAM_WPM_DUR_SUB_HOME => 'MyMachineNode01.server1-Bus1')); - - $subName = $conn->subscribe('topic://A'); - - if (!$subName) { - echo "Subscribe failed"; - } else { - # Subscribe was OK - ... - } +$conn = new SAMConnection(); +// Note: For pub/sub on WPM, when connecting the name of a messaging engine +// to hold the durable subscription (SAM_WPM_DUR_SUB_HOME) must be specified. +$conn->connect(SAM_WMQ, array(SAM_ENDPOINTS => 'localhost:7278:BootstrapBasicMessaging', + SAM_BUS => 'Bus1', + SAM_TARGETCHAIN => 'InboundBasicMessaging' + SAM_WPM_DUR_SUB_HOME => 'MyMachineNode01.server1-Bus1')); + +$subName = $conn->subscribe('topic://A'); + +if (!$subName) { + echo "Subscribe failed"; +} else { + # Subscribe was OK + // ... +} ?> - ]]> +]]> </programlisting> </example> </para> @@ -428,18 +454,18 @@ <example> <title>Receiving published data using a durable subscription</title> <programlisting role="php"> - <![CDATA[ +<![CDATA[ <?php - $msg = $conn->receive($subName); - if ($msg) { - echo "Received a message OK"; - } else { - echo "The receive failed"; - } +$msg = $conn->receive($subName); +if ($msg) { + echo "Received a message OK"; +} else { + echo "The receive failed"; +} ?> - ]]> +]]> </programlisting> </example> </para> @@ -447,15 +473,15 @@ <example> <title>Deleting a durable subscription to a topic</title> <programlisting role="php"> - <![CDATA[ +<![CDATA[ <?php - if (!$conn->unsubscribe($subName)) { - echo "Unsubscribe failed"; - } +if (!$conn->unsubscribe($subName)) { + echo "Unsubscribe failed"; +} ?> - ]]> +]]> </programlisting> </example> </para> @@ -463,9 +489,10 @@ <section id='sam.errors'> <title>Error handling</title> <para> - All SAMConnection methods that provide access to messaging operations return &false; - if an error occurred in processing the request. In addition the SAMConnection object - has two properties, "errno" and "error", that provide respectively the error number and + All SAMConnection methods that provide access to messaging operations + return &false; if an error occurred in processing the request. + In addition the SAMConnection object has two properties, "errno" + and "error", that provide respectively the error number and text description of the last error to occur on the connection. </para> <para> @@ -487,18 +514,18 @@ <example> <title>Handling an error from a method that returns a result</title> <programlisting role="php"> - <![CDATA[ +<![CDATA[ <?php - $correlid = $conn->send('queue://send/test', $msg); +$correlid = $conn->send('queue://send/test', $msg); - if (!$correlid) { - // The Send failed! - echo "Send failed ($conn->errno) $conn->error"; - } else { - ... - } +if (!$correlid) { + // The Send failed! + echo "Send failed ($conn->errno) $conn->error"; +} else { + ... +} ?> - ]]> +]]> </programlisting> </example> </para> @@ -509,7 +536,7 @@ <section id='sam.classes'> &reftitle.classes; - + <section id='sam.class.Connection'> <title><classname>SAMConnection</classname></title> <para> @@ -521,7 +548,7 @@ <itemizedlist> <listitem> <para> - <link linkend='function.SAM-Connection-constructor'>new SAMConnection</link> - construct a new connection object to allow connection to a messaging infrastructure. + <link linkend='function.samconnection-constructor'>new SAMConnection</link> - construct a new connection object to allow connection to a messaging infrastructure. </para> </listitem> </itemizedlist> @@ -532,73 +559,77 @@ <itemizedlist> <listitem> <para> - <link linkend='function.SAM-Connection-commit'>commit</link> - - a method that commits (successfully completes) an in-flight unit of work. + <link linkend='function.samconnection-commit'>commit</link> + - a method that commits (successfully completes) an in-flight unit + of work. </para> </listitem> <listitem> <para> - <link linkend='function.SAM-Connection-connect'>connect</link> + <link linkend='function.samconnection-connect'>connect</link> - a method that connects a PHP script to a messaging server. </para> </listitem> <listitem> <para> - <link linkend='function.SAM-Connection-disconnect'>disconnect</link> + <link linkend='function.samconnection-disconnect'>disconnect</link> - a method that disconnects a PHP script from a messaging server. </para> </listitem> <listitem> <para> - <link linkend='function.SAM-Connection-isConnected'>isConnected</link> - - a method that checks whether a PHP script is connected to a messaging server. + <link linkend='function.samconnection-isconnected'>isConnected</link> + - a method that checks whether a PHP script is connected to a + messaging server. </para> </listitem> <listitem> <para> - <link linkend='function.SAM-Connection-peek'>peek</link> - - a method that receives a message from a queue without removing it from the queue. + <link linkend='function.samconnection-peek'>peek</link> + - a method that receives a message from a queue without removing it + from the queue. </para> </listitem> <listitem> <para> - <link linkend='function.SAM-Connection-peekAll'>peekAll</link> - - a method that receives one or messages from a queue without removing them from the queue. + <link linkend='function.samconnection-peekall'>peekAll</link> + - a method that receives one or messages from a queue without + removing them from the queue. </para> </listitem> <listitem> <para> - <link linkend='function.SAM-Connection-receive'>receive</link> + <link linkend='function.samconnection-receive'>receive</link> - a method that receives a message from a queue or subscription. </para> </listitem> <listitem> <para> - <link linkend='function.SAM-Connection-remove'>remove</link> + <link linkend='function.samconnection-remove'>remove</link> - a method that removes a message from a queue. </para> </listitem> <listitem> <para> - <link linkend='function.SAM-Connection-rollback'>rollback</link> + <link linkend='function.samconnection-rollback'>rollback</link> - a method that cancels (rolls back) an in-flight unit of work. </para> </listitem> <listitem> <para> - <link linkend='function.SAM-Connection-send'>send</link> + <link linkend='function.samconnection-send'>send</link> - a method that sends a message to a queue or posts to a topic </para> </listitem> <listitem> <para> - <link linkend='function.SAM-Connection-subscribe'>subscribe</link> + <link linkend='function.samconnection-subscribe'>subscribe</link> - a method that creates a subscription to one or more topics </para> </listitem> <listitem> <para> - <link linkend='function.SAM-Connection-unsubscribe'>unsubscribe</link> + <link linkend='function.samconnection-unsubscribe'>unsubscribe</link> - a method that destroys a subscription to one or more topics </para> </listitem> @@ -610,15 +641,16 @@ <itemizedlist> <listitem> <para> - <link linkend='function.SAM-Connection-errno'>errno</link> - the numeric error code - for the last encountered error on this connection. This property is set to 0 if the last - operation was successful. + <link linkend='function.samconnection-errno'>errno</link> - the + numeric error code for the last encountered error on this + connection. This property is set to 0 if the last operation was + successful. </para> </listitem> <listitem> <para> - <link linkend='function.SAM-Connection-error'>error</link> - the text description - for the last encountered error on this connection + <link linkend='function.samconnection-error'>error</link> - the + text description for the last encountered error on this connection </para> </listitem> </itemizedlist> @@ -637,7 +669,7 @@ <itemizedlist> <listitem> <para> - <link linkend='function.SAM-Message-constructor'>new SAMMessage</link> - construct a + <link linkend='function.sammessage-constructor'>new SAMMessage</link> - construct a new message. </para> </listitem> @@ -649,12 +681,14 @@ <itemizedlist> <listitem> <para> - <link linkend='function.SAM-Message-body'>body</link> - the body of the message. + <link linkend='function.sammessage-body'>body</link> - the body of + the message. </para> </listitem> <listitem> <para> - <link linkend='function.SAM-Message-header'>header</link> - the header properties of the message. + <link linkend='function.sammessage-header'>header</link> - the + header properties of the message. </para> </listitem> </itemizedlist> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sam/functions/SAM-Connection-commit.xml?r1=1.4&r2=1.5&diff_format=u Index: phpdoc/en/reference/sam/functions/SAM-Connection-commit.xml diff -u phpdoc/en/reference/sam/functions/SAM-Connection-commit.xml:1.4 phpdoc/en/reference/sam/functions/SAM-Connection-commit.xml:1.5 --- phpdoc/en/reference/sam/functions/SAM-Connection-commit.xml:1.4 Mon Dec 18 16:24:16 2006 +++ phpdoc/en/reference/sam/functions/SAM-Connection-commit.xml Sun Feb 4 04:45:43 2007 @@ -1,24 +1,24 @@ <?xml version="1.0" encoding="iso-8859-1"?> - -<refentry id='function.SAM-Connection-commit'> + +<refentry id='function.samconnection-commit'> <refnamediv> - <refname>SAMConnection::commit()</refname> + <refname>SAMConnection->commit()</refname> <refpurpose> Commits (completes) the current unit of work. </refpurpose> </refnamediv> <refsect1 role="description"> &reftitle.description; - <para> - Calling the "commit" method on a Connection object commits (completes) all in-flight - transactions that are part of the current unit of work. - </para> <classsynopsis> <ooclass><classname>SAMConnection</classname></ooclass> <methodsynopsis> <type>bool</type><methodname>commit</methodname><void/> </methodsynopsis> </classsynopsis> + <para> + Calling the "commit" method on a Connection object commits (completes) all + in-flight transactions that are part of the current unit of work. + </para> </refsect1> <refsect1 role="returnvalues"> @@ -46,6 +46,16 @@ </example> </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><xref linkend="function.samconnection-rollback" /></member> + </simplelist> + </para> + </refsect1> + </refentry>  -<refentry id='function.SAM-Connection-connect'> + +<refentry id='function.samconnection-connect'> <refnamediv> - <refname>SAMConnection::connect()</refname> + <refname>SAMConnection->connect()</refname> <refpurpose> Establishes a connection to a Messaging Server </refpurpose> @@ -10,10 +10,6 @@ <refsect1 role="description"> &reftitle.description; - <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> <classsynopsis> <ooclass><classname>SAMConnection</classname></ooclass> <methodsynopsis> @@ -22,6 +18,11 @@ <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"> @@ -32,59 +33,72 @@ <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. + 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: + 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>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> + <tgroup cols="2"> + <thead> + <row> + <entry>Protocol string</entry> + <entry>Constant</entry> + <entry>Usage</entry> + </row> + </thead> + <tbody> + <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> @@ -93,108 +107,133 @@ <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: + 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 - or 1506 for SAM_WPM - </entry> - <entry> - The port number on which to attempt communication with the messaging server. - </entry> - </row> - <row> - <entry>SAM_CLIENT_ID</entry> - <entry>none</entry> - <entry> - A string used to uniquely identify the client when accessing subscriptions. - <para> - Warning: Not yet implemented! - </para> - </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_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> + <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> + <para> + The name of the broker or queue manager running on the messaging + server. + </para> + <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 + or 1506 for SAM_WPM + </entry> + <entry> + The port number on which to attempt communication with the + messaging server. + </entry> + </row> + <row> + <entry>SAM_CLIENT_ID</entry> + <entry>none</entry> + <entry> + <para> + A string used to uniquely identify the client when accessing + subscriptions. + </para> + <para> + Warning: Not yet implemented! + </para> + </entry> + </row> + <row> + <entry>SAM_EXPIRE_AFTER</entry> + <entry>0</entry> + <entry> + <para> + 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> + <para> + Warning: Not yet implemented! + </para> + </entry> + </row> + <row> + <entry>SAM_MESSAGE_PERSISTENCE</entry> + <entry>none</entry> + <entry> + <para> + 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> + <para> + Warning: Not yet implemented! + </para> + </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> @@ -214,7 +253,10 @@ &reftitle.examples; <para> <example> - <title>Creating a connection to a Messaging Server using the IBM MQSeries protocol (WMQ)</title> + <title> + Creating a connection to a Messaging Server using the IBM MQSeries + protocol (WMQ) + </title> <programlisting role="php"> <![CDATA[ <?php @@ -228,7 +270,10 @@ </para> <para> <example> - <title>Creating a connection with application transaction control and default host and port values</title> + <title> + Creating a connection with application transaction control and default + host and port values + </title> <programlisting role="php"> <![CDATA[ <?php @@ -242,7 +287,10 @@ </para> <para> <example> - <title>Creating a connection to a Messaging Server using the IBM WebSphere Platform Messaging protocol (WPM)</title> + <title> + Creating a connection to a Messaging Server using the IBM WebSphere + Platform Messaging protocol (WPM) + </title> <programlisting role="php"> <![CDATA[ <?php @@ -256,6 +304,17 @@ </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>  -<refentry id='function.SAM-Connection-constructor'> + +<refentry id='function.samconnection-constructor'> <refnamediv> - <refname>SAMConnection::SAMConnection()</refname> + <refname>SAMConnection->__construct()</refname> <refpurpose> Creates a new connection to a Messaging Server </refpurpose> @@ -13,8 +13,8 @@ <classsynopsis> <ooclass><classname>SAMConnection</classname></ooclass> <constructorsynopsis> - <methodname>SAMConnection</methodname> - <methodparam ><type>null</type><parameter></parameter></methodparam> + <methodname>__construct</methodname> + <methodparam><type/><parameter/></methodparam> </constructorsynopsis> </classsynopsis> <para> @@ -22,7 +22,6 @@ </para> </refsect1> - <refsect1 role="examples"> &reftitle.examples; <para> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sam/functions/SAM-Connection-disconnect.xml?r1=1.3&r2=1.4&diff_format=u Index: phpdoc/en/reference/sam/functions/SAM-Connection-disconnect.xml diff -u phpdoc/en/reference/sam/functions/SAM-Connection-disconnect.xml:1.3 phpdoc/en/reference/sam/functions/SAM-Connection-disconnect.xml:1.4 --- phpdoc/en/reference/sam/functions/SAM-Connection-disconnect.xml:1.3 Fri Dec 8 17:20:48 2006 +++ phpdoc/en/reference/sam/functions/SAM-Connection-disconnect.xml Sun Feb 4 04:45:43 2007 @@ -1,8 +1,8 @@ <?xml version="1.0" encoding="iso-8859-1"?> - -<refentry id='function.SAM-Connection-disconnect'> + +<refentry id='function.samconnection-disconnect'> <refnamediv> - <refname>SAMConnection::disconnect()</refname> + <refname>SAMConnection->disconnect()</refname> <refpurpose> Disconnects from a Messaging Server </refpurpose> @@ -10,17 +10,24 @@ <refsect1 role="description"> &reftitle.description; - <para> - Calling the "disconnect" method on a SAMConnection object disconnects the PHP script from a - messaging server. No messages can be sent or received after a connection has been - disconnected. - </para> <classsynopsis> <ooclass><classname>SAMConnection</classname></ooclass> <methodsynopsis> <type>bool</type><methodname>disconnect</methodname><void/> </methodsynopsis> </classsynopsis> + <para> + Calling the "disconnect" method on a SAMConnection object disconnects the + PHP script from a messaging server. No messages can be sent or received + after a connection has been disconnected. + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + &return.success; + </para> </refsect1> <refsect1 role="examples"> @@ -40,6 +47,17 @@ </example> </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><xref linkend="function.samconnection-isconnected" /></member> + <member><xref linkend="function.samconnection-connect" /></member> + </simplelist> + </para> + </refsect1> + </refentry>  -<refentry id="function.SAM-Connection-errno"> + +<refentry id="function.samconnection-errno"> <refnamediv> <refname>SAMConnection->errno</refname> <refpurpose>Contains the unique numeric error code of the last executed SAM operation.</refpurpose> </refnamediv> - <refsect1> + <refsect1 role="description"> <title>Description</title> <classsynopsis> <ooclass><classname>SAMConnection</classname></ooclass> <fieldsynopsis><type>int</type><varname>errno</varname></fieldsynopsis> </classsynopsis> <para> - <function>errno</function> Contains the numeric error code of the last executed SAM operation on this connection. If the last operation completed successfully this property contains 0. + Contains the numeric error code of the last executed SAM operation on this + connection. If the last operation completed successfully this property + contains 0. </para> </refsect1> - <refsect1> + <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> - An integer greater than zero indicates the last error type encountered on the connection. Zero indicates that the last operation on this connection completed successfully. + An integer greater than zero indicates the last error type encountered on + the connection. Zero indicates that the last operation on this connection + completed successfully. </para> </refsect1> - <refsect1> - &reftitle.seealso; - <para> - <function>SAMConnection->error</function> - </para> - </refsect1> - - <refsect1> + <refsect1 role="examples"> &reftitle.examples; <para> <example> @@ -53,6 +50,15 @@ </para> </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><xref linkend="function.samconnection-error" /></member> + </simplelist> + </para> + </refsect1> + </refentry>  - <refentry id="function.SAM-Connection-error"> + +<refentry id="function.samconnection-error"> <refnamediv> <refname>SAMConnection->error</refname> <refpurpose>Contains the text description of the last failed SAM operation.</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <classsynopsis> <ooclass><classname>SAMConnection</classname></ooclass> <fieldsynopsis><type>string</type><varname>error</varname></fieldsynopsis> </classsynopsis> <para> - <function>error</function> Contains the text description of the last failed SAM operation on this connection. If the last operation completed successfully this property contains an empty string. + Contains the text description of the last failed SAM operation on this + connection. If the last operation completed successfully this property + contains an empty string. </para> </refsect1> - <refsect1> + <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> - A string containing the text description of the last error type encountered on the connection. An empty string indicates that the last operation on this connection completed successfully. - </para> - </refsect1> - - <refsect1> - &reftitle.seealso; - <para> - <function>SAMConnection->errno</function> + A string containing the text description of the last error type encountered + on the connection. An empty string indicates that the last operation on + this connection completed successfully. </para> </refsect1> - <refsect1> + <refsect1 role="examples"> &reftitle.examples; <para> <example> @@ -51,6 +49,16 @@ </example> </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><xref linkend="function.samconnection-errno" /></member> + </simplelist> + </para> + </refsect1> + </refentry>  -<refentry id='function.SAM-Connection-isConnected'> + +<refentry id='function.samconnection-isconnected'> <refnamediv> - <refname>SAMConnection::isConnected()</refname> + <refname>SAMConnection->isConnected()</refname> <refpurpose> Queries whether a connection is established to a Messaging Server </refpurpose> @@ -10,18 +10,27 @@ <refsect1 role="description"> &reftitle.description; - <para> - Calling the "isConnected" method on a Connection object will check whether the PHP script - is connected to a messaging server. The method returns &true; if the SAMConnection object - is successfully connected to a Messaging server or &false; otherwise. No messages can be sent - or received unless a connection has been established with a Messaging server. - </para> <classsynopsis> <ooclass><classname>SAMConnection</classname></ooclass> <methodsynopsis> - <type>bool</type><methodname>isConnected</methodname><void/> + <type>bool</type><methodname>isConnected</methodname> + <void/> </methodsynopsis> </classsynopsis> + <para> + Calling the "isConnected" method on a Connection object will check whether + the PHP script is connected to a messaging server. No messages can be sent + or received unless a connection has been established with a Messaging + server. + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + This method returns &true; if the SAMConnection object is successfully + connected to a Messaging server or &false; otherwise. + </para> </refsect1> <refsect1 role="examples"> @@ -45,6 +54,17 @@ </example> </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><xref linkend="function.samconnection-disconnect" /></member> + <member><xref linkend="function.samconnection-connect" /></member> + </simplelist> + </para> + </refsect1> + </refentry>  -<refentry id='function.SAM-Connection-peek'> + +<refentry id='function.samconnection-peek'> <refnamediv> - <refname>SAMConnection::peek()</refname> + <refname>SAMConnection->peek()</refname> <refpurpose> Read a message from a queue without removing it from the queue. </refpurpose> @@ -14,8 +14,8 @@ <ooclass><classname>SAMConnection</classname></ooclass> <methodsynopsis> <type>SAMMessage</type><methodname>peek</methodname> - <methodparam><type>string</type><parameter>target</parameter></methodparam> - <methodparam choice='opt'><type>array</type><parameter>properties</parameter></methodparam> + <methodparam><type>string</type><parameter>target</parameter></methodparam> + <methodparam choice='opt'><type>array</type><parameter>properties</parameter></methodparam> </methodsynopsis> </classsynopsis> </refsect1> @@ -36,26 +36,33 @@ <term><parameter>properties</parameter></term> <listitem> <para> - An optional associative array of properties describing other parameters to control the peek operation. + An optional associative array of properties describing other + parameters to control the peek operation. <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Property name</entry> - <entry>Possible values</entry> - </row> - </thead> - <tbody> - <row> - <entry>SAM_CORRELID</entry> - <entry>This is the target correlation id string of the message. This would typically have been returned by a "send" request.</entry> - </row> - <row> - <entry>SAM_MESSAGEID</entry> - <entry>This is the message id string of the message which is to be peeked.</entry> - </row> - </tbody> - </tgroup> + <tgroup cols="2"> + <thead> + <row> + <entry>Property name</entry> + <entry>Possible values</entry> + </row> + </thead> + <tbody> + <row> + <entry>SAM_CORRELID</entry> + <entry> + This is the target correlation id string of the message. This + would typically have been returned by a "send" request. + </entry> + </row> + <row> + <entry>SAM_MESSAGEID</entry> + <entry> + This is the message id string of the message which is to be + peeked. + </entry> + </row> + </tbody> + </tgroup> </informaltable> </para> </listitem> @@ -105,6 +112,16 @@ </example> </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><xref linkend="function.samconnection-peekall" /></member> + </simplelist> + </para> + </refsect1> + </refentry>  -<refentry id='function.SAM-Connection-peekAll'> + +<refentry id='function.samconnection-peekall'> <refnamediv> - <refname>SAMConnection::peekAll()</refname> + <refname>SAMConnection->peekAll()</refname> <refpurpose> Read one or more messages from a queue without removing it from the queue. </refpurpose> @@ -14,8 +14,8 @@ <ooclass><classname>SAMConnection</classname></ooclass> <methodsynopsis> <type>array</type><methodname>peekAll</methodname> - <methodparam><type>string</type><parameter>target</parameter></methodparam> - <methodparam choice='opt'><type>array</type><parameter>properties</parameter></methodparam> + <methodparam><type>string</type><parameter>target</parameter></methodparam> + <methodparam choice='opt'><type>array</type><parameter>properties</parameter></methodparam> </methodsynopsis> </classsynopsis> </refsect1> @@ -36,26 +36,33 @@ <term><parameter>properties</parameter></term> <listitem> <para> - An optional associative array of properties describing other parameters to control the peek operation. + An optional associative array of properties describing other + parameters to control the peek operation. <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Property name</entry> - <entry>Possible values</entry> - </row> - </thead> - <tbody> - <row> - <entry>SAM_CORRELID</entry> - <entry>This is the target correlation id string of messages to be peeked. This would typically have been returned by a "send" request.</entry> - </row> - <row> - <entry>SAM_MESSAGEID</entry> - <entry>This is the message id string of a message which is to be peeked.</entry> - </row> - </tbody> - </tgroup> + <tgroup cols="2"> + <thead> + <row> + <entry>Property name</entry> + <entry>Possible values</entry> + </row> + </thead> + <tbody> + <row> + <entry>SAM_CORRELID</entry> + <entry> + This is the target correlation id string of messages to be + peeked. This would typically have been returned by a "send" + request. + </entry> + </row> + <row> + <entry>SAM_MESSAGEID</entry> + <entry> + This is the message id string of a message which is to be peeked. + </entry> + </row> + </tbody> + </tgroup> </informaltable> </para> </listitem> @@ -67,7 +74,8 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> - This method returns an array of SAMMessage objects or &false; if an error occurs. + This method returns an array of SAMMessage objects or &false; if an error + occurs. </para> </refsect1> @@ -79,16 +87,14 @@ <programlisting role="php"> <![CDATA[ <?php - $msgArray = $conn->peekAll('queue://receive/test'); - if ($msgArray) { - - foreach ( $msgArray as $key => $msg) { - echo "Message $key: body = $msg->body\n"; - } - } - else - echo "PeekAll failed ($conn->errno) $conn->error"; +$msgArray = $conn->peekAll('queue://receive/test'); +if ($msgArray) { + foreach ( $msgArray as $key => $msg) { + echo "Message $key: body = $msg->body\n"; } +} else { + echo "PeekAll failed ($conn->errno) $conn->error"; +} ?> ]]> </programlisting> @@ -96,7 +102,9 @@ </para> <para> <example> - <title>Retrieve all messages from a queue with a matching correlation id</title> + <title> + Retrieve all messages from a queue with a matching correlation id + </title> <programlisting role="php"> <![CDATA[ <?php @@ -118,6 +126,16 @@ </example> </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><xref linkend="function.samconnection-peek" /></member> + </simplelist> + </para> + </refsect1> + </refentry>  -<refentry id='function.SAM-Connection-receive'> + +<refentry id='function.samconnection-receive'> <refnamediv> - <refname>SAMConnection::receive()</refname> + <refname>SAMConnection->receive()</refname> <refpurpose> Receive a message from a queue or subscription. </refpurpose> @@ -14,8 +14,8 @@ <ooclass><classname>SAMConnection</classname></ooclass> <methodsynopsis> <type>SAMMessage</type><methodname>receive</methodname> - <methodparam><type>string</type><parameter>target</parameter></methodparam> - <methodparam choice='opt'><type>array</type><parameter>properties</parameter></methodparam> + <methodparam><type>string</type><parameter>target</parameter></methodparam> + <methodparam choice='opt'><type>array</type><parameter>properties</parameter></methodparam> </methodsynopsis> </classsynopsis> </refsect1> @@ -28,7 +28,8 @@ <term><parameter>target</parameter></term> <listitem> <para> - The identity of the queue, topic or subscription from which to receive the message. + The identity of the queue, topic or subscription from which to receive + the message. </para> </listitem> </varlistentry> @@ -36,34 +37,44 @@ <term><parameter>properties</parameter></term> <listitem> <para> - An optional associative array of properties describing other parameters to control the receive operation. + 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_CORRELID</entry> - <entry>Used to request selection of the message to receive based upon the correlation id string of the message.</entry> - </row> - <row> - <entry>SAM_MESSAGEID</entry> - <entry>Used to request selection of the message to receive based upon the message id string of the message.</entry> - </row> - <row> - <entry>SAM_WAIT</entry> - <entry> - Timeout value in milliseconds to control how long the request should block waiting to receive a message before returning with a failure - if no message is available on the queue or topic. The default value is 0 meaning wait indefinitely and should be used with caution - as the request may wait until the overall PHP script processing time limit has expired if no message becomes available. - </entry> - </row> - </tbody> - </tgroup> + <tgroup cols="2"> + <thead> + <row> + <entry>Property name</entry> + <entry>Possible values</entry> + </row> + </thead> + <tbody> + <row> + <entry>SAM_CORRELID</entry> + <entry> + Used to request selection of the message to receive based upon + the correlation id string of the message. + </entry> + </row> + <row> + <entry>SAM_MESSAGEID</entry> + <entry> + Used to request selection of the message to receive based upon + the message id string of the message. + </entry> + </row> + <row> + <entry>SAM_WAIT</entry> + <entry> + Timeout value in milliseconds to control how long the request + should block waiting to receive a message before returning with + a failure if no message is available on the queue or topic. The + default value is 0 meaning wait indefinitely and should be used + with caution as the request may wait until the overall PHP script + processing time limit has expired if no message becomes available. + </entry> + </row> + </tbody> + </tgroup> </informaltable> </para> </listitem> @@ -102,7 +113,9 @@ <example> <title>Receiving a message from a queue with options</title> <para> - In this example the SAM_CORRELID option is used to specify a correlation id string to be used to identify the message to receive. A wait timeout of 10 seconds is also specified. + In this example the SAM_CORRELID option is used to specify a correlation + id string to be used to identify the message to receive. A wait timeout + of 10 seconds is also specified. </para> <programlisting role="php"> <![CDATA[ @@ -119,7 +132,7 @@ <example> <title>Receiving a message from a subscription</title> <para> - In this example we show how to receive a message from a subscription id. + In this example we show how to receive a message from a subscription id. </para> <programlisting role="php"> <![CDATA[ @@ -134,11 +147,22 @@ ]]> </programlisting> <para> - Please note that $subscriptionName is a subscription id returned from an earlier subscribe call. + Please note that $subscriptionName is a subscription id returned from an + earlier subscribe call. </para> </example> </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><xref linkend="function.samconnection-send" /></member> + </simplelist> + </para> + </refsect1> + </refentry>  -<refentry id='function.SAM-Connection-remove'> + +<refentry id='function.samconnection-remove'> <refnamediv> - <refname>SAMConnection::remove()</refname> + <refname>SAMConnection->remove()</refname> <refpurpose> Remove a message from a queue. </refpurpose> @@ -14,10 +14,13 @@ <ooclass><classname>SAMConnection</classname></ooclass> <methodsynopsis> <type>SAMMessage</type><methodname>remove</methodname> - <methodparam><type>string</type><parameter>target</parameter></methodparam> - <methodparam choice='opt'><type>array</type><parameter>properties</parameter></methodparam> + <methodparam><type>string</type><parameter>target</parameter></methodparam> + <methodparam choice='opt'><type>array</type><parameter>properties</parameter></methodparam> </methodsynopsis> </classsynopsis> + <para> + Removes a message from a queue. + </para> </refsect1> <refsect1 role="parameters"> @@ -36,26 +39,33 @@ <term><parameter>properties</parameter></term> <listitem> <para> - An optional associative array of properties describing other parameters to control the remove operation. + An optional associative array of properties describing other + parameters to control the remove operation. <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Property name</entry> - <entry>Possible values</entry> - </row> - </thead> - <tbody> - <row> - <entry>SAM_CORRELID</entry> - <entry>This is the target correlation id string of the message. This would typically have been returned by a "send" request.</entry> - </row> - <row> - <entry>SAM_MESSAGEID</entry> - <entry>This is the message id string of the message which is to be removed.</entry> - </row> - </tbody> - </tgroup> + <tgroup cols="2"> + <thead> + <row> + <entry>Property name</entry> + <entry>Possible values</entry> + </row> + </thead> + <tbody> + <row> + <entry>SAM_CORRELID</entry> + <entry> + This is the target correlation id string of the message. + This would typically have been returned by a "send" request. + </entry> + </row> + <row> + <entry>SAM_MESSAGEID</entry> + <entry> + This is the message id string of the message which is to be + removed. + </entry> + </row> + </tbody> + </tgroup> </informaltable> </para> </listitem> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sam/functions/SAM-Connection-rollback.xml?r1=1.4&r2=1.5&diff_format=u Index: phpdoc/en/reference/sam/functions/SAM-Connection-rollback.xml diff -u phpdoc/en/reference/sam/functions/SAM-Connection-rollback.xml:1.4 phpdoc/en/reference/sam/functions/SAM-Connection-rollback.xml:1.5 --- phpdoc/en/reference/sam/functions/SAM-Connection-rollback.xml:1.4 Mon Dec 18 16:24:16 2006 +++ phpdoc/en/reference/sam/functions/SAM-Connection-rollback.xml Sun Feb 4 04:45:43 2007 @@ -1,8 +1,8 @@ <?xml version="1.0" encoding="iso-8859-1"?> - -<refentry id='function.SAM-Connection-rollback'> + +<refentry id='function.samconnection-rollback'> <refnamediv> - <refname>SAMConnection::rollback()</refname> + <refname>SAMConnection->rollback()</refname> <refpurpose> Cancels (rolls back) an in-flight unit of work. </refpurpose> @@ -16,6 +16,9 @@ <type>bool</type><methodname>rollback</methodname><void/> </methodsynopsis> </classsynopsis> + <para> + Rolls back an in-flight unit of work. + </para> </refsect1> <refsect1 role="returnvalues"> @@ -43,6 +46,16 @@ </example> </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><xref linkend="function.samconnection-commit" /></member> + </simplelist> + </para> + </refsect1> + </refentry>  -<refentry id='function.SAM-Connection-send'> + +<refentry id='function.samconnection-send'> <refnamediv> - <refname>SAMConnection::send()</refname> + <refname>SAMConnection->send()</refname> <refpurpose> Send a message to a queue or publish an item to a topic. </refpurpose> @@ -10,18 +10,21 @@ <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> + <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> + 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"> @@ -32,7 +35,9 @@ <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. + 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> @@ -48,59 +53,74 @@ <term><parameter>properties</parameter></term> <listitem> <para> - An optional associative array of properties describing other parameters to control the receive operation. + 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> + <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 + <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> @@ -109,15 +129,22 @@ </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. + 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 (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> + </note> </refsect1> <refsect1 role="examples"> @@ -176,6 +203,16 @@ </example> </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><xref linkend="function.samconnection-receive" /></member> + </simplelist> + </para> + </refsect1> + </refentry>  -<refentry id='function.SAM-Connection-subscribe'> + +<refentry id='function.samconnection-subscribe'> <refnamediv> - <refname>SAMConnection::subscribe()</refname> + <refname>SAMConnection->subscribe()</refname> <refpurpose> Create a subscription to a specified topic. </refpurpose> @@ -10,16 +10,16 @@ <refsect1 role="description"> &reftitle.description; - <para> - The "subscribe" method is used to create a new subscription to a specified topic. - </para> <classsynopsis> <ooclass><classname>SAMConnection</classname></ooclass> <methodsynopsis> <type>string</type><methodname>subscribe</methodname> - <methodparam><type>string</type><parameter>targetTopic</parameter></methodparam> + <methodparam><type>string</type><parameter>targetTopic</parameter></methodparam> </methodsynopsis> </classsynopsis> + <para> + The "subscribe" method is used to create a new subscription to a specified topic. + </para> </refsect1> <refsect1 role="parameters"> @@ -30,7 +30,7 @@ <term><parameter>targetTopic</parameter></term> <listitem> <para> - The identity of the topic (topic://topicname) to subscribe to. + The identity of the topic (topic://topicname) to subscribe to. </para> </listitem> </varlistentry> @@ -41,7 +41,10 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> - A subscription identifier that can be used in a subsequent receive call as a selector to obtain any topic data or &false; if an error occurred. The subscription identifier should be used in the receive call in place of the simple topic name. + A subscription identifier that can be used in a subsequent receive call as + a selector to obtain any topic data or &false; if an error occurred. The + subscription identifier should be used in the receive call in place of the + simple topic name. </para> </refsect1> @@ -64,6 +67,16 @@ </example> </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><xref linkend="function.samconnection-unsubscribe" /></member> + </simplelist> + </para> + </refsect1> + </refentry>  -<refentry id='function.SAM-Connection-unsubscribe'> + +<refentry id='function.samconnection-unsubscribe'> <refnamediv> - <refname>SAMConnection::unsubscribe()</refname> + <refname>SAMConnection->unsubscribe()</refname> <refpurpose> Cancel a subscription to a specified topic. </refpurpose> @@ -10,17 +10,18 @@ <refsect1 role="description"> &reftitle.description; - <para> - The "unsubscribe" method is used to delete an existing subscription to a specified topic. - </para> <classsynopsis> <ooclass><classname>SAMConnection</classname></ooclass> <methodsynopsis> <type>bool</type><methodname>unsubscribe</methodname> - <methodparam><type>string</type><parameter>subscriptionId</parameter></methodparam> - <methodparam choice='opt'><type>string</type><parameter>targetTopic</parameter></methodparam> + <methodparam><type>string</type><parameter>subscriptionId</parameter></methodparam> + <methodparam choice='opt'><type>string</type><parameter>targetTopic</parameter></methodparam> </methodsynopsis> </classsynopsis> + <para> + The "unsubscribe" method is used to delete an existing subscription to a + specified topic. + </para> </refsect1> <refsect1 role="parameters"> @@ -31,7 +32,8 @@ <term><parameter>subscriptionId</parameter></term> <listitem> <para> - The identifier of an existing subscription as returned by a call to the subscribe method. + The identifier of an existing subscription as returned by a call to + the subscribe method. </para> </listitem> </varlistentry> @@ -55,8 +57,8 @@ <![CDATA[ <?php if (!$conn->unsubscribe($subid)) { - // The unsubscribe failed! - echo "Unsubscribe failed ($conn->errno) $conn->error"; + // The unsubscribe failed! + echo "Unsubscribe failed ($conn->errno) $conn->error"; } ?> ]]> @@ -64,6 +66,16 @@ </example> </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><xref linkend="function.samconnection-subscribe" /></member> + </simplelist> + </para> + </refsect1> + </refentry>  -<refentry id='function.SAM-Message-body'> + +<refentry id='function.sammessage-body'> <refnamediv> - <refname>SAMMessage::body</refname> + <refname>SAMMessage->body</refname> <refpurpose> The body of the message. </refpurpose> </refnamediv> <refsect1 role="description"> &reftitle.description; + <classsynopsis> + <ooclass><classname>SAMMessage</classname></ooclass> + <fieldsynopsis><type>string</type><varname>nody</varname></fieldsynopsis> + </classsynopsis> <para> - The "body" property contains the actual body of the message. It may not always be set. + The "body" property contains the actual body of the message. + It may not always be set. </para> </refsect1> @@ -31,6 +36,16 @@ </example> </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><xref linkend="function.sammessage-header" /></member> + </simplelist> + </para> + </refsect1> + </refentry>  -<refentry id='function.SAM-Message-constructor'> + +<refentry id='function.sammessage-constructor'> <refnamediv> - <refname>SAMMessage::SAMMessage()</refname> + <refname>SAMMessage->__construct()</refname> <refpurpose> Creates a new Message object </refpurpose> @@ -12,8 +12,8 @@ <classsynopsis> <ooclass><classname>SAMMessage</classname></ooclass> <constructorsynopsis> - <methodname>SAMMessage</methodname> - <methodparam choice='opt'><type>any</type><parameter>body</parameter></methodparam> + <methodname>__construct</methodname> + <methodparam choice="opt"><type>mixed</type><parameter>body</parameter></methodparam> </constructorsynopsis> </classsynopsis> <para> @@ -68,6 +68,7 @@ </example> </para> </refsect1> + </refentry>  -<refentry id='function.SAM-Message-header'> + +<refentry id='function.sammessage-header'> <refnamediv> - <refname>SAMMessage::header</refname> + <refname>SAMMessage->header</refname> <refpurpose> The header properties of the message. </refpurpose> </refnamediv> <refsect1 role="description"> &reftitle.description; + <classsynopsis> + <ooclass><classname>SAMMessage</classname></ooclass> + <fieldsynopsis><type>object</type><varname>header</varname></fieldsynopsis> + </classsynopsis> <para> - The "header" property is a container for any system or user properties that area associated with the message. - Properties may be assigned by the sender of a message to control the way the messaging systems handles it or - may be assigned by the messaging system itself to tell the recipient extra information about the message or - the way in which it has been handled. + The <literal>header</literal> property is a container for any system or + user properties that area associated with the message. </para> <para> - Some properties are understood by SAM in which case constants have been defined for them. The majority of properties - however are ignored by the SAM implementation and simply passed through to the underlying messaging systems allowing - the application to use messaging specific property names or to define its own "user" properties. + Properties may be assigned by the sender of a message to control the way + the messaging systems handles it or may be assigned by the messaging + system itself to tell the recipient extra information about the message or + the way in which it has been handled. </para> <para> - The SAM defined properties are as follows: - <informaltable> + Some properties are understood by SAM in which case constants have been + defined for them. The majority of properties however are ignored by the + SAM implementation and simply passed through to the underlying messaging + systems allowing the application to use messaging specific property names + or to define its own "user" properties. + </para> + <para> + The SAM defined properties are as follows: + <informaltable> <tgroup cols="2"> - <thead> - <row> - <entry>Property name</entry> - <entry>Possible values</entry> - </row> - </thead> - <tbody> - <row> - <entry>SAM_MESSAGEID</entry> - <entry> - When a message is received this field contains the unique identifier of the message as allocated - by the underlying messaging system. When sending a message this field is ignored. - </entry> - </row> - <row> - <entry>SAM_REPLY_TO</entry> - <entry> - A string providing the identity of the queue on to which responses to this message should be posted. - </entry> - </row> - <row> - <entry>SAM_TYPE</entry> - <entry> - <para> - An indication of the type of message to be sent. The value may be SAM_TEXT indicating the contents of - the message body is a text string, or SAM_BYTES indicating the contents of the message body are some - application defined format. - </para> - <para> - The way in which this property is used may depend on the underlying messaging server. For instance - a messaging server that supports the JMS (Java Message Service) specification may interpret this value - and send messages of type "jms_text" and "jms_bytes". In addition, if the SAM_TYPE property is set to - SAM_TEXT the data provided for the message body is expected to be a UTF8 encoded string. - </para> - </entry> - </row> - </tbody> + <thead> + <row> + <entry>Property name</entry> + <entry>Possible values</entry> + </row> + </thead> + <tbody> + <row> + <entry>SAM_MESSAGEID</entry> + <entry> + When a message is received this field contains the unique + identifier of the message as allocated by the underlying + messaging system. When sending a message this field is ignored. + </entry> + </row> + <row> + <entry>SAM_REPLY_TO</entry> + <entry> + A string providing the identity of the queue on to which + responses to this message should be posted. + </entry> + </row> + <row> + <entry>SAM_TYPE</entry> + <entry> + <para> + An indication of the type of message to be sent. The value may be + <constant>SAM_TEXT</constant> indicating the contents of the + message body is a text string, or <constant>SAM_BYTES</constant> + indicating the contents of the message body are some application + defined format. + </para> + <para> + The way in which this property is used may depend on the underlying + messaging server. For instance a messaging server that supports the + JMS (Java Message Service) specification may interpret this value and + send messages of type "jms_text" and "jms_bytes". In addition, if + the SAM_TYPE property is set to <constant>SAM_TEXT</constant> the + data provided for the message body is expected to be a UTF8 encoded + string. + </para> + </entry> + </row> + </tbody> </tgroup> - </informaltable> + </informaltable> </para> <para> - When setting the values of properties it is often useful to give a hint as to the format in which the property - should be delivered to the messaging system. By default property values are delivered as text and the + When setting the values of properties it is often useful to give a hint as + to the format in which the property should be delivered to the messaging + system. By default property values are delivered as text and the following simple syntax may be used to set a value: </para> <para> @@ -75,17 +93,18 @@ <programlisting role="php"> <![CDATA[ <?php - $msg = new SAMMessage(); +$msg = new SAMMessage(); - $msg->header->myPropertyName = 'textData'; +$msg->header->myPropertyName = 'textData'; ?> ]]> </programlisting> </example> </para> <para> - If it is desired to pass type information an alternative syntax may be used where the value and the - type hint are passed in an associative array: + If it is desired to pass type information an alternative syntax may be + used where the value and the type hint are passed in an associative + array: </para> <para> <example> @@ -93,88 +112,99 @@ <programlisting role="php"> <![CDATA[ <?php - $msg = new SAMMessage(); +$msg = new SAMMessage(); - $msg->header->myPropertyName = array('textData', SAM_STRING); +$msg->header->myPropertyName = array('textData', SAM_STRING); ?> ]]> </programlisting> </example> </para> <para> - When passing a type hint the type entry should be one of the SAM defined constant values as defined by the - following table: - <informaltable> + When passing a type hint the type entry should be one of the SAM defined + constant values as defined by the following table: + <informaltable> <tgroup cols="2"> - <thead> - <row> - <entry>Constant</entry> - <entry>Type description</entry> - </row> - </thead> - <tbody> - <row> - <entry>SAM_BOOLEAN</entry> - <entry> - Any value passed will be interpreted as logical true or false. If the value cannot be interpreted - as a PHP boolean value the value passed to the messaging system is undefined. - </entry> - </row> - <row> - <entry>SAM_BYTE</entry> - <entry> - An 8-bit signed integer value. SAM will attempt to convert the property value specified into a - single byte value to pass to the messaging system. If a string value is passed an attempt will - be made to interpret the string as a numeric value. If the numeric value cannot be expressed as - an 8-bit signed binary value data may be lost in the conversion. - </entry> - </row> - <row> - <entry>SAM_DOUBLE</entry> - <entry> - A long floating point value. SAM will attempt to convert the property value specified into a - floating point value with 15 digits of precision. If a string value is passed an attempt will - be made to interpret the string as a numeric value. If the passed value cannot be expressed as - a 15 digit floating point value data may be lost in the conversion. - </entry> - </row> - <row> - <entry>SAM_FLOAT</entry> - <entry> - A short floating point value. SAM will attempt to convert the property value specified into a - floating point value with 7 digits of precision. If a string value is passed an attempt will - be made to interpret the string as a numeric value. If the passed value cannot be expressed as - a 7 digit floating point value data may be lost in the conversion. - </entry> - </row> - <row> - <entry>SAM_INT</entry> - <entry> - An 32-bit signed integer value. SAM will attempt to convert the property value specified into a - 32-bit value to pass to the messaging system. If a string value is passed an attempt will - be made to interpret the string as a numeric value. If the numeric value cannot be expressed as - an 32-bit signed binary value data may be lost in the conversion. - </entry> - </row> - <row> - <entry>SAM_LONG</entry> - <entry> - An 64-bit signed integer value. SAM will attempt to convert the property value specified into a - 64-bit value to pass to the messaging system. If a string value is passed an attempt will - be made to interpret the string as a numeric value. If the numeric value cannot be expressed as - an 64-bit signed binary value data may be lost in the conversion. - </entry> - </row> - <row> - <entry>SAM_STRING</entry> - <entry> - SAM will interpret the property value specified as a string and pass it to the messaging system - accordingly. - </entry> - </row> - </tbody> + <thead> + <row> + <entry>Constant</entry> + <entry>Type description</entry> + </row> + </thead> + <tbody> + <row> + <entry>SAM_BOOLEAN</entry> + <entry> + Any value passed will be interpreted as logical true or false. + If the value cannot be interpreted as a PHP boolean value the value + passed to the messaging system is undefined. + </entry> + </row> + <row> + <entry>SAM_BYTE</entry> + <entry> + An 8-bit signed integer value. SAM will attempt to convert the + property value specified into a single byte value to pass to the + messaging system. If a string value is passed an attempt will be + made to interpret the string as a numeric value. If the numeric + value cannot be expressed as an 8-bit signed binary value data may + be lost in the conversion. + </entry> + </row> + <row> + <entry>SAM_DOUBLE</entry> + <entry> + A long floating point value. SAM will attempt to convert the + property value specified into a floating point value with 15 digits + of precision. If a string value is passed an attempt will be made to + interpret the string as a numeric value. If the passed value cannot + be expressed as a 15 digit floating point value data may be lost in + the conversion. + </entry> + </row> + <row> + <entry>SAM_FLOAT</entry> + <entry> + A short floating point value. SAM will attempt to convert the + property value specified into a floating point value with 7 digits of + precision. If a string value is passed an attempt will be made to + interpret the string as a numeric value. If the passed value cannot + be expressed as a 7 digit floating point value data may be lost in + the conversion. + </entry> + </row> + <row> + <entry>SAM_INT</entry> + <entry> + An 32-bit signed integer value. SAM will attempt to convert the + property value specified into a 32-bit value to pass to the messaging + system. If a string value is passed an attempt will be made to + interpret the string as a numeric value. If the numeric value cannot + be expressed as an 32-bit signed binary value data may be lost in the + conversion. + </entry> + </row> + <row> + <entry>SAM_LONG</entry> + <entry> + An 64-bit signed integer value. SAM will attempt to convert the + property value specified into a 64-bit value to pass to the messaging + system. If a string value is passed an attempt will be made to + interpret the string as a numeric value. If the numeric value cannot + be expressed as an 64-bit signed binary value data may be lost in the + conversion. + </entry> + </row> + <row> + <entry>SAM_STRING</entry> + <entry> + SAM will interpret the property value specified as a string and pass + it to the messaging system accordingly. + </entry> + </row> + </tbody> </tgroup> - </informaltable> + </informaltable> </para> </refsect1> @@ -186,28 +216,28 @@ <programlisting role="php"> <![CDATA[ <?php - $msg = new SAMMessage('This is a test message'); +$msg = new SAMMessage('This is a test message'); - // defining SAM specific properties... - $msg->header->SAM_REPLY_TO = 'queue://test/replyQueue'; +// defining SAM specific properties... +$msg->header->SAM_REPLY_TO = 'queue://test/replyQueue'; - // defining arbitrary properties... - // - // a default string property - $msg->header->myStringProp1 = 'a string property'; - // a string property with a type hint - $msg->header->myStringProp2 = array('another string property', SAM_STRING); - - // a boolean property - $msg->header->myBoolProp = array(FALSE, SAM_BOOL); - - // numeric format properties - $msg->header->myIntProp = array(32768, SAM_INT); - $msg->header->myLongProp = array(9876543, SAM_LONG); - $msg->header->myByteProp1 = array(123, SAM_BYTE); - $msg->header->myByteProp2 = array('12', SAM_BYTE); - $msg->header->myFloatProp = array(3.141592, SAM_FLOAT); - $msg->header->myDoubleProp = array(3.14159265358979, SAM_DOUBLE); +// defining arbitrary properties... +// +// a default string property +$msg->header->myStringProp1 = 'a string property'; +// a string property with a type hint +$msg->header->myStringProp2 = array('another string property', SAM_STRING); + +// a boolean property +$msg->header->myBoolProp = array(FALSE, SAM_BOOL); + +// numeric format properties +$msg->header->myIntProp = array(32768, SAM_INT); +$msg->header->myLongProp = array(9876543, SAM_LONG); +$msg->header->myByteProp1 = array(123, SAM_BYTE); +$msg->header->myByteProp2 = array('12', SAM_BYTE); +$msg->header->myFloatProp = array(3.141592, SAM_FLOAT); +$msg->header->myDoubleProp = array(3.14159265358979, SAM_DOUBLE); ?> ]]> </programlisting> @@ -220,11 +250,11 @@ <![CDATA[ <?php - // accessing an application specific property - $intProp = $msg->header->'MyIntProp'; +// accessing an application specific property +$intProp = $msg->header->'MyIntProp'; - // accessing a messaging system specific property - $encoding = $msg->header->'JMS_IBM_Msgtype'; +// accessing a messaging system specific property +$encoding = $msg->header->'JMS_IBM_Msgtype'; ?> ]]> @@ -233,6 +263,15 @@ </para> </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><xref linkend="function.sammessage-body" /></member> + </simplelist> + </para> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file