Workload classification file

The workload classification document is a common XML file that classifies inbound HTTP, IIOP, message-driven bean (MDB), and mediation work for the z/OS workload manager.

Usage notes

You must perform the task Classifying z/OS workload when you use the workload classification document. See Sample z/OS workload classification document for an example of a workload classification document.

Required elements

<?xml version="1.0" encoding="UTF-8"?>
Indicates that the workload classification document must be saved in ASCII to be processed by the application server. This statement is required.
<!DOCTYPE Classification SYSTEM "Classifications">
Gives the XML parser with the name of the DTD document provided by WebSphere Application Server for z/OS that validates the workload classification document. The workload classification document that you write must follow the rules that are described in this DTD. You must add this statement to the workload classification document.
Classification
<Classification schema_version="1.0">

Indicates the root of the workload classification document. Every workload classification document must begin and end with this element. The schema_version attribute is required. The only supported schema_version is 1.0. The Classification element contains one or more InboundClassification elements. For inbound service integration work, the Classification element can also contain up to two SibClassification elements.

InboundClassification
<InboundClassification type="iiop | http | mdb" schema_version="1.0" default_transaction_class="value">

Use the following rules when using the InboundClassification element:

  • The type attribute is required. The value must be internal, iiop, http, or mdb. Only one occurrence of an InboundClassification element can occur in the document for each type. There can be up to four InboundClassification elements in a document. The types do not have to be specified in a certain order in your classification document.
  • The schema_version attribute is required. The value must be set to 1.0.
  • The default_transaction_class attribute must be specified, and defines the default transaction class for work flows of the specified type. The string value must be a valid WLM transaction class, a null string (such as "") or a string that contains eight or fewer blanks (such as " ").
  • The InboundClassification elements cannot be nested. Each InboundClassification element must end before the next InboundClassification element or SibClassification element can begin.
SibClassification
<SibClassification type="jmsra | destinationmediation" schema_version="1.0" default_transaction_class="value">

Use the following rules when using the SibClassification element:

  • The type attribute is required. The value must be jmsra or destinationmediation. There can be at most one SibClassification element in the document for each type. The types do not have to be specified in a certain order in your classification document.
  • The schema_version attribute is required. The value must be set to 1.0.
  • The default_transaction_class attribute must be specified, and defines the default transaction class for work flows of the specified type. The string value must be a valid WLM transaction class, a null string (such as "") or a string that contains eight or fewer blanks (such as " ").
  • The SibClassification elements cannot be nested. Each SibClassification element must end before the next InboundClassification element or SibClassification element can begin.
The rules and XML statements for classifying different types of work are very similar, but there is slightly different syntax for each type. For more information about the syntax for each type of work, see the following sections:
InboundClassification
SibClassification

Internal Classification

The InboundClassification element with the attribute type="internal" defines the section of the document that is applicable to internal work, such as requests that are dispatched in a servant, that originate in the owning controller. An example of this element follows:

<InboundClassification 	type="internal" schema_version="1.0" 
                         default_transaction_class="value1">

If an InboundClassification element with the type="internal" attribute is not specified, internal work is classified using the rules that are specified for IIOP work.

IIOP Classification

The InboundClassification element with the attribute type="iiop" defines the section of the document that is applicable to IIOP classification. An example of this element follows:

<InboundClassification 	type="iiop" schema_version="1.0" 
                         default_transaction_class="value1">
You can classify IIOP work based on the following Java 2 Platform, Enterprise Edition (J2EE) application artifacts:
  • Application name

    The name of the application that contains the enterprise beans. It is the display name of the application, which might not be the name of the .ear file that contains all of the artifacts.

  • Module name

    The name of the EJB .jar file that contains one or more enterprise beans. There can be multiple EJB .jar files in an .ear file.

  • Component name

    The name of the EJB that is contained in a module (or EJB .jar file). There can be one or more enterprise beans contained in a .jar file.

  • Method name

    The name of a remote method on an EJB.

Classify IIOP work in various applications at any of these levels by using the iiop_classification_info element.

