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 @@
-
+
+
+ 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";
+ }
+
+?>
+ ]]>
+
+
+
+