wbi mb training

8/3/2019 WBI MB Training

1/227

Websphere Business IntegrationMessage Broker 6.0


2/227

INTRODUCTION

WebSphere Message Broker and WebSphereEvent Broker belong to a family of businessintegration products that is available from IBM.

Business integration is the coordination andcooperation of all your business processes andapplications. It involves bringing together thedata and process intelligence in your enterprise,

and harnessing these so that your applicationsand your users can achieve their businessgoals.


3/227

Business integration

You can connect customers, suppliers,partners, and service providers, withcontinuing security and control, to enablenewly built and re-engineered applicationsfor more effective business processes (forexample, Supply Chain Management).

You can make mergers and acquisitions a

success by integrating dissimilar ITinfrastructures from more than onecompany so that they can work togetheras a single entity.


4/227

Contd

You can react more quickly to markettrends and opportunities because your ITsystems are flexible and dependable, and

no longer constraining.

You can overcome the barriers of diversecomputer systems, geographic

boundaries, time differences, languageand format differences, and differentmethods of working.


5/227

Transports

The main components of WebSphereMessage Broker and WebSphere EventBroker (the broker, the ConfigurationManager, the User Name Server, and theMessage Brokers Toolkit) communicateusing WebSphere MQs communicationsprotocol, WebSphere MQ EnterpriseTransport, or, if you implementWebSphere MQ Everyplace, WebSphereMQ Mobile Transport.


6/227

Transports Contd

Your business applications, which can be on anyof more than thirty industry platforms includingthose from IBM, Microsoft, and Sun

Microsystems, Inc., can connect to the brokerusing WebSphere MQ protocols, or using otherprotocols, such as WebSphere MQ TelemetryTransport, WebSphere MQ Real-time Transport,

WebSphere MQ Multicast Transport,WebSphere MQ Web Services Transport, orWebSphere Broker JMS Transport


7/227

Transports Contd

The benefit of using WebSphere MQprotocols (WebSphere MQ EnterpriseTransport or WebSphere MQ Mobile

Transport) is that they provide assured,once-only delivery of messages betweenthe components.


8/227

WebSphere MQ protocols provide richsupport for applications:

The Message Queue Interface (MQI) andApplication Messaging Interface (AMI) aresupported in several programming

languages.

The point-to-point (including request/replyand client/server) and publish/subscribe

application communication models aresupported.


9/227

Contd

The complexities of communicationsprogramming are handled by the messagingservices and are therefore removed from the

application logic.The applications can access other systems

and interfaces through adapters and

gateways to products such as LotusDomino, Microsoft Exchange/Outlook,SAP/R3, and CICS and IMS/ESAproducts.


10/227

WebSphere Event Broker

WebSphere Event Broker provides anoptimized publish and subscribe functionwithin a limited WebSphere Message

Broker framework. It provides high-performance nonpersistent publish andsubscribe functionality to clients that are

connected using various transports.


11/227

WebSphere Message Broker.

WebSphere Message Broker incorporatesWebSphere Event Broker and extends itsfunction to provide a powerful message

broker solution driven by business rules.Messages are formed, routed, andtransformed according to the rules defined

by an easy-to-use graphical user interface(GUI).


12/227

Contd

Diverse applications can exchangeinformation in dissimilar forms, withbrokers handling the processing required

for the information to arrive in the rightplace in the correct format, according tothe rules that you have defined. The

applications do not need to know anythingexcept their own conventions andrequirements.


13/227

Contd

Applications also have much greater flexibilityin selecting which messages they want toreceive, because they can specify a topic

filter, or a content-based filter, or both, tocontrol the messages that are made availableto them.

WebSphere Message Broker addresses theneeds of business and application integrationby managing the flow of information.


14/227

Contd

In addition to the function of WebSphereEvent Broker, it provides services, whichallows you to:

Route a message to several destinations,using rules that act on the contents of one ormore of the fields in the message or message

header.Transform a message, so that applications

using different formats can exchangemessages in their own formats.


15/227

Contd

Store a message, or part of a message, ina database.

Retrieve a message, or part of a message,from a database.

Modify the contents of a message; forexample, by adding data extracted from adatabase.


16/227

Contd

Exploit a public interface to develop messageprocessing node types that can beincorporated into the broker framework to

complement or replace the supplied nodes,or to incorporate node types developed byIndependent Software Vendors (ISVs).

Enable instrumentation by products such asthose developed by Tivoli, using systemmanagement hooks.


17/227

WBIMB Technical Overview


18/227

Contd

There are two ways in which WebSphereMessage Broker can act on messages.

Message routing

Messages can be routed from sender to

recipient based on the content of themessage.


19/227

Contd

The message flows that you design controlmessage routing. A message flowdescribes the operations to be performed

on the incoming message, and thesequence in which they are carried out.

Each message flow consists of:

A series of steps used to process amessage. The steps are defined inmessage flow nodes.


20/227

Contd

Connections between the nodes, definingroutes through the processing.Connections are made using message

flow node connections.

IBM supplies built-in nodes and samplesfor many common functions. If you require

additional functions, you can write yourown user-defined nodes.


21/227

Contd

You create message flows in the MessageBrokers Toolkit; an integrateddevelopment environment and broker

domain administration console.

Message transformation

Messages can be transformed beforebeing delivered:


22/227

Contd

They can be transformed from one format toanother, perhaps to accommodate the differentrequirements of the sender and the recipient.

They can be transformed by modifying,combining, adding or removing data fields,perhaps involving the use of information storedin a database. Information can be mapped

between messages and databases. Morecomplex manipulation of message data can beachieved by using Extended SQL (ESQL).


23/227

Create the run time

The work of routing and transforming messagestakes place in a broker. Brokers contain anumber of execution groups; processes in whichmessage flows are run.

Brokers are grouped into broker domains. Eachdomain is coordinated by a ConfigurationManager. There can be many brokers, and eachcan be running on a different system. Thisprovides protection against failure, and canseparate work across different divisions in abusiness.


24/227

Contd

The system administrator creates theConfiguration Manager with a command lineinstruction. The Configuration Manager uses aninternal repository to store information relating to

its broker domain. The system administrator similarly creates one

or more brokers, linking each to a particularConfiguration Manager, thus making them partof the domain controlled by that ConfigurationManager. Each broker uses a database to storethe information it needs to process messages atrun time.


25/227

Contd

The Configuration Manager also displaysthe users and groups in the Access controllists that you use to set user permissions,

see Publish/subscribe.


26/227

Develop applications

After the system administrator has createdand connected the components of thebroker domain, an application developer

creates and modifies message flows andmessage definitions using the workbench.

Different perspectives in the workbenchare used to develop message flows andmessage sets as well as to administer oneor more broker domains.


27/227

Contd

A repository can be used to provideaccess control and version control. Arepository also allows multiple developers

to work on the same resources in parallel.


28/227

Deploy applications to the run time

When message flows and message setshave been created using the workbench,executable data can be deployed

(transferred) to one or more brokers.

You can deploy data in one of two ways:

From the workbench

Using a shell command


29/227

Contd

When you deploy message flows and messagesets, they are compiled and enveloped in abroker archive (bar) file, and sent to the

