Using z/OS workload management with the WebSphere MQ resource adapter in WebSphere Application Server V7

IBM® WebSphere® Application Server V7.0 has introduced a Java™ Enterprise Edition Connector Architecture (JCA) compliant resource adapter for interoperability with WebSphere MQ, which enables the z/OS workload manager function (zWLM) to process messages of different types or priority across many servant regions. This is often critical to tuning the performance of business applications. This article shows how to configure messaging applications, WebSphere Application Server, and the z/OS system to utilize the zWLM function through the MQ resource adapter for messages flowing between MQ and WebSphere Application Server This content is part of the IBM WebSphere Developer Technical Journal.

Karl Gaffney (kgaffney@uk.ibm.com), Software Test Engineer, IBM

author photoKarl Gaffney works in the WebSphere OSGi team at the Hursley Lab in England. He holds a PhD in Artificial Intelligence. Karl has worked at IBM for 10 years, and has significant experience testing the OSGi framework in WebSphere Application Server and also the interoperability of the WebSphere Application Server and WebSphere MQ from a messaging perspective.



12 November 2008

Also available in Chinese

Introduction

A vitally important function of the WebSphere Application Server from a messaging perspective is its ability to interoperate with WebSphere MQ (hereafter called MQ), IBM’s key messaging product. In WebSphere Application Server Version 6.0 and above, this interoperability relied upon the MQ JAR files that were shipped and installed with WebSphere Application Server or with the MQ client. WebSphere Application Server Version 7.0 has introduced a fully pluggable, Java Enterprise Edition Connector Architecture (hereafter called JCA) compliant MQ resource adapter to replace these JAR files. In addition to standard J2EE resource adapter features, the MQ resource adapter enables more advanced function, such as:

  • Client-channel compression
  • Client-channel exits
  • Client-channel definition tables
  • MQ activation specifications for message-driven beans (MDBs) using a Java Messaging Service (hereafter called JMS) application for WebSphere MQ
  • More integrated logging and tracing features.

The MQ resource adapter shipped and installed with WebSphere Application Server 7.0 currently works with MQ v6 and above.

One of the additional Qualities of Service available to WebSphere running on the z/OS platform is the ability to exploit the z/OS Workload Manager (hereafter called zWLM). zWLM enables many different workloads with different priorities and requirements to execute on the same hardware. If resources (such as CPU or storage) become constrained, then zWLM will distribute these resources, attempting to ensure that each workload meets its goals.

The new MQ resource adapter on the z/OS platform also lets you use zWLM within WebSphere Application Server. In WebSphere Application Server on z/OS, you can host multiple copies of the EJB container across different servant regions. You can dedicate each servant region to handling certain types of workloads, such as processing certain types or classes of messages instead of just the one servant region handling everything. You can tune the zWLM function to define workload goals for each servant region, and hence assign priority to incoming requests for message processing. For example, for high priority work items you could set a goal of “90% processed within 0.1 second”. The zWLM function will do its best to achieve these goals based on the resources available.

Figure 1 illustrates how messages are consumed by multiple servant regions via zWLM and the MQ resource adapter within WebSphere Application Server. Multiple servant regions host instances of message-driven beans (MDBs) deployed using MQ activation specifications that consume messages appearing on the MQ queue. These messages might be classified for processing priority; for example GOLD, SILVER, and BRONZE. Messages are inspected in the order they arrive on the MQ queue that the MDB’s activation specification requests that it monitors. MQ then assigns work load classifications to the messages based on classification rules known to the control region adjunct (CRA). zWLM then uses these classifications to select a servant region to process the message. The corresponding MDB instance running in that servant region processes the message based on goals set for that class of message.

Figure 1. MQ resource adapter usage in WebSphere Application Server 7.0 on z/OS
MQ resource adapter usage in WebSphere Application Server 7.0 on z/OS

Configuring a JMS application for MQ message classification

The sample JMS client application uses an arbitrary integer property on the message to store the message’s priority. We used JMSXGroupSeq because it is a pre-existing integer property on the message object that is not otherwise used by the application. You could also define a new integer property by the user specifically for classification, but here we used JMSXGroupSeq for convenience and illustrative purposes.

The integer range values correspond to levels as follows:

  • BRONZE: Priority = 0 to 3
  • SILVER: Priority = 4 to 6
  • GOLD: Priority = 7 to 9

In terms of message processing, the GOLD messages should take priority over both SILVER and BRONZE, and SILVER messages take priority over BRONZE.

