diff --git a/reference/sam/constants.xml b/reference/sam/constants.xml index ab892a6582..b5864b47f2 100644 --- a/reference/sam/constants.xml +++ b/reference/sam/constants.xml @@ -1,5 +1,5 @@ - +
&reftitle.constants; &extension.constants; @@ -356,6 +356,19 @@ + + + SAM_WMQ_TARGET_CLIENT + (string) + + + + 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. + + + SAM_WPM diff --git a/reference/sam/functions/SAM-Connection-commit.xml b/reference/sam/functions/SAM-Connection-commit.xml index 74c99c6286..6d22dbd4d7 100644 --- a/reference/sam/functions/SAM-Connection-commit.xml +++ b/reference/sam/functions/SAM-Connection-commit.xml @@ -1,5 +1,5 @@ - + SAMConnection::commit() diff --git a/reference/sam/functions/SAM-Connection-connect.xml b/reference/sam/functions/SAM-Connection-connect.xml index 12b0381f52..b273c5ce6a 100644 --- a/reference/sam/functions/SAM-Connection-connect.xml +++ b/reference/sam/functions/SAM-Connection-connect.xml @@ -1,5 +1,5 @@ - + SAMConnection::connect() @@ -195,6 +195,13 @@ + + SAM_WPM_DUR_SUB_HOME + none + + The name of the messaging engine where durable subscriptions are managed. (WPM ONLY). + + diff --git a/reference/sam/functions/SAM-Connection-constructor.xml b/reference/sam/functions/SAM-Connection-constructor.xml index 20c21eac3d..08c784c5b2 100644 --- a/reference/sam/functions/SAM-Connection-constructor.xml +++ b/reference/sam/functions/SAM-Connection-constructor.xml @@ -1,5 +1,5 @@ - + SAMConnection::SAMConnection() diff --git a/reference/sam/functions/SAM-Connection-disconnect.xml b/reference/sam/functions/SAM-Connection-disconnect.xml index e28aa50ee0..7b89a895cb 100644 --- a/reference/sam/functions/SAM-Connection-disconnect.xml +++ b/reference/sam/functions/SAM-Connection-disconnect.xml @@ -1,5 +1,5 @@ - + SAMConnection::disconnect() diff --git a/reference/sam/functions/SAM-Connection-errno.xml b/reference/sam/functions/SAM-Connection-errno.xml index 3c97bac038..24387b8582 100644 --- a/reference/sam/functions/SAM-Connection-errno.xml +++ b/reference/sam/functions/SAM-Connection-errno.xml @@ -1,5 +1,5 @@ - + SAMConnection->errno diff --git a/reference/sam/functions/SAM-Connection-error.xml b/reference/sam/functions/SAM-Connection-error.xml index c56e6e8eb1..91e72820c9 100644 --- a/reference/sam/functions/SAM-Connection-error.xml +++ b/reference/sam/functions/SAM-Connection-error.xml @@ -1,5 +1,5 @@ - + SAMConnection->error diff --git a/reference/sam/functions/SAM-Connection-isConnected.xml b/reference/sam/functions/SAM-Connection-isConnected.xml index f40cf38973..7a39383f52 100644 --- a/reference/sam/functions/SAM-Connection-isConnected.xml +++ b/reference/sam/functions/SAM-Connection-isConnected.xml @@ -1,5 +1,5 @@ - + SAMConnection::isConnected() diff --git a/reference/sam/functions/SAM-Connection-peek.xml b/reference/sam/functions/SAM-Connection-peek.xml index 609508f403..3ff2574740 100644 --- a/reference/sam/functions/SAM-Connection-peek.xml +++ b/reference/sam/functions/SAM-Connection-peek.xml @@ -1,5 +1,5 @@ - + SAMConnection::peek() diff --git a/reference/sam/functions/SAM-Connection-peekall.xml b/reference/sam/functions/SAM-Connection-peekall.xml index 894715c2a5..531a099d3a 100644 --- a/reference/sam/functions/SAM-Connection-peekall.xml +++ b/reference/sam/functions/SAM-Connection-peekall.xml @@ -1,5 +1,5 @@ - + SAMConnection::peekAll() diff --git a/reference/sam/functions/SAM-Connection-receive.xml b/reference/sam/functions/SAM-Connection-receive.xml index ddaa91530d..adc0e60e1e 100644 --- a/reference/sam/functions/SAM-Connection-receive.xml +++ b/reference/sam/functions/SAM-Connection-receive.xml @@ -1,5 +1,5 @@ - + SAMConnection::receive() @@ -28,7 +28,7 @@ target - The identity of the queue from which to receive the message. + The identity of the queue, topic or subscription from which to receive the message. @@ -115,6 +115,29 @@ $msg = $conn->receive('queue://receive/test', array(SAM_SELECT => $token, SAM_WA + + + Receiving a message from a subscription + + In this example we show how to receive a message from a subscription id. + + +receive($subscriptionName); + +if (!$msg) { + // The receive failed! + echo "Receive failed ($conn->errno) $conn->error"; +} +?> +]]> + + + Please note that $subscriptionName is a subscription id returned from an earlier subscribe call. + + + diff --git a/reference/sam/functions/SAM-Connection-remove.xml b/reference/sam/functions/SAM-Connection-remove.xml index 8bfc757508..78f7dfbc77 100644 --- a/reference/sam/functions/SAM-Connection-remove.xml +++ b/reference/sam/functions/SAM-Connection-remove.xml @@ -1,5 +1,5 @@ - + SAMConnection::remove() diff --git a/reference/sam/functions/SAM-Connection-rollback.xml b/reference/sam/functions/SAM-Connection-rollback.xml index 157b7a0488..a76e29a3e3 100644 --- a/reference/sam/functions/SAM-Connection-rollback.xml +++ b/reference/sam/functions/SAM-Connection-rollback.xml @@ -1,5 +1,5 @@ - + SAMConnection::rollback() diff --git a/reference/sam/functions/SAM-Connection-send.xml b/reference/sam/functions/SAM-Connection-send.xml index dbc3d831b9..022178fe33 100644 --- a/reference/sam/functions/SAM-Connection-send.xml +++ b/reference/sam/functions/SAM-Connection-send.xml @@ -1,5 +1,5 @@ - + SAMConnection::send() @@ -91,6 +91,14 @@ discarding it. The default value is 0 indicating the message should be retained indefinitely. + + SAM_WMQ_TARGET_CLIENT + + 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. + + diff --git a/reference/sam/functions/SAM-Connection-subscribe.xml b/reference/sam/functions/SAM-Connection-subscribe.xml index ebd3a60e67..740b6f8674 100644 --- a/reference/sam/functions/SAM-Connection-subscribe.xml +++ b/reference/sam/functions/SAM-Connection-subscribe.xml @@ -1,17 +1,17 @@ - + SAMConnection::subscribe() - Create a subscription to one or more topics. + Create a subscription to a specified topic. &reftitle.description; - The "subscribe" method is used to create a new subscription to one or more topics. + The "subscribe" method is used to create a new subscription to a specified topic. SAMConnection @@ -20,9 +20,6 @@ stringtargetTopic - - Warning: This method is not currently implemented. - @@ -44,7 +41,7 @@ &reftitle.returnvalues; - 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. + 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. @@ -52,7 +49,7 @@ &reftitle.examples; - Subscribe to a single topic + Subscribe to a topic - + SAMConnection::unsubscribe() - Cancel a subscription to one or more topics. + Cancel a subscription to a specified topic. &reftitle.description; - The "unsubscribe" method is used to delete an existing subscription to one or more topics. + The "unsubscribe" method is used to delete an existing subscription to a specified topic. SAMConnection @@ -21,9 +21,6 @@ stringtargetTopic - - Warning: This method is not currently implemented. - @@ -38,16 +35,6 @@ - - targetTopic - - - An optional topic identifier of the topic for which the subscription is to be cancelled. - If this value is not specified the subscription will be cancelled for all topics currently - subscribed to. - - - @@ -63,11 +50,11 @@ &reftitle.examples; - Unsubscribe from a single topic + Delete a subscription unsubscribe($subid, 'topic://A')) { +if (!$conn->unsubscribe($subid)) { // The unsubscribe failed! echo "Unsubscribe failed ($conn->errno) $conn->error"; } diff --git a/reference/sam/functions/SAM-Message-body.xml b/reference/sam/functions/SAM-Message-body.xml index 8d8438cddb..afcf671f1b 100644 --- a/reference/sam/functions/SAM-Message-body.xml +++ b/reference/sam/functions/SAM-Message-body.xml @@ -1,5 +1,5 @@ - + SAMMessage::body diff --git a/reference/sam/functions/SAM-Message-constructor.xml b/reference/sam/functions/SAM-Message-constructor.xml index 228fe3ff15..6f36899354 100644 --- a/reference/sam/functions/SAM-Message-constructor.xml +++ b/reference/sam/functions/SAM-Message-constructor.xml @@ -1,5 +1,5 @@ - + SAMMessage::SAMMessage() diff --git a/reference/sam/functions/SAM-Message-header.xml b/reference/sam/functions/SAM-Message-header.xml index c2ddb50ac2..07881186e2 100644 --- a/reference/sam/functions/SAM-Message-header.xml +++ b/reference/sam/functions/SAM-Message-header.xml @@ -1,5 +1,5 @@ - + SAMMessage::header diff --git a/reference/sam/reference.xml b/reference/sam/reference.xml index b86a4c0673..a8398b93cd 100644 --- a/reference/sam/reference.xml +++ b/reference/sam/reference.xml @@ -1,5 +1,5 @@ - + SAM - Simple Asynchronous Messaging SAM @@ -361,7 +361,110 @@ by using the freely distributable runtime package
+
+ Publish/Subscribe and suscriptions to topics + + 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. + + + 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. + + + 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. + + + + Creating a durable subscription to a topic + + subscribe('topic://A'); + + if (!$subName) { + echo "Subscribe failed"; + } else { + # Subscribe was OK + ... + } +?> + ]]> + + + + + + Subscribing to a topic using a WebSphere Platform Messaging (WPM) server + + 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 + ... + } +?> + ]]> + + + + + + Receiving published data using a durable subscription + + receive($subName); + if ($msg) { + echo "Received a message OK"; + } else { + echo "The receive failed"; + } + +?> + ]]> + + + + + + Deleting a durable subscription to a topic + + unsubscribe($subName)) { + echo "Unsubscribe failed"; + } + +?> + ]]> + + + +
Error handling