Overview

In this section:

iWay functions enable you to examine the context in which a message is processed and the attributes of that message. You can use the result to determine the subsequent processing steps for the message. You can select, bypass, or modify the steps in the defined process.

For example, you can examine an XML message with XPATH() to extract specific elements of the message that serve as execution parameters. You can check for a schema error, in which case you might route the message differently.

Conditional routing uses functions that either return a Boolean value (true or false) or can, as a result of a relationship test, result in a Boolean condition. If the result is true, the step governed by the conditional routing expression is performed. Otherwise, it is bypassed. For example, if you use an emitter only if a document is in error, you might use the _ISERROR() conditional routing expression.


Top of page

x
Runtime Functions

iWay Service Manager supports a large number of runtime functions that can be used to make routing decisions and supply configuration parameters to iWay components, such as services and listeners. These functions can be combined into expressions, which consist of one or more of the functions that are discussed in this chapter.

Functions fall into several categories:


Top of page

x
Syntax and Usage

Functions are written using the following common computer language format:

name(parms)

Functions return strings that can be used directly or tested for routing purposes.

For example, the following function

 _sreg(<name>,<default>)

returns the value of a specific special register (context value). This value can be used directly as a configuration parameter. For example:

This value can also be tested in a route, such as:

_sreg('iway.config') yields 'base'

More sophisticated checking methods, including mathematical conditions, existence and case insensitive compares, are available through the following special function:

_cond(<value>,operator,<operand>)

For more information on how to use and configure this function, see _cond(): Perform Conditional Test.

Parameters can also include literals, which are sequences of characters, usually enclosed in single quotes. A quote character can be included by escaping it, such as:

_sreg('playwrite','O\'Casey')

The compiler attempts to recognize literals, avoiding the need to use the enclosing quotes. However iWay strongly recommends that functions be written using the enclosing quotes.

All iWay functions begin with the underscore character. Some commonly used functions such as sreg(), xpath(), ldap(), and file() can often be written without the leading underscore. Using the underscore helps prevent ambiguity and is strongly recommended.

Functions can be combined in literal statements. For example, a data path can be:

_sreg('iway.home')/_sreg('iway.config')/etc/data

which will be evaluated to the data subdirectory in the etc subdirectory of the current configuration.

Simple mathematical operations can also be performed by using functions. Supported operations include add, subtract, multiply, divide, and modulus. For example, assume that the special register timeout holds a number of seconds that you want to use in a parameter that requires milliseconds. Specifying the following accomplishes the needed conversion:

_mul(sreg('timeout',0),1000)

To divide a timeout period in half, use the following:

_div(sreg('timeout',0),2)

Division can be accomplished faster by multiplying by the reciprocal of the divisor. For example, to obtain one half of the timeout value in the above example, use the following to yield the desired result:

_mul(sreg('timeout',0),0.5)

The _div and _mul functions are used in place of the traditional slash and asterisk to avoid confusion in file names and unique patterns.

Integer math, especially suitable for date arithmetic functions such as adding a duration to a base date, are available through the _iadd, _isub, _imul, and _idiv functions. Integer math is supported to 16 places of precision. For more information on date arithmetic, see _dateof(): Return the Time Stamp for a Passed Time.

Functions that return Boolean values, such as _isroot() can be combined with AND and OR conjunctions. For example, the expression

 _isroot('a') or _isroot('b') 

returns as true if the current root element name of the document is either a or b. A more complicated test might be:

_isroot('a') or sreg('a')==55

Unary not (!) is supported for tests. For example, if a document is in error, !_iserror() will return as false. The not can be used in combination with other tests, such as _isxml() and !iserror() combines two tests with a logical and condition.



Example: Routing an Output Document

The following example uses the COND() function to route an output document if it is larger than 1000 characters:

COND(_LENGTH(_FLATOF()),GT,1000)


Example: Testing the Result of an Attribute

The following example uses the ALL() function to test the result of each attribute returned from an XPATH expression and to determine if the document is in an error state. If the attribute, ABC, is either TOM or HARRY, or the document is in an error state, routing occurs.

ALL(XPATH(//XX/@ABC), EQ, OR("TOM", "HARRY")) OR _ISERROR()

Top of page

x
Parameter Evaluation

Parameters are evaluated in the standard manner, so that any operators in the parameters are compiled. Evaluation of math symbols can be avoided by enclosing the constant parameters in literal quotes. However, for reasons of simplicity of upward compatibility, this is not often performed. As a convenience, certain functions for which math evaluation of parameters makes little sense do not apply such compilation to their parameters. These include the following:


Top of page

x
Conjunctions

The AND and OR conjunctions allow you to compose expressions that include multiple phrases. For example:

_if(sreg('a') < 15 and sreg('b') = 'hello', 'true', 'false')

AND and OR conjunctions are used only in COND(), ALL(), and ANY() functions, where a list of comparands are being evaluated. For example, consider the following sample document:

<root>
<child>4</child>
<child>2.3</child>
<child>1</child>
</root>

The following expression returns as true:

ANY(XPATH(//child),EQ,OR(5.5,1,7,8))

Programmers refer to this type of comparison as a lazy or. It applies only to the COND(), ALL(), and ANY functions.


Top of page

x
The Functions

Each of the available functions is discussed, along with comments on their syntax and common purpose. Some functions are available only in specific server configurations or with optional components installed. Where such is the case this is stated in the Function Support Table.

Additional functions can be written and included in the function repertory by following the instructions in the iWay Service Manager Programmer's Guide.

The function categories are often arbitrary and are used only for description purposes. The richness of the function may enable it to be used for several purposes. For example, the _sreg() function returns the value of a context special register. Some registers are defined during configuration and some are only defined as a specific document passes through the system.


Top of page

x
Automatic Concatenation

The interpreter attempts to construct values by evaluating the entire string for iFL. It will concatenate the value returned by an evaluated iFL at the point of the function. For example, if the special register partname has a value of xyz, then the string c:/w_sreg(partname)/file.txt will be evaluated to c:/wxyz/file.txt.

In some cases, automatic concatenation can lead to unexpected results. For example, suppose you have a value myfile(fname). Evaluating this can result in an attempt to read load the contents of the fname file, which will result in an error. This can be avoided by treating the statement as a literal and having iFL evaluate it as such. One solution is to place the text in a _concat() function. For example:

_concat('myfile(fname)')

In this case, the desired value is returned. The literal marks (in quotes) prevent the evaluation of the literal itself.


iWay Software