( ! ) Warning: Creating default object from empty value in /var/www/clients/client1/web1/web/modules/Forums/common.php on line 421
Call Stack
#TimeMemoryFunctionLocation
10.0000358432{main}( ).../modules.php:0
20.0005369376include( '/var/www/clients/client1/web1/web/index.php ).../modules.php:4
31.0153675912include( '/var/www/clients/client1/web1/web/modules/PHP_Manual/index.php ).../index.php:179
41.0157676808include( '/var/www/clients/client1/web1/web/header.php ).../index.php:157
51.0157693408head( ).../header.php:112
61.0157693992online( ).../header.php:39
71.0158693992my_online( ).../mainfile.php:720
81.0158697168include( '/var/www/clients/client1/web1/web/modules/Forums/common.php ).../custom_mainfile.php:1151
Omega13a's Corner - PHP Manual - Reference - Sam
Omega13a's Corner
Contribute To This Site
Submit a Download
Submit a Link
Submit A Review for Omega13a's Corner

This Website Is Best Viewed In Mozilla Firefox 0.9+
You Are Currently Using
  Login or Register
::  Home   ::  Your Account   ::  Forums   ::  UFT Encyclopedia   ::  UFT Writer  ::
2020.81
Omega13a's Wish List
My Amazon.com Wish List
 
Affiliates
Supported by

[ Be A Supporter ]
[ NukeSupporters( tm) ]
 
Navigation
· Hom e
· Rep ort An Error

Omega13a's Corner

· Ome ga13a's Corner Index
· Ana grams
· Ana grams
· Aut ograms
· Aut ograms
· Bum per Stickers
· Bum per Stickers
· Cow Analogies
· Cow Analogies
· Cru el Baby Names
· Cru el Baby Names
· DHT ML Tricks
· DHT ML Tricks
· Dum b Criminals
· Dum b Criminals
· Dum b Headlines
· Dum b Headlines
· Dum b Laws
· Dum b Laws
· Dum b Questions
· Dum b Questions
· Dum b Quotes
· Dum b Quotes
· Dum b Signs
· Dum b Signs
· Dum b Warning Labels
· Dum b Warning Labels
· Eye witness Reports
· Eye witness Reports
· Fea rs
· Fea rs
· Gam es
· Gam es
· Goo gle Searches
· Goo gle Searches
· Gra phing Calculator
· Gra phing Calculator
· Hor oscope
· Hor oscope
· hta ccess Tutorials
· hta ccess Tutorials
· HTM L Manual
· HTM L Manual
· IP Lookup
· IP Lookup
· Jok es
· Jok es
· Mis c Funny Stuff
· Mis c Funny Stuff
· Odd Books
· Odd Books
· Odd Place Names
· Odd Place Names
· Odd Product Names
· Odd Product Names
· Our Solar System
· Our Solar System
· Pal indromes
· Pal indromes
· Pan grams
· Pan grams
· PEA R Manual
· PEA R Manual
· PHP Manual
· PHP Manual
· PHP Nuke Tools
· PHP Nuke Tools
· Poi ntless Quizzes
· Poi ntless Quizzes
· Pri me Numbers
· Pri me Numbers
· Ran dom Quotes
· Ran dom Quotes
· Ran t
· Ran t
· Rev iews
· Rev iews
· Rhy ming Pairs
· Rhy ming Pairs
· Sci -Fi/Fantasy Encyclopedia
· Sci -Fi/Fantasy Encyclopedia
· Wea ther
· Wea ther
· Wei rd Ads
· Wei rd Ads
· Wei rd Wide Web
· Wei rd Wide Web
· Zen Sarcasms
· Zen Sarcasms

Star Trek

·&nbs pBorg Species Designations
· Bor g Species Designations
· FAQ
· FAQ
· Sev Trek
· Sev Trek
· Sta r Trek Alien Sayings
· Sta r Trek Alien Sayings
· Sta r Trek Eggs
· Sta r Trek Eggs
· Sta r Trek Encyclopedia
· Sta r Trek Encyclopedia
· Sta r Trek Episode Guides
· Sta r Trek Episode Guides
· Sta r Trek Goofs
· Sta r Trek Goofs
· Sta r Trek Mysteries
· Sta r Trek Mysteries
· Sta r Trek Reviews
· Sta r Trek Reviews
· Sta r Trek Timeline
· Sta r Trek Timeline
· Tre k Today Headlines
· Tre k Today Headlines
· Wor lds in Star Trek
· Wor lds in Star Trek

Community

· Cha t Bot
· Cha t Bot
· Cha t Room
· Cha t Room
· Fee dback
· Fee dback
· For ums
· For ums
· Gue stbook
· Gue stbook
· Joi n a Webring
· Joi n a Webring
· Joi n the Staff
· Joi n the Staff
· Mem bers List
· Mem bers List
· Pri vate Messages
· Pri vate Messages
· Rec ommend Us
· Rec ommend Us
· Rul es/Terms of Use
· Rul es/Terms of Use
· Sur veys
· Sur veys
· Use r Journals
· Use r Journals
· Vot e For Us
· Vot e For Us
· Win An Award
· Win An Award
· You r Account
· You r Account

Media/Arts

· Dow nloads
· Dow nloads
· Fan Fictions
· Fan Fictions
· Han gman
· Han gman
· Ima ge Gallery
· Ima ge Gallery
· Tec hnobable Generator
· Tec hnobable Generator

Staff Personal Sections

· Lad y Lursa's Reading Corner

Links and Webrings

· Ban ner Exchanges
· Ban ner Exchanges
· Joi n Banner Exchange
· Joi n Banner Exchange
· Lin king To Us
· Lin king To Us
· Top sites
· Top sites
· Web Links
· Web Links
· Web rings
· Web rings

Site Info

· Abo ut the Owner
· Abo ut the Site
· Abo ut the Site
· Abo ut UFT_PHP
· Abo ut UFT_PHP
· Abo ut You
· Awa rds
· Awa rds
· Ban ned Stuff
· Ban ned Stuff
· Cop yright
· Cop yright
· Leg al Information
· Leg al Information
· Mod ifications Installed
· Mod ifications Installed
· Sea rch Results
· Sea rch Results
 
UFT Community

Omega13a's Corner Forums

 
Vote For Us
 
Ads


SAM - Simple Asynchronous Messaging

CXXXVI. SAM - Simple Asynchronous Messaging

Introduction

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.

Installation

Prerequisites

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 Introducing XMS - The IBM Message Service API.

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 (MQC6).

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.

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.

Linux installation steps

The sam extension is supplied as a PECL module, which you should be able to download and install in one step as follows:
pear install sam
(Depending on your php environment, you will probably need to be root to do this.)

Make sure that the module is loaded by PHP, by adding following line to php.ini :
extension=sam.so

to your php.ini file.

If you cannot use the PEAR installer, you can download the extension and build it manually:
pear download sam          #downloads sam-<version>.tgz
tar -xzf sam-<version>.tgz
cd sam-<version>
phpize
configure
make
make install               #you may need to be root for this step

To work with the very latest source, you'll need to extract it from cvs and build manually as above.

Windows installation steps

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.

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 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 should have something like:
c:\php_build\-
              |
              |---php_5.0.5--|---build
              |              |---ext
              |              |--- ...
              |
              |---win32build--|---bin
                              |---include
                              |---lib

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.

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.

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)

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.

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:
set PATH=..\win32build\bin;%PATH%

Run the buildconf.bat command. This should rebuild the configure.js file.

Run the cscript command:
cscript /nologo configure.js --with_sam="c:\program files\ibm\xms"

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.

You can specify whatever other cscript parameters you require to include or exclude items from the php build or select options.

Assuming all has gone well so far you can now finally run a make!
nmake php_sam.dll

Additional steps for Visual Studio 2005

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:
mt.exe -manifest php_sam.dll.manifest -outputresource:php_sam.dll;2

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 runtime package.

API Usage

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.

Example 1. Creating a connection and connecting to a remote WebSphere MQSeries Messaging Server

<?php
   $conn
= new SAMConnection();
   
$conn->connect(SAM_WMQ, array(SAM_HOST => myhost.mycompany.com,
                                 
SAM_PORT => 1506,
                                 
SAM_BROKER => mybroker));
?>

Example 2. Creating a connection and connecting to a remote WebSphere Application Server

<?php
   $conn
= new SAMConnection();
   
$conn->connect(SAM_WMQ, array(SAM_ENDPOINTS => 'localhost:7278:BootstrapBasicMessaging',
                                 
SAM_BUS => 'Bus1',
                                 
SAM_TARGETCHAIN => 'InboundBasicMessaging'));
?>

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.

Example 3. Creating a message with a simple text body

<?php
   $msg
= new SAMMessage('This is a simple text message');
?>

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:

Example 4. Setting a text format property using the default syntax

<?php
   $msg
->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:

Example 5. Setting a property using a type hint

<?php
   $msg
->header->myPropertyName = array(3.14159, SAM_FLOAT);
?>

Properties may also be extracted from the header of a message.

Example 6. Retrieving a property from a message header

<?php
   $myProperty
= $msg->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.

Example 7. Adding a message to a queue and receiving a response

<?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));
   }