Configuration Manager. The bar file hasconfigurable system properties. You canoverride properties such as queue and databasenames, without the need to change source files

or redevelop the message flow. This makes iteasier to move definitions between systems.


30/227

Contd

The Configuration Manager opens the envelope,removes the contents, makes a record of theinformation that it has received, and routes theinformation to the appropriate brokers. (Theenvelope is discarded when the information itcontains has been retrieved.) Each broker storesthe information in its own local database. Thismeans that, when a broker has sufficient

information, it can continue processingmessages even if it is no longer connected to itsConfiguration Manager.


31/227

Contd

The Configuration Manager coordinates allactivity (for example, changes to amessage set) between the workbench and

brokers within its domain. WebSphere MQmessaging is used between theworkbench, the Configuration Manager,

and the brokers.


32/227

Publish/subscribe

The simplest way of directing messages is touse point-to-point messaging, by sendingmessages directly from one application toanother. Publish/subscribe provides an

alternative style of messaging. A publishingapplication sends a message about a namedtopic to a broker. The broker passes thepublished message to those applications that

have registered an interest in that topic. Thepublisher and the subscriber are unaware of theothers existence.


33/227

Contd

The broker handles the distribution of messagesbetween publishing applications and subscribingapplications. Applications can publish on, or

subscribe to, many topics as well as apply moresophisticated filtering mechanisms.

An optional User Name Server in the brokerdomain controls who is authorized to publish or

subscribe to topics. You set up and administertopic-based security from the workbench.


34/227

Client environment

The Message Brokers Toolkit is an integrateddevelopment environment and graphical userinterface based on the Eclipse platform.

Application developers work in separateinstances of the Message Brokers Toolkit todevelop message sets and message flows. TheMessage Brokers Toolkit also communicateswith one or more Configuration Managers, andis used to manage broker domains.

The Message Brokers Toolkit can be installed onWindows and Linux (x86 platform).


35/227

The workbench

When you start the Message BrokersToolkit, a single window is displayed. Thisis the workbench, which contains one or

more perspectives.


36/227

Perspectives

A perspective is a group of views and editorsthat shows various aspects of the resources inthe workbench, and helps you to completespecific tasks.

You can switch perspectives, depending on thetask at hand, and customize the layout of views

and editors. Switch between perspectives byclicking Window Open Perspective Otherand clicking the name of the perspective towhich you want to switch.


37/227

Contd

The Message Brokers Toolkit contains the followingperspectives:

Broker Application Development perspective This is the default perspective that is displayed the first time that

you start the Message Brokers Toolkit. Application developerswork in this perspective to develop and modify message setsand message flows.

Broker Administration perspective

This is a broker administration console that communicateswith one or more Configuration Managers. Administratorswork in this perspective to manage the resources (alsoreferred to as domain objects) in the broker domain that aredefined on one or more Configuration Managers.


38/227

Contd

Debug perspective This is where applicationdevelopers test and debug message flows.

Plug-in Development perspective This is

where application developers develop plug-insfor user-defined extensions.

Data perspective This is where applicationdevelopers import relational database schemasfor ESQL content assist and validation.


39/227

Development repository

You can use any repository supported byEclipse with WebSphere Message Broker.Many repositories provide features such

as version control and access control offiles, and make it easier for teams to workon shared resources. Because theMessage Brokers Toolkit is based on the

Eclipse platform, you can access Eclipse-supported repositories directly from theMessage Brokers Toolkit.


40/227

Runtime environment

The runtime environment is the set of resources thatexist at run time, including the Configuration Manager,brokers, and execution groups. The following figureshows the relationship between the resources that exist

at run time, and how they interact with the workbench.The following are the main runtime components inWBIMB.

Broker.

Execution Group

Broker Domain

Configuration Manager

User Name server


41/227

Contd


42/227

Brokers

A broker is a set of execution processes thathosts one or more message flows to route,transform, and enrich inflight messages.

Applications send messages to the brokerusing WebSphere MQ queues andconnections. The broker routes each

message using the rules defined in messageflows and message sets, and transforms thedata into the structure required by thereceiving application.


43/227

Execution groups:

The broker uses sender and receiverchannels to communicate with theConfiguration Manager and other brokers in

the broker domain.An execution group is a named grouping of

message flows that have been assigned to a

broker. The broker enforces a degree ofisolation between message flows in distinctexecution groups by ensuring that theyexecute in separate address spaces, or as

unique processes.


44/227

Contd

Each execution group is started as aseparate operating system process, providingan isolated runtime environment for a set ofdeployed message flows. A single defaultexecution group is set up ready for use whenyou create a reference to a broker in theworkbench. By setting up additional

execution groups, you can isolate messageflows that handle sensitive data such aspayroll records, or security information, orunannounced product information, from other

non-sensitive message flows.


45/227

Contd

Within an execution group, the assignedmessage flows run in different thread pools. Youcan specify the size of the thread pool (that is,

the number of threads) that are assigned foreach message flow by specifying the number ofadditional instances of each message flow.

If you create additional execution groups, you

must give each group a name that is uniquewithin the broker, and assign and deploy one ormore message flows to each one.


46/227

Broker domains

A broker domain is one or more brokersthat share a common configuration,together with the single Configuration

Manager that controls them.You install, create, and start one or more

brokers, and an optional User Name

Server, in a broker domain. You canconfigure more than one broker domain,each managed by its own Configuration

Manager.


47/227

Contd

The Configuration Manager uses aninternal repository to store and shareinformation about the resources and

components in the domain.You create the physical components of a

broker domain using command line

instructions, and then configure andadminister the broker domain using theBroker Administration perspective in the

workbench.


48/227

Configuration Manager

The Configuration Manager is the interfacebetween the workbench and an executing setof brokers. It provides brokers with their initial

configuration, and updates them with anysubsequent changes. It maintains the brokerdomain configuration.

The Configuration Manager is the centralruntime component that manages thecomponents and resources that constitute thebroker domain.


49/227

Contd

The Configuration Manager has four mainfunctions:

Maintains configuration details in an internal

repository. This internal repository provides acentral record of the broker domaincomponents.

Deploys the broker topology and message

processing operations in response to actionsinitiated through the workbench. Brokerarchive (bar) files are deployed through theConfiguration Manager to the execution

groups within a broker.


50/227

Contd

Reports on the results of deployment and thestatus of the broker.

Communicates with other components in the

broker domain using WebSphere MQtransport services.

You must install, create, and start aConfiguration Manager for each broker

domain. You can install, create, and startmore than one Configuration Manager on oneor more machines.


51/227

Contd

Resources associated with aConfiguration Manager:

When you create the ConfigurationManager runtime component, thefollowing resources are also created:

An internal repository.


52/227

Contd

A WebSphere MQ queue manager (unlessone exists already) on the same physicalsystem as the Configuration Manager. A

queue manager can be shared with asingle broker.

A set of fixed-name queues, defined to the

queue manager that hosts theConfiguration Manager.


53/227

User Name Server

The User Name Server is an optionalruntime component that providesauthentication of users and groupsperforming publish/subscribe operations.


54/227

Contd

If you have applications that use thepublish/subscribe services of a broker, youcan apply an additional level of security tothe topics on which messages are

