Other Functions

_eval(): Evaluate a String

The _eval() function can be used to evaluate a string as a function expression. It uses the following format:

_eval(function)

function

string

String to be evaluated

A common use is to store a complex expression in a file. The expression can be used by _eval(_file(<path>)). Assume the file "/myfilescfg.txt" contains the simple expression "_sreg('iway.config','none')". If the _file('/myfilescfg.txt') function is used alone, 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.

_cond(): Perform Conditional Test

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 is 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 is 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

_fileexists(): Does file exist

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.

_file():Get File Contents

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.

_exists(): Does Value Exist

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.

_exists1(): Does Value Exist

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(): Does value exist

_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 objectvis 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.

_ldap(): Get LDAP Contents

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.

_if(): Obtain Value Conditionally

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 calue 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(): Obtain Value Under Lock

_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'))OR(item[,item*])

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.

_jdbc(): Get A Relational Value from a Table

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.

_unq(): Generate a Unique Identifier

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.

_uuid(): Generate a Unique Identifier

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

lockname	string	Name of the lock under which the value is computed and returned.
value	string	The value to be returned.