Listing 1. Sample JMS client application
int count=0;
for (int i = 1; i <= messageCount; i++) {

    // 9 = GOLD, 6 = SILVER, 3 = BRONZE
    if (count==0) priority=3;
    if (count==1) priority=6;
    if (count==2) priority=9;
             

    // jmsMessage is the JMS Message object       
    jmsMessage.setIntProperty("JMSXGroupSeq", priority);

    // queueSender is the JMS QueueSender object
    queueSender.send(jmsMessage);
                    
    ++count;
}

In Listing 1, we assign message priority simply on a round-robin basis. In reality, you would assign priority on an application requirement based on business need. We set the priority after the creation of the JMS messages and before the send occurs.


Defining classification rules

Next we’re required to define classification rules, by creating (or amending) a Workload Classification document. These rules associate message priorities with Transaction Classes defined on the zWLM system (see Listing 2) and are defined in an XML document.

Listing 2. Workload classification document
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Classification SYSTEM "Classification.dtd">
<Classification schema_version="1.0">
	<WMQRAClassification default_transaction_class="TC_3" schema_version="1.0">
  		<wmqra_classification_info transaction_class="TC_1"
                             selector="JMSXGroupSeq&gt;6"
                             description="High priorities 7,8,9 map to TC_1 = GOLD"/>
  		<wmqra_classification_info transaction_class="TC_2"
                             selector="JMSXGroupSeq&gt;3 AND JMSXGroupSeq&lt;7"
                             description="Medium priorities 4,5,6 map to TC_2 = SILVER"/>
	</WMQRAClassification>
</Classification>

With this file defined (called zwlm.xml for example), messages that the MQ resource adapter message selector function browses in the control region adjunct with GOLD priority (in this case JMSXGroupSeq > 7 ) are handled by Transaction Class TC_1 within the zWLM function for consumption by the appropriate servant region(s). SILVER priority messages (JMSXGroupSeq > 3 and < 8) are handled by Transaction Class TC_2 and all other messages (BRONZE in this case) are handled by TC_3.

Listing 3 shows the associated DTD file (called Classification.dtd for example):

Listing 3. Workload classification document DTD
<?xml version='1.0' encoding="UTF-8"?>
<!ELEMENT WMQRAClassification (wmqra_classification_info+)>
<!ATTLIST WMQRAClassification default_transaction_class CDATA #REQUIRED>
<!ATTLIST WMQRAClassification schema_version CDATA #REQUIRED>
<!ELEMENT wmqra_classification_info EMPTY>
<!ATTLIST wmqra_classification_info transaction_class CDATA #REQUIRED>
<!ATTLIST wmqra_classification_info selector CDATA #IMPLIED>
<!ATTLIST wmqra_classification_info description CDATA #IMPLIED>

This DTD file can also contain classification information for incoming IIOP, HTTP and MDB (monitoring non-WMQ queues) calls. Both the workload classification file and the DTD file together should be placed in any suitable location on the z/OS system. For this sample we placed them in a directory called /classification in the Application Server profile on the HFS file system.


Configuring WebSphere Application Server from the Administrative Console

Next we need to configure the Application Server to utilize the zWLM function and the classification rules defined in the last section. The control region adjunct must be present after WebSphere Application Server starts. This is required for both MQ activation specification MDBs and the MQ resource adapter message selector function for zWLM.

  1. In the adminstrative console select: Servers -> Server Types - WebSphere application servers - <server_name> - Messaging - WebSphere MQ CRA settings. Check the Start CRA box.
  2. To use the zWLM function, you need to enable multiple servant regions. For this sample we will make three servant regions “startable”, one for each transaction class (and message priority type). However, you could tune these to suit your application requirements, for example with more servant regions if possible. Each transaction class runs in its own servant region. In the administrative console, select Servers -> Server Types - WebSphere application servers - <server_name> - Java and Process Management - Server Instance. Check the Multiple Instances Enabled box.
  3. Set the Minimum Number of Instances and Maximum Number of Instances to 3 (as in Figure 2). Setting the minimum number in this way (rather than having a minimum of 1, say) ensures that all the servant regions are available after WebSphere Application Server start up. Otherwise the first request to a Transaction Class could take some time because the servant region would need to be started.
    Figure 2. Define the number of servant region instances
    Define the number of servant region instances
  4. Set the wlm_classification_file environment variable to reference the workload classification document. You can set this variable at the cell, node, or server level. If you specify the cell or node level, the information contained in it must be accessible and applicable to all servers that inherit the specification from that cell or node. In the administrative console, select:Environment - WebSphere variables - New.
  5. Make the Name wlm_classification_file and the Value: /WebSphere/Base/AppServer/profiles/default/classification/zwlm.xml.

Configuring WebSphere Application Server and zWLM via TSO

This section shows how to configure zWLM to process the GOLD, SILVER, and BRONZE messages arriving from MQ through the control region adjunct, to be subsequently consumed in an appropriate servant region. Of course you would definite your actual user implementation based on application requirements with suitable goals specified.