published and subscribed. This additionalsecurity, known as topic-based security, ismanaged by the User Name Server. Itprovides administrative control over who

can publish and who can subscribe.


55/227

Contd

For example, if a client applicationpublishes messages containing sensitivecompany finance information, or personnel

details, the User Name Server can beused to restrict access to those messages.

The User Name Server interfaces with

operating system facilities to provideinformation about valid users and groupsin a broker domain.


56/227

Message Flows


57/227

Overview

A message flow is a sequence of processingsteps that execute in the broker when aninput message is received. You define a

message flow in the workbench by includinga number of message flow nodes, each ofwhich represents a set of actions that definea processing step. The connections in theflow determine which processing steps arecarried out, in which order, and under whichconditions.


58/227

Contd

A message flow must include an inputnode that provides the source of themessages that are processed. You must

then deploy the message flow to a brokerfor execution. When you want to exchangemessages between multiple applications,

you might find that the applications do notunderstand or expect messages in exactlythe same format.


59/227

Contd

You might need to provide someprocessing between the sending andreceiving applications that ensures that

both can continue to work unchanged, butcan exchange messages successfully.


60/227

Message flow projects

A message flow project is a specializedcontainer in which you create and maintainall the resources associated with one or

more message flows. You can create amessage flow project to contain a singlemessage flow and its resources, or youcan group together related message flows

and resources in a single message flowproject to provide an organizationalstructure to your message flow resources.


61/227

Contd

Message flow project resources arecreated as files, and are displayed withinthe project in the Navigator view. These

resources define the content of themessage flow, and additional objects thatcontain detailed configuration information,

in the form of ESQL modules andmappings, for one or more nodes withinthe message flow.


62/227

Message flow nodes

A message flow node is a processing stepin a message flow. It receives a message,performs a set of actions against themessage, and optionally passes the

message on to the next node in themessage flow. A message flow node canbe a built-in node , a user-defined node, ora subflow node. A message flow node has

a fixed number of input and output pointsknown as terminals. You can makeconnections between the terminals todefine the routes that a message can take

through a message flow.


63/227

Contd

Built-in node

A built-in node is a message flow nodethat is supplied by WebSphere Message

Broker. The built-in nodes provide inputand output, manipulation andtransformation, decision making, collating

requests, and error handling and reportingfunctions.


64/227

Contd

User-defined node A user-defined node is an extension to the

broker that provides a new message flownode in addition to those supplied with theproduct. It must be written to the user-defined node API provided by WebSphereMessage Broker for both C and Javalanguages.


65/227

Contd

Subflow

A subflow is a directed graph that is composedof message flow nodes and connectors and is

designed to be embedded in a message flow orin another subflow. A subflow must include atleast one Input node or one Output node. Asubflow can be executed by a broker only as

part of the message flow in which it isembedded, and therefore cannot beindependently deployed.


66/227

Message flows And ESQL

A message flow represents the set ofactions performed on a message when itis received and processed by a broker.

The content and behavior of a messageflow is defined by a set of files that youcreate when you complete your definition

and configuration of the message flowcontent and structure:


67/227

Contd

The message flow definition file.msgflow. This is arequired file and is created automatically

for you. It contains details about themessage flow characteristics and contents(for example, what nodes it includes, its

promoted properties, and so on).


68/227

Contd

The ESQL resources file.esql. This file isrequired only if your message flow

includes one or more of the nodes thatmust be customized using ESQL modules.You can create this file yourself, or you

can use it to be created for you byrequesting specific actions against a node.


69/227

Contd

You can customize the following built-innodes by creating free-form ESQLstatements that use the built-in ESQL

statements and functions, and your ownuser-defined functions:

Compute

-- Database Filter


70/227

Connections And Terminal

Connections

A connection is an entity that connects anoutput terminal of one message flow node

to the input terminal of another. Itrepresents the flow of control and databetween two message flow nodes.


71/227

Contd

Terminals

A terminal is the point at which one node in amessage flow is connected to another node. Use

terminals to control the route that a messagetakes, depending whether the operationperformed by a node on that message issuccessful. Terminals are wired to other node

terminals using message flow node connectionsto indicate the flow of control.


72/227

Message Tree

A message tree is a structure that is createdby one or more parsers when an inputmessage bitstream is received by a messageflow or by the action of a message flow node.

A message is used to describe:A set of business data exchanged by

applications

A set of elements arranged in a predefined

structure.A structured sequence of bytes


73/227

Contd

WMB routes and manipulates messagesafter converting them into a logical tree.

The process of conversion, called parsing,

makes the content and structure of amessage obvious, and simplifies lateroperations. After the message has been

processed, the parser converts it back intoa bitstream.


74/227

Contd

WMB supplies a range of parsers tohandle the many different messagingstandards in use. In some cases WMB will

be able to parse your messageautomatically.

Alternatively, the MRM provides a

powerful method of modeling messagesthat you need to process. After a messagehas been parsed, it can be processed in a

message flow.


75/227

Contd

The logical tree contains identical contentsto that of the message but is easier tomanipulate within the message flow. The

message flow nodes provide an interfaceto query, update or create the contentwithin the tree.


76/227

How the message tree is populated

The message tree is initially populated by theinput node of the message flow. When theinput node receives the input message, it

creates the Properties tree (the first subtreeof the message tree) and populates this withthe node properties that you have configuredin the message flow. It then examines the

contents of the input message bit stream andcreates the remainder of the message tree toreflect those contents.


77/227

Contd

This process depends to some extent onthe input node itself, which is governed bythe transport across which the message is

received.WebSphere MQ Enterprise Transport,and WebSphere MQ Telemetry

Transport protocols


78/227

Contd

If your application communicates with thebroker across these protocols, and yourmessage flow includes the corresponding

MQInput, or SCADAInput node, allmessages that are received must startwith a Message Queue MessageDescriptor (MQMD) header. If a valid

MQMD is not present at the start of themessage, the message is rejected and nofurther processing takes place.


79/227

Contd

The input node first invokes the MQMDparser and creates the subtree for thatheader.

A message can have zero or moreadditional headers following the MQMD,and these are chained together, with the

Format field of one header defining theformat of the following header, up to andincluding the last header, which defines

the format of the message body.


80/227

Contd

If there is an MQRFH and MQRFH2header in the chain, the name/value datain either of these two headers can also

contain information about the format of thefollowing data. If the value specified inFormat is a recognized parser, this alwaystakes precedence over the name/value

data. The broker invokes the appropriateparser to interpret each header, followingthe chain in the message.

C


81/227

Contd

The broker ensures that the integrity of theheaders that precede a message body ismaintained. The format of each part of themessage is defined, either by the Format

field in the immediately preceding header(if the following part is a recognizedWebSphere MQ format) or by the valuesset in the MQRFH or MQRFH2 header:

The format of the first header is known,because this must be MQMD.

C d


82/227

Contd

The format of any subsequent header in themessage is set in the Format field in thepreceding header.

The format of the body corresponds to the

message domain and the parser that must beinvoked for the message body (for example,XML). This information is set either in the

MQRFH or MQRFH2 header, or in themessage domain property of the input nodethat receives the message.

C td


83/227

ContdThe original value in that field is stored in the

Domain field within the MQRFH or MQRFH2header to retain the information about thecontents of the message body. If there is noMQRFH or MQRFH2, the information is