iiop_classification_info
<iiop_classification_info 	transaction_class="value1"
                          [application_name="value2"]
                          [module_name="value3"]
                          [component_name="value4"]
                          [method_name="value5"]
                          [description="value6"] >
With the iiop_classification_info element, you can build filters based on the application, module, component, and method names to assign TCLASS values to inbound requests. Use the following rules when using the iiop_classification_info element:
  • The transaction_class attribute must be specified. The string value must be a valid WLM transaction class, a null string (such as "") or a string that contains eight or fewer blanks (such as " "). By specifying a null or blank string, you can override a default TCLASS setting, or a TCLASS setting that was assigned by a higher level filter. Specifying a null or blank string means that you do not have a TCLASS value for the request.
  • The attributes application_name, module_name, component_name, and method_name can be used as you need them. These attributes act as selectors or filters that either assign a transaction class or allow a nested iiop_classification_info element to assign the transaction class. You can specify the values of these attributes in the following ways:
    • The exact name of the application, module, component, or method.
    • A wild carded value. You can place an asterisk (*) as the last character in a string to indicate that any string that starts with the string preceding the asterisk is considered a match. For example, the string MAR* matches both MARCH and MARS.

    You can use any combination of these attributes to make a classification filter. But you should only use the granularity that is required. For example, if there is only one application on the application server, the classification rules do not need to specify the application_name attribute.

  • The iiop_classification_info elements can be nested in a hierarchical manner. By nesting the elements, you can create classification filters that are based on the attribute values. The following filter classifies requests on the EJB1 and EJB2 enterprise beans in the MyAPP1 application:
    <iiop_classification_info transaction_class="FAST"
                              application_name="MyAPP1"
                              component_name="EJB1" />
    <iiop_classification_info transaction_class="SLOW"
                              application_name="MyAPP1"
                              component_name="EJB2" />
    The following filter also classifies requests on EJB1 and EJB2 in the MyAPP1 application, but also classifies requests on any other EJB in the application:
    <iiop_classification_info transaction_class="MEDIUM"
                              application_name="MyAPP1">
         <iiop_classification_info transaction_class="FAST"
                                   component_name="EJB1" />
         <iiop_classification_info transaction_class="SLOW"
                                   component_name="EJB2" />
    </iiop_classification_info>
  • If you specify an attribute value that conflicts with the parent element's attribute value, the lower level filter is negated. An example of a child value that conflicts with the parent element's attribute value follows:
    <iiop_classification_info transaction_class="FAST"
                              application_name="MyAPP1">
         <iiop_classification_info transaction_class="SLOW"
                                   application_name="MyAPP2" />
    </iiop_classification_info>
    In this example, EJB Requests in MyAPP2 would never be assigned to transaction class "SLOW" because the higher level filter only allows IIOP requests for application_name="MyAPP1" to be passed through to the lower level filter.
  • The first filter at a specific level that matches the attributes of the request is used, not the best or most restrictive filter. Therefore, the order that you specify filters is important.
    <iiop_classification_info transaction_class="FAST"
                              application_name="MyAPP" />
         <iiop_classification_info transaction_class="SLOW"
                                   component_name="*" />
         <iiop_classification_info transaction_class="MEDIUM"
                                   component_name="MySSB" />
    </iiop_classification_info>								
    In the preceding example, all the IIOP requests that are processed by enterprise beans in the MyAPP application are assigned a TCLASS value of SLOW. This is true for any requests to the MySSB enterprise as well. Even though MySSB is assigned a transaction class, the filter is not applied because the first filter was applied and was assigned a TCLASS value of SLOW. The remaining list of filters at the same level is ignored.
  • The description field is optional. However, you should use a description on all iiop_classification_info elements. The description string prints as part of the operator command support so you can identify the classification rules that are being used. Keep your descriptions reasonably short because they are displayed in the MVS console.

HTTP classification

The InboundClassification element with the attribute type="http" defines the section of the document that is applicable to HTTP classification. An example of this element follows:

<InboundClassification  	type="http"
                        schema_version="1.0"
                        default_transaction_class="value1">