Invoke the zWLM configuration interface in the z/OS command interface (TSO) by selecting 6. Command (or whatever number corresponds to ‘Command’) from the primary option menu. Then issue this command: iwmarin0

Defining the service classes

Next we create a service class for each message priority type’s (GOLD, SILVER, BRONZE) transaction class defined in the workload classification XML file. These service classes specify the goals for message processing in the respective servant regions for each type. For example the user might want to specify the target average response time of each transaction, or more usually target average response time with a percentile. The average response time is usually chosen because often, if the goal is unachievable and unrealistic, the zWLM function discards any attempt to achieve it.

For our example, we will create three service classes called MQGOLD, MQSILVER, and MQBRONZE, each with a goal of an average response time with a percentile. The GOLD has the fastest target response time.

  1. Select (2) Extract definition from WLM couple data setas in Figure 3:
    Figure 3. Extract service definition for defining Service Classes
    Extract service definition for defining Service Classes
  2. Then select (4) Service Classes as in Figure 4:
    Figure 4. Start defining the Service Class
    Start defining the Service Class
  3. Next create a new service class from any existing class by selecting an existing class and entering 1 for the action.
    Figure 5. Choose an existing Service Class to define a new one
    Choose an existing Service Class to define a new one
  4. Define the Service Class Name (MQGOLD in this example) with a Workload Name to group the classes together (WEB has been chosen here) and enter I under the action to insert the goal, as Figure 6 shows:
    Figure 6. Define the MQGOLD Service Class for GOLD messages
    Define the MQGOLD Service Class for GOLD messages
  5. Now you choose the type of goal (response time with percentile) and define MQGOLD to be “90% of messages processed within 0.1 seconds”. Select 2 from the goal type menu as shown in Figure 7. On the subsequent goal data entry screen (Figure 8) you enter 90 as the Percentile and 0.1 as the Seconds. You can leave the Importance field as 1.
    Figure 7. Start defining the goal for MQGOLD based on response time with percentile
    Start defining the goal for MQGOLD based on response time with percentile
    Figure 8. Set goal to be 90% of messages processed within 0.1 second
    Set goal to be 90% of messages processed within 0.1 second
    Figure 9. The Service Class and goal are now defined for GOLD messages
    The Service Class and goal are now defined for GOLD messages

Repeat these steps for MQSILVER and MQBRONZE with suitable goals. Figure 10 shows that the three service classes are now defined:

Figure 10. MQGOLD, MQSILVER, MQBRONZE service classes are now defined
MQGOLD, MQSILVER, MQBRONZE service classes are now defined

Defining Component Broker (CB) classification rules

Next we need to create the CB classification rules. These rules essentially link the transaction classes (TC_1, TC_2, TC_3) with the service classes (MQGOLD, MQSILVER, MQBRONZE).

  1. From the WLM Policy menu (see Figure 4) select (6) Classification Rules. Choose any existing rule to create the new CB classification rules (see Figure 11):
    Figure 11. Select any existing rule to create a new CB classification rule
    Select any existing rule to create a new CB classification rule
  2. Within the Classification Rule definition screen (Figure 12) define the Subsystem Type as CB. This step requires a default service class, for which messages of unknown priority type can be assigned. Set this class to MQBRONZE for our example. Place an I under Action for each of the three transaction classes to associate each transaction class name with their respective service class. Set the Type to bTC.
    Figure 12. Define the three CB classification rules
    Define the three CB classification rules

    Figure 13 shows the new set of CB classification rules.

    Figure 13. The new set of CB Classification Rules have been defined
    The new set of CB Classification Rules have been defined
  3. Exit the zWLM function configuration, and select(2) Install definition on WLM couple data set and continue to install all the changes to the system.

Conclusion

We’ve completed configuration of the system for a basic setup to enable priority message processing and workload management using the MQ resource adapter and the zWLM function across multiple servant regions. This configuration included:

  • The JMS client application for WebSphere MQ
  • The classification rules xml
  • Transaction classes
  • The Application Server configuration
  • Service classes
  • CB classification rules

When the JMS client application for MQ sends messages (for example to a MQ queue for consumption by MDBs running in WebSphere Application Server), it initiates three servant regions. Each servant region will have instances of the MDBs running within it and process (consume) messages from the MQ queue based on the messages priority type. So, all GOLD messages will be processed within servant region1, all SILVER within servant region2 and BRONZE in servant region3. In addition, if there is competition for system resources, GOLD messages will take priority over SILVER and BRONZE due to the transaction goal specified in its service class.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=350782
ArticleTitle=Using z/OS workload management with the WebSphere MQ resource adapter in WebSphere Application Server V7
publish-date=11122008