stored in the Properties tree.For example, if the MQRFH2 header

immediately precedes the message body andits Format field is set to XML, indicating that

the message body must be parsed by thegeneric XML parser, the MQRFH2 Domainfield is set to XML, and its Format field resetto MQFMT_NONE.

C td


84/227

Contd

If the message has an MQRFH or MQRFH2header, the domain that is identified in theheader (either in Format or the name/valuedata) determines the parser that is

associated with this message. If the message does not have an MQRFH or

MQRFH2 header, or the header does notidentify the domain, but the properties of the

input node, stored in the Properties tree,indicate the domain of the message, theparser specified by the input node property isused. You can specify a user-defined parser.

C td


85/227

Contd

If the message domain cannot beidentified by header values or byproperties of the input node, the message

is handled as a binary object (BLOB). TheBLOB parser is associated with themessage. A BLOB can be interpreted as astring of hexadecimal characters, and can

be modified or examined in the messageflow by specifying the location of thesubset of the string.

C td


86/227

Contd

The message body is not parsed forperformance reasons; it is possible thatthe configuration of the message flow

does not require the message body to beparsed. The body is parsed only when areference is made to its contents during

the message flow.

T t t ft ti


87/227

Tree contents after an exception:

The contents of the message tree areupdated if an exception is raised. If noexception occurs while processing the

message, the tree structure and contentreceived by an individual node isdetermined by the action of previousnodes in the flow. If an exception occurs in

the message flow, the content of the fourtrees depends on the following factors:

C td


88/227

Contd

1. If the exception is returned to the inputnode, and the input node catch terminal isnot connected, the trees are discarded. If

the message is within a transaction, it isreturned to the input queue for furtherprocessing. When the message is

processed again, a new tree structure iscreated. If the message is not within atransaction, it is discarded.

C td


89/227

Contd

2. If the exception is returned to the inputnode and the catch terminal is connected,the Message and LocalEnvironment trees

that were created originally by the inputnode, and propagated through the outterminal, are restored, and any updates

that you made to their content in the nodesthat followed the input node are lost.

C td


90/227

Contd

The Environment tree is not restored, andits contents are preserved. If the nodesfollowing the input node include a

Compute node that creates a newLocalEnvironment or Message tree, thosetrees are lost. The ExceptionList tree

reflects the one or more exceptions thathave been recorded.

C td


91/227

Contd

3. If the exception is caught within themessage flow by a TryCatch node, theMessage and LocalEnvironment trees that

were previously propagated through thetry terminal of the TryCatch node arerestored and propagated through the catch

terminal. Any updates that you made totheir content in the nodes that followed theTryCatch node are lost.

Logical tree structure


92/227

Logical tree structure

The logical tree structure is the internal(broker) representation of a message.When a message arrives at a broker, it is

received by an input node that you haveconfigured in a message flow. Before themessage can be processed by themessage flow, it must be interpreted by

one or more parsers that create a logicaltree representation from the bit stream ofthe message data.

Contd


93/227

Contd

The tree format contains identical contentto the bit stream from which it is created,but it is easier to manipulate within the

message flow. Many of the built-inmessage flow nodes provide an interfacefor you to query and update messagecontent within the tree, and perform other

actions against messages and databasesto help you to provide the required functionin each node.

Contd


94/227

Contd

Three interfaces are provided:

ESQL, a programming language that youcan code in the Compute, Database, and

Filter nodes.Java, a programming language that you

can code in the JavaCompute node.

Contd


95/227

Contd

Mappings, a method of achieving transformationfrom input to output structures, available in theDataDelete, DataInsert, DataUpdate, Extract,Mapping, and Warehouse nodes. The tree

structure created by the parsers is largelyindependent of any message format (forexample, XML). The exception to this is thesubtree that is created as part of the message

tree and that represents the message body. Thissubtree is message dependent, and its contentis not further described.

Contd


96/227

Contd

The input node creates the logical tree, whichconsists of four subtrees:

Message Tree Environment Tree LocalEnvironment Tree ExceptionList Tree

The first of these trees is populated with the

contents of the input message bit stream.the remaining three are initially empty.Each of the four trees created has a rootelement. The root element has no parent.

Message tree:


97/227

Message tree:

The message tree is a part of the logicalmessage tree in which the broker stores itsinternal representation of the message body.The root of a message tree is called Root. Themessage tree is always present, and is passedfrom node to node within a single instance of amessage flow.

The message tree includes all the headers thatare present in the message, in addition to themessage body

Contd


98/227

Contd

If the message has been received across theWebSphere MQ Enterprise Transport,WebSphere MQ Mobile Transport, orWebSphere MQ Telemetry Transport, the firstheader (the second element) must be theMQMD. Any additional headers included in themessage appear in the tree in the same order as

in the message. The last element beneath theroot of the message tree is always the messagebody.

Contd


99/227

Contd

The message tree structure is shown below. If the inputmessage is not a WebSphere MQ message, the headersshown might not be present. If the parser that createdthis tree is a user-defined parser, the Properties tree

might not be present.

Properties

Root

Element1/Format1

BodyOther header

Element2/Field2

Element 3/Field3

MQMD

Contd


100/227

Contd

The Body tree, a structure of child elements(described below) that is determined by theparser, represents the message content (data).The message body might be:

MRM, if you have modeled the message. XML, if the message is self-defining.

A value that identifies a user-defined parser.

Properties parser:


101/227

Properties parser:

The properties folder is the first element ofthe message tree and holds informationabout the characteristics of the message.

The root of the properties folder is calledProperties. It is the first element underRoot. All message trees generated by the

built-in parsers include a properties folderfor the message.

Contd


102/227

Contd

If you create your own user-defined parser,you can choose whether the parser creates aproperties folder. However, for consistency,

you are recommended to include this actionin the user-defined parser.

For example, the MQRFH2 header containsinformation about the message set, type, andformat. These values are stored in theproperties folder as MessageSet,MessageType, and MessageFormat.

Contd


103/227

Contd

When the message flow processing iscomplete, the properties folder isdiscarded.

Environment tree:


104/227

Environment tree:

The Environment tree is a part of the logicalmessage tree in which you can storeinformation while the message passes

through the message flow. The root of theEnvironment tree is called Environment. Thistree is always present in the input message;an empty Environment tree is created when a

message is received and parsed by the inputnode. You can use this tree as you choose,and create both its content and structure.

Contd


105/227

ContdThe Environment tree differs from the

LocalEnvironment tree in that a singleinstance of it is maintained throughout themessage flow.

If you include a Compute node in yourmessage flow, you do not have to specifywhether you want the Environment tree to beincluded in the output message. Thishappens automatically, and the entirecontents of the input Environment tree areretained in the output Environment tree,subject to any modifications that you makeusing ESQL in the node.

Contd


106/227

Contd

Any changes that you make are availableto subsequent nodes in the message flow,and to previous nodes if the message

flows back (for example, to a FlowOrder orTryCatch node). You are recommended tocreate information in the Environment tree

within a subtree called Variables (althoughthis is not enforced).

Contd


107/227

Contd

There is one situation in which WebSphereMessage Broker refers to (but never creates)a field in this tree. If you have requested data