HTTP work can be classified based on the following J2EE artifacts:
  • Virtual host name

    Specifies the host name in the HTTP header to which the inbound request is being sent.

  • Port number

    Specifies the port on which the HTTP catcher is listening.

  • URI (Uniform Resource Identifier)

    The string that identifies the Web application.

You can classify HTTP work in various applications at any of these levels by using the http_classification_info element.
<http_classification_info transaction_class="value1"
                          [host="value2"]
                          [port="value3"]
                          [uri="value4"]
                          [description="value5"] >
With the http_classification_info element, you can build filters based on the host, port, and URI to assign TCLASS values to inbound requests. Use the following rules when you use the http_classification_info element:
  • The transaction_class attribute must be specified. The string value must be a valid WLM transaction class, a null string (such as "") or a string that contains eight or fewer blanks (such as " "). By specifying a null or blank string, you can override a default TCLASS setting, or a TCLASS setting that was assigned by a higher level filter. Specifying a null or blank string means that you do not have a TCLASS value for the request.
  • The attributes host, port, and uri can be used as you need them. These attributes act as selectors or filters that either assign a transaction class or allow a nested http_classification_info element to assign the transaction class. You can specify the values of these attributes in the following ways:
    • The exact name of the host, port, or uri.
    • A wild carded value. You can use an asterisk (*) to match strings. The string MAY* matches any string that starts with MAY.
    • Any value. To specify a match to any value, use the asterisk (*) symbol.
    Use any or all of these attributes to make a classification filter. Only use the granularity that is required. For example, if there is only one application on the application server, the classification rules do not need to specify the uri attribute.
  • You can nest the http_classification_info elements in a hierarchical manner. You can construct filters based on attribute names. Consider the two following filters:
    <http_classification_info transaction_class="FAST"
                              host="MyVHost1.com"
                              uri="/MyWebApp1/*" />
    <http_classification_info transaction_class="SLOW"
                              host="MyVHost2.com"
                              uri="/MyWebApp2/*" />
    <http_classification_info transaction_class="MEDIUM"
                              host="MyVHost1.com">
         <http_classification_info transaction_class="FAST"
                                   uri="/MyWebApp1/*" />
         <http_classification_info transaction_class="SLOW"
                                   uri="/MyWebApp2/*" />
    </http_classification_info>
    Both filters classify requests to Web applications that are identified by context roots /MyWebApp1 and /MyWebApp2 in the application server that is hosting web applications for virtual host MyVHost1.com. However, the second filter also classifies requests on any other context root in the application server.
  • Specifying an attribute name that is different from the parent element's attribute value effectively negates the lower level filter. For example:
    <http_classification_info transaction_class="FAST"
                              uri="/MyWebApp1/*">
         <http_classification_info transaction_class="SLOW"
                                   uri="/MyWebApp2">
         </http_classification_info>
    </http_classification_info>
    This example would never result in Web applications with a context root of /MyWebApp2 being assigned to the transaction class SLOW. The high level filter only allows HTTP requests with a context root of /MyWebApp1/* to be passed to a lower level filter.
  • The first filter that is at a specific level is used, not the best or most restrictive filter. Therefore, the order of the filters at each level is important. For example:
    <http_classification_info transaction_class="FAST"
                              host="MyVHost.com" />
         <http_classification_info transaction_class="SLOW"
                                   uri="*" />
         <http_classification_info transaction_class="MEDIUM"
                                   uri="/MyWebAppX/*" />
    </http_classification_info>
    In this example, HTTP requests processed by the application server by the virtual host "MyVHost.com" are assigned a TCLASS value of SLOW. Even requests to the Web application with context root /MyWebAppX are assigned a TCLASS value of SLOW because the filter was not applied. The first filter that matches is used for the TCLASS assignment, and the remainder of the filters at the same level is ignored.
  • The description field is optional, however, you should use it on all the http_classification_info elements. The description is displayed when you monitor the transaction classes in the MVS console.

MDB classification

The InboundClassification element with the attribute type="mdb" defines the section of the document that applies to work for EJB 2.0 message-driven beans (MDBs) deployed with listener ports. An example of this element follows:
<InboundClassification  type="mdb"
                        schema_version="1.0"
                        default_transaction_class="qrs">
Each InboundClassification element can contain one or more endpoint elements with a messagelistenerport type defined. Define one endpoint element for each listener port that is defined in the server that you want to associate transaction classes with the message-driven bean. An example of the endpoint element follows:
<endpoint  type="messagelistenerport" 
           name="IPVListenerPort" 
           defaultclassification="MDBX"
           description="ABC">
Use the following rules when defining your endpoint elements:
  • The type attribute must always equal messagelistenerport.
  • The name attribute corresponds to the listener for your endpoint element. The value of the name attribute must be the name of the listener port that is specified in the administration console for the server.
  • The defaultclassification element is the default transaction class that is associated with the message-driven beans. The value of this attribute overrides the default transaction classification value.
  • The description field is optional, however, you should use it on all the endpoint elements. The description is displayed when you monitor the transaction classes in the MVS console.
Each endpoint element can have zero, one, or more classificationentry elements. An example of a classification entry element follows:
<classificationentry  
selector="Location=&apos;East&apos;"
                      classification="MDB2"
                      description="XYZ" />
Use the selector attribute of the classificationentry element to assign a transaction class to a message-driven bean that has a selector clause in its deployment descriptor. Use the following rules when defining your classificationentry elements:
  • The value of the selector attribute must match exactly to the selector clause in the MDB deployment descriptor.
  • The value of the selector attribute must have the correct syntax for an XML document. You must replace the < and > symbols with the entity references &lt; and &gt;, respectively. Similarly, if you use an apostrophe or quotation mark, use the &apos; and &quot; entity references.

JMS RA classification

The SibClassification element with the attribute type="jmsra" defines the section of the document that applies to work for message-driven beans (MDBs) deployed against JCA 1.5-compliant resources for use with the JCA resource adapter (RA) of the default messaging provider. An example of this element follows:
<SibClassification  type="jmsra"
                        schema_version="1.0"
                        default_transaction_class="a">
Each SibClassification element can contain one or more sib_classification_info elements. An example of a classification entry element follows:
<sib_classification_info  selector="&apos;East&apos;"
                      transaction_class="sibb"
                      selector="user.Location=&apos;East&apos;"
                      bus="bigrred"
                      destination="abusqueue"
                      description="Some words" />
selector
Use the selector attribute of the sib_classification_info element to assign a transaction class to a message-driven bean that has a selector clause in its deployment descriptor. Use the following rules when defining your sib_classification_info elements:
  • The value of the selector attribute is an SQL expression that selects a message according to the values of the message properties. The syntax is that of a message selector in the JMS 1.1 specification, but it can operate on SIMessage messages (more than JMS messages). The syntax can select on system properties (including JMS headers, JMSX properties, and JMS_IBM_properties) and user properties (which must be prefixed by ".user" - for example, for the user property "Location", the selector would specify "user.Location" as shown in the preceding example). For more information, see Working with the message properties.
  • The value of the selector attribute must have the correct syntax for an XML document. You must replace the < and > symbols with the entity references &lt; and &gt;, respectively. Similarly, if you use an apostrophe or quotation mark, use the &apos; and &quot; entity references.
bus
The name of the service integration bus on which the target destination is assigned. The classification applies to the bus named by this property, or to any bus if you do not specify this property. The destinations to which the classification applies depend on your use of the destination property.
destination
The name of the target bus destination to which the message has been delivered. This is the name of a queue or topic space. The classification applies to the destination named by this property, or any destination if you do not specify this property. The service integration buses to which the classification applies depend on your use of the bus property.
discriminator
The property applies only when the destination property names a topic space. This discriminator value is then an XPath expression that selects one or more topics within the topic space.
description
Although the description field is optional, you should use it on all the sib_classification_info elements. The description is displayed when you monitor the transaction classes in the MVS console.

Each sib_classification_info element can contain one or more of these properties as needed to classify the work for a message. A sib_classification_info element cannot contain more than one instance of each property.

If a message matches several sib_classification_info elements, the element that appears first is used. For example, consider the following specifications:
<sib_classification_info bus="MyBus" transaction_class="a" />
<sib_classification_info destination="MyDest" transaction_class="b" />
A message that arrives at destination MyDest from the service integration bus MyBus is assigned the classification "a". A message that arrives at MyDest from another bus is assigned the classification "b".

If a message does not match any sib_classification_info element in an enclosing SibClassification element, the message is assigned the default classification from the SibClassification element.

If a message does not match any sib_classification_info element in any SibClassification element, or if no SibClassification elements are defined, all work receives a built-in default classification with the value "SIBUS". You must perform z/OS Workload Manager actions that are required to use the TCLASS value "SIBUS", as described in Classifying z/OS workload.

Mediation classification

The SibClassification element with the attribute type="destinationmediation" defines the section of the document that applies to work for mediations assigned to destinations on a service integration bus. An example of this element follows:
    <SibClassification type="destinationmediation"
                        schema_version="1.0"
                        default_transaction_class="b">
Each SibClassification element can contain one or more sib_classification_info elements. An example of a classification entry element follows:
<sib_classification_info
                      transaction_class="e"
                      selector="user.Location=&apos;East&apos;"
                      destination="themoon"
                      discriminator="sides/dark" 
                      description="n" />
selector
Use the selector attribute of the sib_classification_info element to assign a transaction class to a mediation that has a selector clause in its deployment descriptor. Use the following rules when defining your sib_classification_info elements:
  • The value of the selector attribute is an SQL expression that selects a message according to the values of the message properties. The syntax is that of a message selector in the JMS 1.1 specification, but it can operate on SIMessage messages (more than JMS messages). The syntax can select on system properties (including JMS headers, JMSX properties, and JMS_IBM_properties) and user properties (which must be prefixed by ".user" - for example, for the user property "Location", the selector would specify "user.Location" as shown in the preceding example).

    For more information, see Working with the message properties.

  • The value of the selector attribute must have the correct syntax for an XML document. You must replace the < and > symbols with the entity references &lt; and &gt;, respectively. Similarly, if you use an apostrophe or quotation mark, use the &apos; and &quot; entity references.
bus
The name of the service integration bus on which the target destination is assigned. The classification applies to the bus named by this property, or to any bus if you do not specify this property. The destinations to which the classification applies depend on your use of the destination property.
destination
The name of the target bus destination to which the message has been delivered. This is the name of a queue or topic space. The classification applies to the destination named by this property, or any destination if you do not specify this property. The service integration buses to which the classification applies depend on your use of the bus property.
discriminator
The property applies only when the destination property names a topic space. This discriminator value is then an XPath expression that selects one or more topics within the topic space.
description
Although the description field is optional, you should use it on all the sib_classification_info elements. The description is displayed when you monitor the transaction classes in the MVS console.

Each sib_classification_info element can contain one or more of these properties as needed to classify the work for a message. A sib_classification_info element cannot contain more than one instance of each property.

If a message matches several sib_classification_info elements, the element that appears first is used. For example, consider the following specifications:
<sib_classification_info transaction_class="e" destination="themoon" description="n" />
<sib_classification_info transaction_class="f" description="n" />
A message that arrives at the mediated destination themoon is assigned the classification "e". A message that arrives at another mediated destination is assigned the classification "f".

If a message does not match any sib_classification_info element in an enclosing SibClassification element, the message is assigned the default classification from the SibClassification element.

If a message does not match any sib_classification_info element in any SibClassification element, or if no SibClassification elements are defined, all work receives a built-in default classification with the value "SIBUS". You must perform z/OS Workload Manager actions that are required to use the TCLASS value "SIBUS", as described in Classifying z/OS workload.




Related concepts
Workload management (WLM) for z/OS
Related tasks
Classifying z/OS workload
Related reference
Sample z/OS workload classification document
Reference topic Reference topic    

Terms and conditions for information centers | Feedback

Last updatedLast updated: Aug 31, 2013 12:02:36 AM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=pix&product=was-nd-zos&topic=rrun_wlm_tclass_dtd
File name: rrun_wlm_tclass_dtd.html