Section 5 - File Formats, Data Descriptions, MIBs, and System Processes Reference

File Formats, Data Descriptions, MIBs, and System Processes Reference

ROUTING Section

This section provides information for data-dependent routing of service requests using FML buffers, XML buffers, and views. The routing criteria specified here are used only if the default routing functions _froute, _xroute, and _vroute, are being used (see tuxtypes(5)). Lines within the ROUTING section have the form:

ROUTING_CRITERIA_NAME required_parameters

where ROUTING_CRITERIA_NAME is the (string_value) name assigned to the ROUTING parameter for a particular service entry in the SERVICES section. ROUTING_CRITERIA_NAME must be 15 characters or less in length.

Required parameters are:

FIELD = string_value

Specifies the name of the routing field. It must be 30 characters or less. This field is assumed to be an FML or FML32 buffer, XML element or element attribute, view field name that is identified in an FML field table (using two environment variables—FLDTBLDIR and FIELDTBLS or FLDTBLDIR32 and FIELDTBLS32), or an FML view table (using two environment variables—VIEWDIR and VIEWFILES or VIEWDIR32 and VIEWFILES32), respectively. This information is used to get the associated field value for data-dependent routing during the sending of a message. If a field in an FML or an FML32 buffer is used for routing, the value of that field must be a number less than or equal to 8191.

To route XML documents on the basis of element content or element attribute, you must define the value of the FIELD parameter with the following syntax:

FIELD="root_element[/child_element][/child_element][/. . .][/@attribute_name]"

The value of FIELD specifies the name of the routing element or an element attribute. This element is assumed to be an element type (or name) or an element attribute name of an XML document or datagram. This information is used to identify the element content or element attribute value for data-dependent routing while sending a document or datagram. The element name and attribute name combined may contain no more than 30 characters. Because indexing is not supported, the BEA Tuxedo system recognizes only the first occurrence of a given element type when processing an XML buffer for data-dependent routing.

XML strictly defines the set of characters that may be used in an attribute name. An attribute name must be a string consisting of a single letter, underscore, or colon followed by one or more name characters. Both element names and attribute names are case-sensitive.

You can find more information about XML on the World Wide Web Consortium Web site at http://www.w3c.org/XML.

FIELDTYPE = type

Indicates the type of routing field specified in the FIELD parameter. This parameter is used only for routing XML buffers. The value type can be set to one of the following: CHAR, SHORT, LONG, FLOAT, DOUBLE, or STRING. The default type of the routing field is STRING.

RANGES = string_value

Specifies the ranges and associated server groups for the routing field. string must be enclosed in double quotes. string can be up to 2048 characters in length (except in Domains, where string can be up to 4096 characters). The format of string is a comma-separated ordered list of range/group_name pairs; for example, RANGES="0-2:DBG1,3-5:DBG2,6-9:"DBG3".

A range is either a single value (signed numeric value or character string in single quotes), or a range of the form "lower - upper" (where lower and upper are both signed numeric values or character strings in single quotes). Note that "lower" must be less than or equal to "upper." To embed a single quote in a character string value (as in O'Brien, for example), it must be preceded by two backslashes ('O\\'Brien'). The value MIN can be used to indicate the minimum value for the data type of the associated FIELD on the machine. The value MAX can be used to indicate the maximum value for the data type of the associated FIELD on the machine. Thus, "MIN - -5" is all numbers less than or equal to -5 and "6 - MAX" is all numbers greater than or equal to 6. The meta-character "*" (wildcard) in the position of a range indicates any values not covered by the other ranges previously seen in the entry; only one wildcard range is allowed per entry and it should be last (ranges following it will be ignored).

The routing field can be of any data type supported in FML. A numeric routing field must have numeric range values, and a string routing field must have string range values.

String range values for string, carray, and character field types must be placed inside a pair of single quotes and cannot be preceded by a sign. Short and long integer values are strings of digits, optionally preceded by a plus or minus sign. Floating point numbers are of the form accepted by the C compiler or atof(3): an optional sign, then a string of digits optionally containing a decimal point, then an optional e or E followed by an optional sign or space, followed by an integer.

The group name indicates the associated group to which the request is routed if the field matches the range. The meta-character "*" (wildcard) indicates that the request goes to the default group if the field value does not match the range or if there is match but no viable server in the group associated with the range entry, the service request is forwarded to the default group specified on the wildcard "*" range entry.

Within a range/group pair, the range is separated from the group name by a ":".

An XML element content and attribute value must be encoded in UTF-8 and can be used for routing if it can be converted to the data type specified by the FIELDTYPE parameter.

When used for routing, the element content cannot contain character references, entity references, or CDATA sections.

An XML attribute value (encoded in UTF-8) can be used for routing if the element to which the attribute belongs is defined.

BUFTYPE = "type1[:subtype1[,subtype2 . . . ]][;type2[:subtype3[, . . . ]]] . . ."

A list of types and subtypes of data buffers for which this routing entry is valid. This parameter can be up to 256 characters in length and a maximum of 32 type/subtype combinations are allowed. The types must be one of the following: FML, FML32, XML, VIEW, VIEW32, X_C_TYPE, or X_COMMON. No subtype can be specified for types FML, FML32, or XML. Subtypes are required for type VIEW, VIEW32, X_C_TYPE, and X_COMMON ("*" is not allowed). Note that subtype names should not contain semicolon, colon, comma, or asterisk characters. Duplicate type/subtype pairs cannot be specified for the same routing criteria name; more than one routing entry can have the same criteria name as long as the type/subtype pairs are unique. This parameter is required. If multiple buffer types are specified for a single routing entry, the data types of the routing field for each buffer type must be the same.

An example of a routing entry is:

BRNCH FIELD=B_FLD RANGES="0-2:DBG1,3-5:DBG2,6-9:DBG3" BUFTYPE="FML"

which sends buffers with field B_FLD values 0-2 to server group DBG1, values 3-5 to server group DBG2, and values 6-9 to DBG3; no other values are allowed.

If the field value is not set (for FML buffers), or does not match any specific range and a wildcard range has not been specified, an error is returned to the application.

An example of a routing entry based on the XML element CODE is:

PRODUCT FIELD="ORDER/CODE" RANGES="'AAA' - 'FFF':DBG1, 'GGG-ZZZ':DBG2" BUFTYPE="XML"

Here, CODE is a child element of the root element ORDER.

A routing entry based on the attribute ORDERNO might look like the following example.

ORDER FIELD="ORDER/HEADER/@ORDERNO" FIELDTYPE=long RANGES="0-9999:DBG1,10000-MAX:DBG3"  BUFTYPE="XML"

Here, ORDERNO is the attribute of the XML child element HEADER of the root element ORDER.