collection for message flow accounting andstatistics, and have indicated that accountingorigin basic support is required, the brokerchecks for the existence of the field

Environment.Broker.AccountingOrigin. If thefield exists, the broker uses its value to setthe accounting origin for the current data

record

Contd


108/227

Contd

Variables

CheeseWineBread

Evnironment

Name Currency

CountryColors

LocalEnvironment tree:


109/227

LocalEnvironment tree:

The LocalEnvironment tree is a part of thelogical message tree in which you canstore information while the message flow

processes the message. The root of theLocalEnvironment tree is calledLocalEnvironment. This tree is always

present in the input message: an emptyLocalEnvironment tree is created when amessage is received by the input node.

Contd


110/227

Contd

Use the LocalEnvironment tree to storevariables that can be referred to andupdated by message processing nodes

that occur later in the message flow.You can also use the LocalEnvironment

tree to define destinations (that are

internal and external to the message flow)to which a message is sent..

Contd


111/227

Contd

WebSphere Message Broker also storesinformation in LocalEnvironment in somecircumstances, and references it to accessvalues that you might have set fordestinations.(Contrast this to the Environmenttree).

The figure below shows the LocalEnvironment

tree structure. The children of Destination areprotocol-dependent.

Contd


112/227

Contd

If the message is parsed by another built-in parser, or bya user-defined parser, the tree structure below theDestination element has different content than thatshown in the figure.

WrittenDestination

DestinationVariables

LocalEvnironment

RouterList

Defaults

MQDestinatio

nList

MQ

DefaultsDestinationD

ataDestinationD

ataDestinationD

ata

Contd


113/227

Contd

VariablesThis subtree is optional. If you createlocal environment variables, you are

recommended to store them in asubtree called Variables. It provides awork area that you can use to pass

information between nodes. Thissubtree is never inspected or modifiedby any supplied node.

Contd


114/227

Contd

Variables in the local environment can bechanged by any subsequent messageprocessing node, and persist until the

message flow goes out of scope and thenode that created it has completed itswork and returns control to the previous

node.

Contd


115/227

Contd

The variables in this subtree are onlypersistent within a single instance of amessage flow. If you have multiple

instances of a message passing throughthe message flow, and need to passinformation between them, you must use

an external database.

Contd


116/227

Contd

Destination

This subtree consists of a number ofchildren that indicate the transport types to

which the message is directed (theTransport identifiers), or the target Labelnodes that are used by a RouteToLabel

node.

Contd


117/227

Contd

Transport information.Transport information is used by some input

and output nodes.

If the message flow includes an MQOutputnode, each element is a single nameelement, MQDestinationList. If more than oneelement exists, each is processed

sequentially by the node.

Contd


118/227

Contd

Routing information The child of Destination is RouterList. It has a

single child element called DestinationData,which has a single entry called labelName. If youare using a dynamic routing scenario involvingthe RouteToLabel and Label nodes, you mustset up the Destination subtree with a RouterList

that contains the reference labels.

WrittenDestination


119/227

WrittenDestination

This subtree contains the addresses towhich the message has been written. Itsname is fixed. It is created by the messageflow when a message is propagatedthrough the out terminal of an output node.It includes transport specific information(for example, if the output message has

been put to a WebSphere MQ queue, itincludes the queue manager and queuenames).

Contd


120/227

Contd

If the out terminal of the output node is notconnected to another node, this subtree isnot created. The topic for each output

node contains more information about thecontents of WrittenDestination forWebSphere MQ and WebSphere MQ

Everyplace.

ExceptionList tree:


121/227

cept o st t ee

The ExceptionList tree is a part of thelogical message tree in which themessage flow writes information about

exceptions that occur when a message isprocessed. The root of the ExceptionListtree is called ExceptionList, and the treeconsists of a set of zero or more exceptiondescriptions.

Contd


122/227

The ExceptionList tree is populated by themessage flow if an exception occurs. If noexception conditions occur during

message flow processing, the exceptionlist associated with that message consistsof a root element only.

Contd


123/227

This is, in effect, an empty list ofexceptions. The ExceptionList tree can beaccessed by other nodes within the

message flow that receive the messageafter the exception has occurred. You canmodify its contents only in the Computenode. If an exception condition occurs,message processing is suspended and anexception is thrown.

Contd


124/227

Control is passed back to a higher level,that is, an enclosing catch block.

An ExceptionList is built to describe the

failure condition, and the whole message,together with the LocalEnvironment andthe newly-populated ExceptionList, is

propagated through an exception handlingmessage flow path.

Contd


125/227

The child of the ExceptionList is alwaysRecoverableException. There is normallyonly one child of the root, although more

than one might be generated in somecircumstances. The child of theExceptionList contains a number ofchildren, the last of which provides furtherinformation specific to the type ofexception, which can be one of:

Contd


126/227

RecoverableExceptionParserException

ConversionException

UserException

DatabaseException

Correlation names in nodes that createan output message:


127/227

an output message:

If you are coding ESQL for a Compute node, thecorrelation names are different because thereare two message trees involved: the inputmessage and the output message. Thecorrelation names in ESQL within these nodes

are:Environment The structure that contains thecurrent global environment variables available tothe node. Environment can be read and

updated.InputRoot The root of the input message.

Contd


128/227

InputBodyThe last child of the root of the input

message. This is an alias for

