This section lists and describes other functions that you can use in iWay Service Manager.
The _eval() function evaluates a string as an expression of the function. This function uses the following format:
_eval(expression [,tracemsg [,level]])
expression | string | The string to be evaluated. |
tracemsg | string | A trace message to be issued when the expression is evaluated. |
level | keyword | The trace level specified for the tracemsg attribute. The following trace levels are supported:
|
A common use of the _eval() function is to store a complex expression in a file. The expression can be used by _eval(_file(<path>)). Assume that the file /myfilescfg.txt contains the simple expression _sreg('iway.config','none'). If the _file('/myfilescfg.txt') function is used alone, then the value will be _sreg('iway.config','none'), the value in the file. However, by using the _eval() function, the _sreg() is evaluated and the result is the name of the configuration in which the server is running.
An optional tracing service adds a message at the specified trace level (if enabled) to the current trace log. This is useful for debugging the value to be output by this function. By including the special token (%v) in the trace message, the expression value can be included in the message. For example:
_eval('file(/holdifl.txt)','eval got %v','deep')
The _log() function writes a message to the trace log. This function uses the following format:
_log(tracemsg [,level] [,expression]])
tracemsg | string | A trace message to be issued when the expression is evaluated. |
level | keyword | The trace level specified for the tracemsg attribute. The following trace levels are supported:
|
expression | iFL | An iFL expression (default is true). |
The tracing service adds a message at the specified trace level (if enabled). This is useful for debugging the value to be output by this function. By including the special token (%v) in the trace message, the expression value can be included in the message.
For example, the following function produces the specified message:
_log('Code reached point one','deep')As an additional example, assume that special register (SREG) A contains the value 12345. Consider the following function:
_log('Code reached point one with %v','deep',sreg(a))The output will be:
Code reached point one with 12345
A use of this function is to display intermediate values in a complex iFL expression. The results of the expression are returned as the value of the function. This allows a _log() function to be cascaded in a complicated expression. When used with a third parameter (the iFL expression), the function is idempotent.
The _log() function differs from the _eval() function in that _eval() is designed to construct the expression to be evaluated. An example is to read an iFL expression from a file and then execute it at runtime. The _log() function does not perform the delayed evaluation, rather the expression is simply part of the overall iFL to be evaluated.
The _cond() function uses the following format:
_cond(expression,operator [,operand])
function | string | First operand. |
operator | string | Operator to be applied. |
operand | string | Operand for comparison operators. |
The first parameter is a string, often obtained from some other function. This value is operated upon as ordered by the second parameter, possibly using the optional third parameter to complete the test. The result of _cond() is true or false.
Operator | Purpose | Value Used |
eq, =, == | Pure equality. Strings are compared case sensitively. | Yes |
eqc | Equality, case-insensitive. | Yes |
ne, != | Not equals. | Yes |
lt, < | Less than, numeric, or lexical. | Yes |
gt, > | Greater than, numeric, or lexical. | Yes |
le, <= | Less than or equals, numeric, or lexical. | Yes |
ge, >= | Greater than or equals, numeric, or lexical. | Yes |
istrue | Returns true if the result of the expression is true. | No |
isfalse | Returns true if the result of the expression is false. | No |
isempty | Returns true if the result of the expression exists but has no value. This is useful for testing the return from an xpath operation. | No |
isnotempty | Returns true if the result of the expression exists and has a value. This is useful for testing the return from an xpath operation. | No |
isnull | Returns true if the result of the expression does not exist. | No |
isnotnull | Returns true if the result of the expression exists. | No |
_xquery(expression)
expression | string | Expression in XQuery language. |
The _xquery() function is used to evaluate an XQuery 1.0 expression against the current document. XQuery can be used to select portions of the document and to compute new values in powerful ways. The result is the return value of the function.
The XQuery language is documented in XQuery 1.0: An XML Query Language available at http://www.w3.org/TR/xquery/. Notice XQuery 1.0 is a strict superset of XPath 2.0.
The expression argument is treated as a special literal. Functional replacement is performed by iFL but math operations, quotes, and top-level commas are ignored. This makes it easier to pass non-alphanumeric characters to the XQuery interpreter.
The result of evaluating an XQuery expression is a result sequence. The return value of _xquery() is the value of each result sequence item separated by |.
For example, when the expression _xquery(//e[@a="1"]) is applied to the following document:
<root> <e a="1">one</e> <e a="1">uno</e> <e a="2">two</e> </root>
the result is “one|uno”. Notice how the XQuery expression does not need special quoting.
Functional replacement is applied before the XQuery interpreter is called. For example, assume the special register reg1 has the value 1, then the expression:
_xquery(//e[@a="sreg(reg1)"])
returns the same value as the previous expression when applied to the same document.
An XQuery expression can declare variables to be external. For example, the following expression declares the external variables $v1:
_xquery(declare variable $v1 external; //e[@a=$v1])
The initial value of an external variable is the value of the special register with the same local name. For example, the last expression returns the same result as the previous examples when the special register v1 has the value 1. An external variable may be declared in a namespace. The namespace is ignored when choosing the special register name. For example, the special register corresponding to the external variable $ns:v2 is simply v2.
The _fileexists() function uses the following format:
_fileexists(path)
path | string | Path to file. |
At attempt is made to determine whether the file exists. If the filename is a literal or is resolved as a literal (such as the contents of a special register), that file name is used. If the parameter is a file() function, the file name as resolved for the file function is used, not the contents of the file. To test for a name in a file, use the _eval() function to evaluate the file operation.
For example, is special register fname holds a file name,
_fileexists(sreg(fname))
returns true if the file exists, else false.
The _file() function uses the following format:
_file(path, [,default[,encoding]])
path | string | Path to the desired file. |
default | string | Value to be returned if the file does not exist. |
encoding | string | IANA encoding. |
The specified file is loaded and returned. If encoding is specified, the file is considered to be encoded in the specified IANA encoding. If omitted, the default file system encoding is assumed.
The special encoding of base64 will return the contents of the file encoded in base64. This is especially useful when contents of files, such as PDFs, are to be included as XML values. Placing an _file() function in the XML document and then using the Tree Evaluator Service (com.ibi.agents.EvalWalk) will perform the inclusion.
For example:
_file('/mydoc.pdf',,'base64')
The _exists() function uses the following format:
_exists(statement)
statement | string | XPATH statement of other object. |
An attempt is made to determine whether the object exists. If the path parameter starts with a /, this is presumed to be an xpath expression and if the statement locates a value this function returns true.
Otherwise, the object is assumed to be some other internal object such as a special register, and its existence is tested.
The _exists1() function uses the following format:
_exists1(expression [,nsmap [,object]])
expression | string | Expression in xpath language. |
nsmap | string | Name of a namespace map from a provider. If omitted, no namespace map is applied. |
object | document | A document to which xpath is applied. If omitted, the current document is evaluated. |
An attempt is made to determine whether the object exists. If the path parameter starts with a /, this is presumed to be an xpath expression and if the statement locates a value this function returns true.
Otherwise, the object is assumed to be some other internal object such as a special register, and its existence is tested. The use of the parameters is as described in the xpath() function. Exists1() is compatible with xpath1() which is the full xpath(). Use of standard xpath() functions is recommended over use of the _exists1() function.
_iwexists(statement)
statement | string | XPATH statement of other object. |
An attempt is made to determine whether the object exists. If the path parameter starts with a /, this is presumed to be an xpath expression and if the statement locates a value this function returns true.
Otherwise the object is assumed to be some other internal object such as a special register, and its existence is tested.
Use the _fileexists() function to test for the existence of a file. Use the _exists() function to test with full xpath.
The _ldap() function uses the following format:
_ldap(filter, attribute[[,context], provider])
filter | string | Search filter in the LDAP. |
attribute | string | Attribute to be accessed from the repository. |
context | string | Context to be applied to the search. |
provider | string | Name of any LDAP provider |
The value of the attribute is loaded from the LDAP. Some servers support only a single LDAP directory specification (URL, access ID, password) and this default LDAP directory is used to satisfy this function. Some servers support multiple LDAP providers. In this case, the optional provider name can be supplied.
For example, Dick Beck is a member of the corporate group (in LDAP terms the Organizational Unit). A call to look up his telephone number might be as follows:
LDAP('CN=Beck, Dick',phoneNumber,'ou=COR')The actual format of the function call will depend upon the schema used to organize the directory.
The _if() function uses the following format:
_if(test [, trueclause [,falseclause]])
test | condition | A conditional test, such as sreg(abc)<6 or _fileexists('c:/abc.txt). |
trueclause | string | A value to return if the test condition evaluates to true. |
falseclause | string | A value to return if the test condition evaluates to false. If omitted, an empty value is returned. |
The test is evaluated, If the test results in a true condition, the true clause is returned, else the false clause is returned. This is useful to set a value in a configuration based on a test.
The clauses can themselves be tests. For example, imagine two special registers, aa and bb each holding a value. The following expression is legal:
_if(sreg(aa)<8,_if(sreg(bb)=9,'tt','tf'),'f')
If the test is not followed by a trueclause or falseclause, the function returns the tokens true or false. For example, assume that special register t1 contains 15, then the following returns as true:
_if(sreg(t1)<20)
_lock(lockname, value)
lockname | string | Name of the lock under which the value is computed and returned. |
value | string | The value to be returned. |
The value is determined while the named lock is held. This function is designed for use in returning values of metrics which hold statistics. The lock name should be the same as the lock name under which the metrics are computed by the XDSREGAgent.
Metrics can be referenced as special registers. The lock is desirable when one or more of the registers might be changed by an XDSREGAgent while the value of that register is being accessed to compute the value.
_lock('my.lock',_if(sreg(aa)<8,_if(sreg(bb)=9,'tt','tf'),'f'))Used only in COND(), ALL(), and ANY() functions. Makes the right comparator a list. For example, consider the sample document:
<root> <child>4</child> <child>2.3</child> <child>1</child> </root>
The following expression returns 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.
One value is returned from the JDBC data source identified by the provider. The statement is expected to be an SQL select statement, or a {call} statement. It in turn is expected to return a single value. If the statement returns multiple rows, only the first row is accessed. If the statement returns multiple fields, only the first is returned. These situations are not considered errors.
The _jdbc() function uses the following format:
_jdbc(provider, statement [,timeout])
This function is useful for extracting a value from a table with keys. For example:
key | value |
|---|---|
one | first |
two | second |
Now assume a special register named sequence which holds ‘one’ or ‘two’. The following function statement will return the correct value:
_jdbc(provname,_sql(select value from table where key = _sreg(sequence)))
Note the use of the _sql() function to assist in the analysis of the statement. This is not necessary unless iWay functions are used in the expression.
The _unq() function uses the following format:
_unq(pattern)
pattern | string | Descriptive pattern |
Returns a unique identifier within the bounds of the supported pattern. A pattern consists of literal characters, such as ID, plus trigger characters that are replaced with values by the server. The supported trigger values are:
Character | Use | Restriction |
# | Stored digit | None |
^ | Unstored digit | None |
* | Current timestamp in RFC 1123 format with non-path characters removed. | One per pattern |
Stored digits survive the restart of the server, while unstored digits are reset to zero each time the server starts. The number of pattern digits defines the modulus of the generated number. For example, a pattern of ab### returns ab001, ab002…ab999. The function then returns ab001 on the next call.
The pattern support is identical to that used for unique file names in other server configuration parameters.
Returns a UUID (Universally Unique Identifier), also known as GUIDs (Globally Unique Identifier) meeting the requirements of RFC 4122. A UUID is 128 bits long, and is guaranteed to be unique across space and time. The method of generation leverages the unique values of IEEE 802 MAC addresses to guarantee uniqueness. The optional code parameter controls the format of the generated result.
The _uuid() function uses the following format:
_uuid([code])
Code | Use | Example |
|---|---|---|
none, 0 or standard | Display format. | d71648c0-1485-11dc-a269-0019b92fe248 |
1 or compressed | Compressed format. | 3e2246d0148211dc957b0019b92fe248 |
The _savedoc() function allows the current document and (optionally) its state to be held while the document is changed for some purpose. The current document is the document flowing through the process flow at any moment. The _restoredoc() function is used to return the current document to the value set when it was stored in the register. Registers holding documents will not be marshaled for exchange through the gateway (RVI) or passed to an internal channel. The save and restore sequence should not be used across threads in the process flow.
The _savedoc() function is especially useful during pre- and post-service execution in process flows.
Note: Since saving a document requires memory, this facility should be used with caution to avoid an impact on performance.
The _savedoc() function uses the following format:
_savedoc(name, {action} [,scope] [,serialization)name | string | Name of a special register to hold the saved information. |
action | keyword | Determines what data should be saved for later restoration. For more information on how to recover the saved document information, see _restoredoc(): Restore a Saved Document. |
scope | keyword | The scope of the specified register. The query on the former value is performed at this scope. The following scopes are supported:
|
serialization | keyword | Determines how the saved data is stored. Specify one of the following settings:
|
Specifying a local scope requires the restore of the data (_restoredoc()) to be on the edge line on which the data was saved, or an edge that descends from the edge. Specifying flow or message scopes allows the _restoredoc() function to be used on another thread line, or even in a subsequent stage of the message handling. Use of these scopes requires careful management of the edge execution (thread management) to ensure that the data was saved before it is restored. As a best practice, specifying local scope is recommended.
Serialization settings provide a balance between memory and performance. Specifying the internal setting (default) causes the data to be held in memory. For very large documents that are to be saved, specifying the external setting causes the data to be held on a disk. This reduces memory use at the cost of significant use of system resources and time to exchange the data with the disk storage. The system maintains the disk storage and the data is only available to the _restoredoc() function.
Example 1. To save the current message:
_savedoc('docpoint1','document')Example 2. To save the payload to disk on the local scope:
_savedoc('docpoint1','payload',,'external')Example 3. If you are running more than 10 messages on the channel use external media, otherwise use memory:
_savedoc('docpoint1','document',,_if(_chaninfo(*,'active')>10,'external','internal'))
The _restoredoc() function is designed to be paired with a _savedoc() function that saves a current document or its payload. Using the _savedoc() and _restoredoc() functions provides an efficient means of holding the current document while other operations change the document, and then restoring the current document to its saved state. The _restoredoc() function will restore the entire document or the payload, depending on how the save was performed by the _savedoc() function.
The _restoredoc() function uses the following format:
_restoredoc(name [,disposition])
name | string | Name of the register holding the information that is saved by the _savedoc() function. |
disposition | keyword | An optional action that can be taken after the document is restored. Select one of the following actions:
|
The _restoredoc() function is especially useful during pre- or post-service execution in process flows, or as a clause of an _if() function.
If the data was saved to external media by the _savedoc() function, specifying the keep action prevents the file from being deleted. Specifying the clear action causes the file to be deleted after the restoration. In either case, the file is deleted when the server terminates.
| iWay Software |