Environmental Functions

_sreg(): Lookup a Special Register

The _sreg() function uses the following format:

_sreg(name [,default])

name	string	Name of the register
default	string	Default value

Special registers contain context information. The information can be configured on the runtime system, reflect the processing state of the current message, or be explicitly set by services in a process flow.

Special registers exist in scopes, and are looked up from the local scope to the outermost scope (the system context). The value returned is that of the nearest scope in which the register is found. If the register is not found in any scope, the default is returned. If the default is not specified, null is returned.

The _sreg() function searches in a case sensitive manner. Consider the following examples:

Register Name	Value	_sreg('a','def1')
a	hello	hello
A	hello	defl

_property(): Retrieve a Value from a Java Property Object File

The _property() function loads the value for the desired property from a Java properties object file. It uses the following format:

_property(file, attribute [, default [,control]] )

file	file name	Path to the properties file.
attribute	string	Name of the desired property.
default	string	Default if property does not exist.
control	string	Keyword to control operation: check. Check for modification. keep. Do not check for modification.

Load the value for the desired property from a Java properties object file. The check control option causes the properties file modification timestamp to be examined on each request. This is to determine whether the file has changed since the last load. If so, the properties file is reloaded. The keep control option prevents this check for cases in which it is known that changes will not be made or should not be loaded. Avoiding the check can result in file read time savings. The keep option is the default.

For example, assume file test.properties contains:

one=first
two=second

The following function call causes the value first to be returned:

_property('test','one','notfound','check')

Next, change the properties file to the following:

one=next
two=second

In this case, the following function call returns next:

_property('test','one','notfound','check')

If the control option is omitted or keep is used, the following function call returns first as before:

_property('test','one','notfound',keep')

_propertymatch(): Match a String Against a File of Regular Expression Patterns

A properties file contains key=value pairs consisting of a regular expression and a value. An input string is matched against the patterns in the properties file, and the value associated with the first pattern to match the input is returned.

The properties file is loaded once, cached for the channel, and is not reloaded for each use. If any changes are made in the properties file, the channel must be restarted to reflect these changes.

The _propertymatch() function uses the following format:

_propertymatch(file,input,[,default [,control [,encoding]]]

file
path
Path to the properties file. The suffix is optional.
input
string
The candidate to be matched against the regular expressions in the properties file.
default
string
The value to be returned if none of the patterns are matched by the candidate input string.
control
keyword
Keyword to control operation:
check. Check for modification.
keep. Do not check for modification.
encoding
string
IANA encoding of the properties file.

The properties file consists of one or more regular expressions (keys), each with an associated value. Standard properties file comments (lines starting with #) and blank lines are allowed. Continuation lines are not supported.

The check control option causes the properties file modification timestamp to be examined on each request to determine whether the file has changed since the last load, and if so the properties file is reloaded. The keep control option prevents this check for cases in which it is known that changes will not be made or should not be loaded. Avoiding the check can result in file read time savings. The keep option is the default.

In the following example, an input ZIP code must be matched to select an appropriate subflow to handle the location. The file stored at /appdata/zip.properties might be structured as follows:

# zip code flow selection file
00.*=zip00
01.*=zip01
10.*=zipnyc
20500=zipwhitehouse
20.*=zipwashdc

Since the patterns are matched in the order specified in the file, the ZIP code for the White House will match before the general Washington D.C. ZIP codes are matched.

Assume that the ZIP code is located in an input document and stored in a Special Register (SREG) called INZIP. The following function call does the matching:

_propertymatch('/appdata.zip',sreg(INZIP),'zipother')

If the INZIP SREG holds 10121, then the function returns zipnyc. If the INZIP SREG holds 11570, then the function returns zipother.

_setreg(): Set a Special Register

The _setreg() function sets the specified special register to the value that is entered and returns the previous value, if any. This function uses the following format:

_setreg(name,value[,type [,scope]])

name	string	The name of the register.
value	string	The value to be set.
type	keyword	The register type. The following types are supported: user (default). The user register, which is a simple value. doc. The document-related value. hdr. The header value, which is serialized by appropriate protocols when emitted. delete. Eliminates the specified register.
scope	keyword	The scope of the specified register. The query on the former value is performed at this scope. The following scopes are supported: local (default). The scope is the local register context. flow. The scope is the head of the flow. message. The scope is the message.

Use caution with the _setreg() function, since this function can change the contents of the local special register manager.

The selected scope must be appropriate to the context in which the function is used. For example, a flow scope is not present in non-flow contexts.

When deleting a register, the delete takes place at the identified scope. Registers are normally looked up by the nearest scope, so the register may continue to exist at lower scopes. This function can be used effectively as an operand of the _if() function.

If you need to set multiple registers in parallel, you can consider using the _concat() function. The following example sets registers ra and rb if register rt is true:

_if(sreg('rt')='true',_concat(_setreg('ra','1'),_setreg('rb','2'))

If you are setting multiple registers using this technique, then you may need to consider the _lock() function as a part of the setting clause. For example:

_lock('lock1',_concat(,_concat(_setreg('ra','1'),_setreg('rb','2')))

The value parameter is not recommended to be a literal value, but rather a function to obtain the value, such as _xpath() or _jdbc().

file	path	Path to the properties file. The suffix is optional.
input	string	The candidate to be matched against the regular expressions in the properties file.
default	string	The value to be returned if none of the patterns are matched by the candidate input string.
control	keyword	Keyword to control operation: check. Check for modification. keep. Do not check for modification.
encoding	string	IANA encoding of the properties file.