InputRoot.*[


129/227

InputDestinationListThe structure that contains the localenvironment variables for the message

passing through the node. Use thecorrelation name InputDestinationList forbackward compatibility; if compatibility is

not required, use the preferred nameInputLocalEnvironment.

Contd


130/227

InputExceptionListThe structure that contains the exception

list for the message passing through the

node.InputLocalEnvironment

The structure that contains the local

environment variables for the messagepassing through the node.

Contd


131/227

OutputRoot The root of the output message. In a Compute

node, there is no correlation name OutputBodyOutputDestinationList

The structure that contains the local environmentvariables being sent out from the node. Use thecorrelation name OutputDestinationList forbackward compatibility; if compatibility is not

required, use the preferred nameOutputLocalEnvironment

Contd


132/227

OutputExceptionList The structure containing the exception list that

the node is generating. While this correlationname is always valid, it has meaning only when

the Compute Modeproperty of the Computenode indicates that the Compute node ispropagating the ExceptionList.

OutputLocalEnvironment

The structure that contains the local environmentvariables being sent out from the node.

Parsers


133/227

A parser is a program that interprets thebit stream of an incoming message andcreates an internal representation of themessage in a tree structure. It alsoregenerates a bit stream for an outgoingmessage from the internal message treerepresentation. A parser is invoked when

the bit stream that represents an inputmessage is converted to the internal formthat can be handled by the broker.

Contd


134/227

The way in which the parser interprets thebit stream is unique to that parser, so thelogical message tree that is created from

the bit stream varies from parser to parser.A parser might also create a bit stream

from a tree structure if a node in the

message flow invokes the ESQLASBITSTREAM function.

MRM parser and domain


135/227

The MRM message domain includes allmessages that are modeled in the workbench.You can create message models to represent awide range of message types, with one or more

optional physical formats. Messages in thisdomain are processed by the MRM parser. TheMRM parser is a program that interprets a bitstream or tree that represents a message that

belongs to the MRM domain, and generates thecorresponding tree from the bit stream on input,or bit stream from the tree on output.

Contd


136/227

Its interpretation depends on the physicalformat that you have associated with theinput or output message:

For CWF, the parser reads a set sequenceof bytes and translates these into the fieldsand values in the message tree.

Contd


137/227

For TDS, the parser uses the Data ElementSeparation method to parse the bit stream.Depending on the values that you have set forthe TDS physical format properties, this might

involve identifying delimiters, tags, fixed lengthelements, patterns, and so on.

For XML, the parser identifies the XML markup

language (tags and attributes) and creates thecorrect objects, modified by the values that youhave set for the XML physical format properties.

Contd


138/227

In the MRM domain, the message isconsidered in two parts:

1. The logical message model. This is the piece ofthe message that conveys the business data,devoid of its physical representation (how it

appears in a bit stream on the wire). It isindependent of platform and the way in whichthe message is constructed. For example, if youdefine a message that conveys informationabout a debit of an individuals bank account, itcan be represented in different physical formson the wire (in XML, or a fixed structure such asa COBOL copybook).

Contd


139/227

The business meaning and data is thesame in both cases: only the physicallayout has changed.

2. The physical representation. This is howthe data is physically laid out on the wire.A single logical message model might

have several different ways in which it canbe physically represented.


140/227

Message Modeling


141/227

Much of the business world relies on theexchange of information between applications.The information is contained in messageshaving a defined structure which is known andagreed by the sender and the receiver. You will

probably find that your applications use acombination of messages, including thosedefined by:

C and COBOL data structures.

industry standards such as SWIFT or EDIFACT. XML DTD or schema.

Contd


142/227

You can model a wide variety of messageformats which can be understood by WebSphereMessage Broker message flows. Once themessage format is known, the broker can parse

an incoming message bit stream and convert itinto a logical message tree for manipulation by amessage flow. After the message has beenprocessed by the message flow, the brokerconverts the message tree back into a messagebit stream.

Message modeling concepts


143/227

Message modeling is a way of predefiningthe message formats used by yourapplications. Once you have modeled your

messages, products like WebSphereMessage Broker can use your messagemodels to automatically parse and writeyour message formats. When you modelmessages you need to understand thefollowing concepts:

Contd


144/227

Message set projectsMessage sets

Message definition files

Message categories

Domains and parsers

Why model messages?


145/227

A product such as WebSphere MessageBroker typically supplies a range of parsers toparse and write message formats. Somemessage formats are self-defining and can

be parsed without reference to a model. Anexample of a self-defining message format isXML. In XML the message itself containsmetadata as well as data values, enabling an

XML parser to understand an XML messageeven if no model is available. Most messageformats, however, are not self-defining.

Contd


146/227

As examples, a binary messageoriginating from a COBOL program and aSWIFT formatted text message do not

contain sufficient metadata to enable aparser to understand the message. Theparser must have access to a model thatdescribes the message to parse itcorrectly.

Which message domain and format touse?


147/227

use?

Each message set you create specifies adomain, which determines the parser thatis used when parsing and writing allmessages defined within that message

set. Each domain is suited to a particularclass of messages (fixed-length binary,delimited text, XML and so on).

Additionally, some domains supportseveral physical formats (sometimescalled wire formats).

Contd


148/227

When you create a message set you need todecide which domain and physical format to use.

You can select one of the following domains:

MRM For modeling a wide range of messagesincluding XML, fixed-format binary and formattedtext.

XML, XMLNS or XMLNSC For messages

conforming to the W3C XML standard.

Contd


149/227

JMSMap or JMSStream For messagesproduced by the WebSphere MQimplementation of the Java Messaging

Service standard.IDOC For messages in SAP IDoc format.

MIME For handling multipart MIME

messages such as SOAP withAttachments or RosettaNet.

The message model


150/227

The message model consists of thefollowing components:

Message set projects

Message setsMessage definition files

Message categories

Message set projects


151/227

A message set project is a specializedcontainer in which you create and maintainall the resources associated with one

message set. The content of a messageset project is a single message set folder,the name of which provides the name ofthe message set.


152/227

Contd


153/227

Runtime ParserThe message domain of the message set. This

is used when parsing and writing all messagesdefined within that message set and effectively

defines the message domain.Use Namespaces

Indicates whether the message definitions you

create within the message set are XMLnamespace aware.

Contd


154/227

Message set resources:Resources within a message set are created

as files, and are displayed under the messageset folder in the Navigator view:

Message set file messageSet.mset

There is always one, and only one,messageSet.mset file in a message set. It

contains message model properties that arecommon to all the content of the message set.

Contd


155/227

It is also where you define the physicalformats that you want for this message set.These can be Custom Wire Format (CWF),XML Wire Format (XML) and Tagged

Delimited String Format (TDS). The file iscreated for you when a new message setis created, and you manipulate its contentwith the Message Set Editor.

Message definition files that have thesuffix .mxsd.

Contd


156/227

You can have many message definition filesin a message set. Each file contains thelogical model and associated physical modelin XML Schema form for a group of relatedmessages.

Message category files that have thesuffix .category

These files are optional. You can have manymessage category files in a message set.

Contd


157/227

A message category provides another wayof grouping your messages, perhaps fordocumentation purposes or to assist withgenerating Web Services Description

Language (WSDL) files.Message set identification:

As well as having a name, provided by the

folder, and a message set alias, amessage set also has an identifier.

Contd


158/227

This is a generated string of 13 charactersthat uniquely identifies the message set.You can use either the name, the alias, or

the identifier interchangeably wheneveryou need to specify the message set to aruntime product such as WebSphereMessage Broker (for example, in anMQRFH2 message header).

Contd


159/227

Message set version and keywords:When you are developing a message set,

you can define the version of the message

set as well as any other key informationthat you need to be associated to it. Afterthe message set has been deployed, the

Configuration Manager can be used todisplay the properties of the message set.

Contd


160/227

This includes the deployment andmodification dates and times (the defaultinformation that is displayed) as well as

any additional version or keywordinformation that you have set.

$MQSI Author=John Smith MQSI$

$MQSI Subflow 1 Version=v1.3.2 MQSI$.

Message definition files


161/227

A message definition file contains themessages, elements, types and groupswhich make up a message set. Every

message set requires at least onemessage definition file to describe itsmessages. Message definition files usethe XML Schema language to describe thelogical format of one or more messages.


162/227

XML Schema:


163/227

XML Schema is an international standardwhich defines a language for describingthe structure of XML documents. The XMLSchema language is ideally suited to

describing the messages which flowbetween business applications, and it iswidely used in the business community for

this purpose. WebSphere Message Brokeruses XML Schema to describe the logicalstructure of messages.

Contd


164/227

At a simple level, the types and elementsin the message are modeled using XMLSchema types and elements. However,

when the need arises, most of theadvanced modeling features of XMLSchema are available for modeling MRMmessages.

Messages


165/227

A message is a global elementrepresenting an entire message (ratherthan a structure within a message). Within

a message definition file, a message isrepresented by a special global elementwhich carries the extra informationrequired by WebSphere Message Broker.

Composition


166/227

The message model adds the followingcompositions which are beyond the XMLSchema specification. These extra

compositions allow message modelsproduced in earlier versions of the productto be supported.

Contd


167/227

OrderedSet A set of elements which must appear in the

order in which they are listed. Groups are notallowed within an orderedSet. Elements can

repeat, but duplicate element references are notallowed.

UnorderedSet

A set of elements which can appear in any

order. Groups are not allowed within anunorderedSet.

Contd


168/227

Unlike an all group, elements within anorderedSet are allowed to repeat.However, duplicate element references

are not allowed.


169/227

Message model objects:


170/227

Message A message is a set of data passed between

applications. Messages must have a structureand format which is agreed by the sending and

receiving applications.Message definition

A message definition is a logical description of amessage. A message definition is a collection of

simple elements organized in a tree-likestructure.

Contd


171/227

Simple elementA simple element describes one or more

fields in a message. It is based on a

simple type (for example, string, integer orfloat). It can repeat, and it can define adefault or a fixed value.

Contd


172/227

Simple type A simple type describes a class of data within amessage. It describes the type of data (forexample, string, integer or float) and it can havevalue constraints which place limits on the

values of any simple elements based on thatsimple type.

Complex element A complex element is a named structure

containing simple elements within the message.Complex elements can contain other complexelements, and can also contain groups.

Contd


173/227

The content of a complex element is defined bya complex type.Complex type

A complex type describes a structure within a

message. It contains elements, attributes andgroups organised into a hierarchy.Group

A group is a list of elements with informationabout how those elements can appear in amessage. Groups can be ordered (sequence)unordered (all) or selective (choice).


174/227


175/227


176/227

Extended Structured Query Language(ESQL) is a programming language definedby WebSphere Message Broker to define andmanipulate data within a message flow. Thissection contains introductory informationabout ESQL. ESQL is based on StructuredQuery Language (SQL) which is in commonusage with relational databases such as DB2.ESQL extends the constructs of the SQL

language to provide support for you to workwith message and database content to definethe behavior of nodes in a message flow.


177/227

The ESQL code that you create tocustomize nodes within a message flow isdefined in an ESQL file, typically named

.esql, which isassociated with the message flow project.You can also use ESQL to createfunctions and procedures that you can use

in some built-in nodes, like Compute,Databse and Filter nodes.


178/227


179/227

5 Statements6 Functions

7 Procedures8 Modules


180/227


181/227


182/227

Contd


183/227

Note: The names of ESQL variables arecase sensitive, so it is important to makesure that you use the correct case in all

places. The simplest way to guarantee thisis always to define variables using uppercase names.

Variable scope, lifetime, and sharing


184/227

How widespread and for how long aparticular ESQL variable is available, isdescribed by its scope, lifetime, and

sharing:A variables scope is a measure of the

range over which it is visible. In the brokerenvironment, the scope of variables isnormally limited to the individual node.


185/227


186/227

Types of variable


187/227

You can use the DECLARE statement todefine a variable in your ESQL code. Thefollowing are three different types of variable.

External

External variables (defined with the EXTERNALkeyword) are also known as user-definedproperties. They exist for the entire lifetime of a

message flow and are visible to all messagespassing through the flow.

Contd


188/227

Their initial values (optionally set by theDECLARE statement) can be modified, atdesign time, by the Message Flow editor,

or, at deployment time, by the BAR editor.Their values cannot be modified by ESQL.


189/227

Contd


190/227

SharedShared variables (defined with theSHARED keyword) are long-lived. They

are re-initialized only when a messageflow is modified or restarted and are visibleto all messages passing through the flow.Their values can be modified by ESQL.

Contd


191/227

User-defined propertiesA user-defined property (UDP) is a user-definedconstant whose initial value can be modified, atdesign time, by the Message Flow editor, or

overridden, at deployment time, by the BrokerArchive editor. You can use UDPs in your ESQLor Java programs. In ESQL, you use theDECLARE statement to define a UDP to yourprogram.

Contd


192/227

You can give the UDP an initial value on theDECLARE statement, but your code cannotmodify the value at run-time.

When a UDP is given an initial value on the

DECLARE statement this becomes its default.However, any value specified by the MessageFlow editor at design time, or by the BAR editorat deployment time (even a zero length string)overrides any initial value coded on theDECLARE statement.

Contd


193/227

All UDPs in a message flow must have avalue, given either on the DECLAREstatement or by the Message Flow or BAReditor; otherwise a deployment-time erroroccurs. At run time, after the UDP hasbeen declared its value can be queried bysubsequent ESQL statements but not

modified.


194/227

Contd


195/227

This makes access much faster than itwould be from a database, though this isat the expense of shorter persistence andno transactionality.

Long-lifetime variables are created byusing the SHARED keyword on theDECLARE statement. Long-lived datatypes have an extended lifetime beyond

that of a single message passing througha node.

Contd


196/227

They are shared between threads andexist for the life of a message flow (strictlyspeaking the time between configurationchanges to a message flow).

ESQL field references


197/227

An ESQL field reference is a sequence ofperiod-separated values that identify aspecific field (which might be a structure)within a message tree or a database table.The path from the root of the informationto the specific field is traced using theparent/child relationships.

Contd


198/227

A field reference is used in an ESQLstatement to identify the field that is to bereferenced, updated, or created within themessage or database table.

For example, you might use the followingidentifier as a message field reference:You can use an ESQL variable of type

REFERENCE to set up a dynamic pointerto contain a field reference.


199/227

ESQL operators


200/227

An ESQL operator is a character or symbol thatyou can use in expressions to specifyrelationships between fields or values. ESQLsupports the following groups of operators:

Comparison operators To compare one value to another value (for

example, less than).

Logical operators

To perform logical operations on one or twoterms (for example, AND).

Contd


201/227

Numeric operatorsTo indicate operations on numeric data

(for example, +).

There are some restrictions on theapplication of some operators to datatypes; not all lead to a meaningful

operation. These are documented wherethey apply to each operator.

ESQL statements


202/227

An ESQL statement is an instruction thatrepresents a step in a sequence of actions or aset of declarations. ESQL provides a largenumber of different statements that perform

different types of operation. All ESQL statementsstart with a keyword that identifies the type ofstatement and end with a semicolon. An ESQLprogram consists of a number of statements that

are processed in the order they are written.

Contd


203/227

As an example, consider the followingESQL program:

DECLARE X INTEGER;

SET X = 42;This program consists of two statements.The first starts with the keyword

DECLARE and ends at the first semicolon.


204/227

Contd


205/227

The first statement declares a variablecalled x of type INTEGER, that is, itreserves a space in the computersmemory large enough to hold an integervalue and allows this space to besubsequently referred to in the program bythe name x. The second statement setsthe value of the variable x to 42. A numberappearing in an ESQL program withoutdecimal point and not within quotes isknown as an integer literal.

ContdESQL nested statements


206/227

An ESQL nested statement is a statement that iscontained within another statement. Considerthe following ESQL program fragment:IF Size > 100.00 THEN

SET X = 0;SET Y = 0;SET REVERSE = FALSE;

ELSE

SET X = 639;SET Y = 479;SET REVERSE = TRUE;

END IF;

ESQL functionsA function is an ESQL construct that


207/227

calculates a value from a number of giveninput values. A function usually has inputparameters and can, but does not usuallyhave, output parameters. It returns a valuecalculated by the algorithm described byits statement. This statement is usually acompound statement, such as BEGIN...END, because this allows an unlimitednumber of nested statements to be usedto implement the algorithm.

Contd


208/227

ESQL provides a number of predefined, orbuilt-in, functions which you can usefreely within expressions. You can alsouse the CREATE FUNCTION statement todefine your own functions

ESQL procedures


209/227

An procedure is a subroutine that has noreturn value. It can accept inputparameters from, and return outputparameters to, the caller. Procedures arevery similar to functions. The maindifference between them is that, unlikefunctions, procedures have no returnvalue. Thus they cannot form part of anexpression and are invoked by using theCALL statement. Procedures commonlyhave output parameters.

Contd


210/227

You can implement a procedure in ESQL(an internal procedure) or as a databasestored procedure (an external procedure).The ESQL procedure must be a singleESQL statement, although that statementcan be a compound statement such asBEGIN END.

ESQL modules


211/227

A module is a sequence of declarationsthat define variables and their initialization,and a sequence of subroutine (functionand procedure) declarations that define a

specific behavior for a message flow node.A module must begin with the CREATEnode_type MODULE statement and endwith an END MODULE statement. Thenode_type must be one of COMPUTE,DATABASE, or FILTER.

Contd


212/227

The entry point of the ESQL code is thefunction named MAIN, which hasMODULE scope. Each module is identifiedby a name which follows CREATEnode_type MODULE.

The name might be created for you with adefault value, which you can modify, oryou can create it yourself.

Creating ESQL for a node


213/227

The name is handled in a case insensitiveway (that is, use of the name with anycombination of upper and lower caseletters matches the declaration). That is incontrast to the names that you declare forschemas, constants, variables, and labels,which are handled in a case sensitive way,

and which you must specify exactly as youdeclared them.

Contd


214/227

You can also create local constants andvariables. If you have created constants,functions, or procedures at the brokerschema level, you can also refer to thesewithin the module. You can define routinesat a level at which many different modulescan use them, which can save you

development time and maintenance effort.To create ESQL for a node:

Contd

Create ESQL to customize the behavior of a


215/227

Compute, Database, or Filter node within anESQL file. Before you start To complete thistask, you must have completed the followingtask:

A module can be associated with only onenode of a particular type (Compute,Database, or Filter). Within the module you

can create and use functions and proceduresas well as the supplied statements andfunctions.

Contd

1 Switch to the Broker Application Development


216/227

1. Switch to the Broker Application Developmentperspective.

2. In the Navigator view, double-click the messageflow that includes the node for which you want tocreate ESQL. The message flow opens in the

editor view.3. Right-click the node (which must be Compute,

Database, or Filter) and click Open ESQL. Thedefault ESQL file for this message flow,.esql, is opened in theeditor view (the file is created if it does notalready exist).

Contd


217/227

If you have already created the default fileand you click Open ESQL, the file isopened in the editor view and a newmodule is created and highlighted. Askeleton module is created for this node atthe end of the ESQL file. Its exact contentdepends on the type of node. The

following module is created for a Computenode:

Contd

CREATE COMPUTE MODULE CREATE FUNCTION Main() RETURNS BOOLEAN


218/227

CREATE FUNCTION Main() RETURNS BOOLEAN

BEGIN-- CALL CopyMessageHeaders();-- CALL CopyEntireMessage();

RETURN TRUE;END;

CREATE PROCEDURE CopyMessageHeaders()BEGIN

DECLARE I INTEGER 1;DECLARE J INTEGER CARDINALITY(InputRoot.*[]);WHILE I < J DO

SET OutputRoot.*[I] = InputRoot.*[I];SET I = I + 1;

END WHILE;END;

CREATE PROCEDURE CopyEntireMessage()

BEGIN SET OutputRoot = InputRoot;END;

END MODULE;

Contd

The module name is determined by the value


219/227

The module name is determined by the valuethat you have set for the corresponding nodeproperty. The default is_. TheMain function contains calls to two procedures,

described below, that are declared within theCompute node module following the functionMain. These calls are commented out. If youwant to include the function that they provide,uncomment these lines and place them at the

appropriate point in the ESQL that you create forMain.

Contd


220/227

CopyMessageHeadersThis procedure loops through the headerscontained in the input message and copieseach one to the output message. If you

are migrating from Version 2.1, thisprocedure is equivalent to the codegenerated when you select the Copymessage headers button on the Computenode properties dialog.

Contd


221/227

CopyEntireMessageThis procedure copies the entire contentsof the input message, including the

headers, to the output message. If you aremigrating from Version 2.1, this procedureis equivalent to the code generated whenyou select the Copy entire message button

on the Compute node properties dialog.

Contd

Adding comments to ESQL


222/227

Adding comments to ESQLYou can add comments to and removecomments from your ESQL code:

1. To change an existing line of code into acomment line, click Source Comment.

2. To change a comment line to a code line, clickSource Uncomment.

3. To create a new comment line, press Enter tocreate a new line and either type the comment

identifier -- or click Source Comment. Youcan enter any text after the identifier: everythingyou type is ignored by the ESQL editor.

Contd

ESQL TIME data type


223/227

ESQL TIME data type

The TIME data type holds a time of day in hours,minutes, seconds, and fractions of a second.The format of a TIME literal is the word TIMEfollowed by a space, followed by a time in singlequotation marks in the form hh:mm:ss.ffffff. Forexample: DECLARE MyTime TIME; SETMyTime = TIME 11:49:23.656; Each of thehour, minute, and second fields in a TIME literalmust always be two digits; the optional fractionalseconds field can be up to 6 digits in length.

Contd


224/227

ESQL GMTTIME data typeThe GMTTIME data type is similar to theTIME data type, except that its values areinterpreted as values in Greenwich Mean

Time. GMTTIME literals are defined in asimilar way to TIME values. For example:DECLARE MyGetGmttime GMTTIME;SET MyGetGmttime = GMTTIME12:00:00;

Contd


225/227

ESQL TIMESTAMP data typeThe TIMESTAMP data type holds a DATEand a TIME in years, months, days, hours,minutes, seconds, and fractions of a

second. The format of a TIMESTAMPliteral is the word TIMESTAMP followed bya space, followed by a timestamp in singlequotation marks in the form yyyy-mm-ddhh:mm:ss.ffffff.

Contd


226/227

For example: DECLARE MyTimeStampTIMESTAMP; SET MyTimeStamp =TIMESTAMP 1999-12-31 23:59:59; Theyear field must always be four digits inlength. The month, day, hour, and minutefields must always be two digits. (Do notomit leading zeroes.) The optional

fractional seconds field can be 0 - 6 digitslong.

Contd


227/227

ESQL GMTTIMESTAMP data typeThe GMTTIMESTAMP data type is similar to theTIMESTAMP data type, except that the valuesare interpreted as values in Greenwich Mean

Time. GMTTIMESTAMP values are defined in asimilar way to TIMESTAMP values, for example:DECLARE MyGetGMTTimeStampGMTTIMESTAMP; SET MyGetGMTTimeStamp

wbi mb training

Documents