?>

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.

Example 8. Creating a durable subscription to a topic

<?php

      $subName
= $conn->subscribe('topic://A');

      if (!
$subName) {
         echo
"Subscribe failed";
      } else {
         
# Subscribe was OK
         
...
      }
?>

Example 9. Subscribing to a topic using a WebSphere Platform Messaging (WPM) server

<?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
      
...
   }
?>

Example 10. Receiving published data using a durable subscription

<?php

      $msg
= $conn->receive($subName);
      if (
$msg) {
         echo
"Received a message OK";
      } else {
         echo
"The receive failed";
      }

?>

Example 11. Deleting a durable subscription to a topic

<?php

      
if (!$conn->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.

Example 12. Handling an error from a method that returns no result

<?php
   
if (!$conn->commit()) {
     
// The commit failed!
     
echo "Commit failed ($conn->errno) $conn->error";
   }
?>

Example 13. Handling an error from a method that returns a result

<?php
   $correlid
= $conn->send('queue://send/test', $msg);

   if (!
$correlid) {
     
// The Send failed!
     
echo "Send failed ($conn->errno) $conn->error";
   } else {
     ...
   }
?>

Predefined Classes

SAMConnection

Object representing a connection to a Messaging Server

Constructor

  • new SAMConnection - construct a new connection object to allow connection to a messaging infrastructure.

Methods

  • commit - a method that commits (successfully completes) an in_flight unit of work.

  • connect - a method that connects a PHP script to a messaging server.

  • disconnect - a method that disconnects a PHP script from a messaging server.

  • isConnected - a method that checks whether a PHP script is connected to a messaging server.

  • peek - a method that receives a message from a queue without removing it from the queue.

  • peekAll - a method that receives one or messages from a queue without removing them from the queue.

  • receive - a method that receives a message from a queue or subscription.

  • remove - a method that removes a message from a queue.

  • rollback - a method that cancels (rolls back) an in_flight unit of work.

  • send - a method that sends a message to a queue or posts to a topic

  • subscribe - a method that creates a subscription to one or more topics

  • unsubscribe - a method that destroys a subscription to one or more topics

Properties

  • errno - the numeric error code for the last encountered error on this connection. This property is set to 0 if the last operation was successful.

  • error - the text description for the last encountered error on this connection

SAMMessage

Object representing a message to be sent or received

Constructor

Properties

  • body - the body of the message.

  • header - the header properties of the message.

Predefined Constants

The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.

SAM_AUTO (string)

Automatic behaviour

SAM_BOOLEAN (string)

Type specifier used when setting properties on SAM_Message objects.

SAM_BUS (string)

Connect attribute used to set the name of the enterprise service bus to connect to.

SAM_BYTE (string)

Type specifier used when setting properties on SAM_Message objects.

SAM_BYTES (string)

Message body type descriptor.

SAM_CORRELID (string)

Attribute used on receive, send and remove requests to identify specific messages.

SAM_DELIVERYMODE (string)

Message header property.

SAM_DOUBLE (string)

Type specifier used when setting properties on SAM_Message objects.

SAM_ENDPOINTS (string)

Connect attribute used to define the possible endpoints to connect to.

SAM_FLOAT (string)

Type specifier used when setting properties on SAM_Message objects.

SAM_HOST (string)

Connect attribute used to set the hostname of the required messaging server.

SAM_INT (string)

Type specifier used when setting properties on SAM_Message objects.

SAM_LONG (string)

Type specifier used when setting properties on SAM_Message objects.

SAM_MANUAL (string)

Manual (script controlled) behaviour

SAM_MESSAGEID (string)

Attribute used on receive and remove requests to identify specific messages.

SAM_NON_PERSISTENT (string)

Connect attribute value used to request messages are not made persistent on the messaging server.

SAM_PASSWORD (string)

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.

SAM_PERSISTENT (string)

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.

SAM_PORT (string)

Connect attribute used to set the port number on which to communicate with the messaging server.

SAM_PRIORITY (string)

Option name used on send requests to specify a delivery priority value.

SAM_REPLY_TO (string)

Message propery used to specify the queue identity on to which the script expects response or reply messages to be posted.

SAM_RTT (string)

Connect protocol definition for selecting the IBM Realtime Transport protocol for communication with a business integration messaging server.

SAM_STRING (string)

Type specifier used when setting properties on SAM_Message objects.

SAM_TARGETCHAIN (string)

Connection attribute used to set the required target chain identifier.

SAM_TEXT (string)

Message body type descriptor.

SAM_TIMETOLIVE (string)

Message send option name used to specify the length of time a message should be retained in milliseconds.

SAM_TRANSACTIONS (string)

Connection attribute used to set required transactional behaviour. May be set to SAM_AUTO (default) or SAM_MANUAL.

SAM_USERID (string)

Connect attribute used to define the account to being used to connect to a messaging server that requires authorisation for connections.

SAM_WAIT (string)

Receive property used to specify the wait timeout to be used when receiving a message from a queue or subscription.

SAM_WMQ (string)

Connect protocol definition for selecting the IBM WebSphere MQSeries protocol for communication with the desired messaging server.

SAM_WMQ_BINDINGS (string)

Connect protocol definition for selecting the IBM WebSphere MQSeries protocol for communication with a local messaging server.

SAM_WMQ_CLIENT (string)

Connect protocol definition for selecting the IBM WebSphere MQSeries protocol for communication with a remote messaging server.

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 (string)

Connect protocol definition for selecting the IBM WebSphere Platform Messaging protocol for communication with a WebSphere Application Server messaging server.

Table of Contents
SAMConnection::commit() --  Commits (completes) the current unit of work.
SAMConnection::connect() --  Establishes a connection to a Messaging Server
SAMConnection::SAMConnection() --  Creates a new connection to a Messaging Server
SAMConnection::disconnect() --  Disconnects from a Messaging Server
SAMConnection->errno -- Contains the unique numeric error code of the last executed SAM operation.
SAMConnection->error -- Contains the text description of the last failed SAM operation.
SAMConnection::isConnected() --  Queries whether a connection is established to a Messaging Server
SAMConnection::peek() --  Read a message from a queue without removing it from the queue.
SAMConnection::peekAll() --  Read one or more messages from a queue without removing it from the queue.
SAMConnection::receive() --  Receive a message from a queue or subscription.
SAMConnection::remove() --  Remove a message from a queue.
SAMConnection::rollback() --  Cancels (rolls back) an in_flight unit of work.
SAMConnection::send() --  Send a message to a queue or publish an item to a topic.
SAMConnection::subscribe() --  Create a subscription to a specified topic.
SAMConnection::unsubscribe() --  Cancel a subscription to a specified topic.
SAMMessage::body --  The body of the message.
SAMMessage::SAMMessage() --  Creates a new Message object
SAMMessage::header --  The header properties of the message.

Total Hits: 0

Powered by PHPNukePage Protected By Copyscape. Do Not CopyNukeSentinel ProtectedPowered by PEARPowered by PECL

© 2000, 2001, 2002 Trek Archive, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020 United Federation of Trek.
Omega's Corner is © 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020 omega13a.
Star Trek®, Star Trek: The Next Generation®, Star Trek: Deep Space Nine®, Star Trek: Voyager®, Enterprise®, and Star Trek: Enterprise® are registered trademarks of Paramount Pictures and Viacom. All Star Trek material found on this site is for promotional purposes only, and not personal or financial gain. No infringements on their copyrights is intended.
All logos and trademarks in this site are property of their respective owners. The comments are property of their posters.


ROR Sitemap Google Sitemap

PHP-Nuke Copyright © 2005 by Francisco Burzi. This is free software, and you may redistribute it under the GPL. PHP-Nuke comes with absolutely no warranty, for details, see the license.
Page Generation: 1.3519 Seconds
Server Load: 0.98
Queries: 24 (0.8492 seconds)
Included 92 files
242 classes defined
46 interfaces defined
0 classes loaded using __autoload()
2,724 functions defined
4,460 constants defined

:: subBlack phpbb2 style by spectre :: PHP-Nuke theme by www.nukemods.com ::

This Website Is Best Viewed In Mozilla Firefox 0.9+
You Are Currently Using

UFT's Webring of Sci-Fi and Fantasy
UFT's Webring of Sci-Fi and Fantasy
Previous site : Random : Next site : List sites
Powered by PHP-Ring
Psychology News
Scitrek webring
Scitrek webring
Previous site : Random : Next site : List sites
Powered by .PHP-Ring
Psychology News
robots.txt
Contributors Contact Us