&reftitle.examples;
Connections
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.
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.
Creating a connection and connecting to a remote WebSphere MQSeries Messaging Server
connect(SAM_WMQ, array(SAM_HOST => 'myhost.mycompany.com',
SAM_PORT => 1506,
SAM_BROKER => 'mybroker'));
?>
]]>
Creating a connection and connecting to a remote WebSphere Application Server
connect(SAM_WPM, array(SAM_ENDPOINTS => 'localhost:7278:BootstrapBasicMessaging',
SAM_BUS => 'Bus1',
SAM_TARGETCHAIN => 'InboundBasicMessaging'));
?>
]]>
Creating a connection and connecting to an MQTT server
connect(SAM_MQTT, array(SAM_HOST => 'myhost.mycompany.com',
SAM_PORT => 1883));
?>
]]>
Messages
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.
Creating a message with a simple text body
]]>
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:
Setting a text format property using the default syntax
header->myPropertyName = 'textData';
?>
]]>
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:
Setting a property using a type hint
header->myPropertyName = array(3.14159, SAM_FLOAT);
?>
]]>
Properties may also be extracted from the header of a message.
Retrieving a property from a message header
header->myPropertyName;
?>
]]>
Messaging operations
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.
Adding a message to a queue and receiving a response
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));
}
?>
]]>
Publish/Subscribe and subscriptions to topics
SAM allows messages to be sent either to queues or, for WebSphere MQ
and WPM, to publish/subscribe topics.
A topic destination 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
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.
Handling an error from a method that returns no result
commit()) {
// The commit failed!
echo "Commit failed ($conn->errno) $conn->error";
}
?>
]]>
Handling an error from a method that returns a result
send('queue://send/test', $msg);
if (!$correlid) {
// The Send failed!
echo "Send failed ($conn->errno) $conn->error";
} else {
/* ... */
}
?>
]]>