The _excel() function returns a value from a workbook spreadsheet.

Note: The _excel() function requires the Excel extension to be installed.

The _excel() function uses the following format:

_excel(workbook, sheetname,keycol, dif, keyval, valcol [,default] [,keep] [,evaluate])

workbook	string	The path to the workbook.
sheetname	string	Name of the sheet in the workbook. If omitted, the default is Sheet1.
keycol	sheetcol (see below)	The column containing the desired property key.
dif	boolean	Determines whether this sheet is compliant with DIF format. If set to true, then the property key search starts in row 2, else it starts in row 2. Note: As a convenience the keyword dif is equivalent to true. The setting of this parameter cannot vary based on the input document.
keyval	string	The property name in the keycol.
valcol	sheetcol	The column containing the desired value.
default	string	Value returned if the keycol/valcol cannot be determined or located.
keep	keyword	The keyword to control workbook load operation: check. Check for file modification. (default) keep. Do not check for file modification and retain the worksheet in memory. Note: The setting of this parameter cannot vary based on the input document.
evaluate	keyword	The keyword to control the result evaluation: evaluate. Evaluate the result as iFL. Allows iFL to be held in a cell of the worksheet. constant. Do not evaluate. (default) Note: The setting of this parameter cannot vary based on the input document.

Similar to the _property() function, a key is evaluated and the value returned. The spreadsheet, however, can provide data anywhere on a sheet, and sheet relationships are supported. For example, a formula in a value column might reference another position or sheet position in a logical hierarchy meaningful to an application. For example, separate sheets within a single workbook might hold values for different customers, message types, and so on.

Once a keycol is determined, the rows of the sheet are interrogated to locate the row containing the keyval. Once the row is determined, the valcol on that row is accessed to obtain the desired value.

A sheetcol is used to locate the column of interest. It may be an integer, a column ID (if not DIF format) or a meaningful value in the header row (dif is set to true) such as dev or prod enabling multiple sets of properties to be stored together. For example, in the sample spreadsheet, formulas are used to construct simple interrelationships. Other application architects might elect to keep values in different spreadsheets, with the relationships between the spreadsheets arranged in a meaning property hierarchy. The _excel() function attempts to resolve formulas, but users are cautioned that it is possible to construct formulas that _excel() cannot evaluate. Constructing valid spreadsheets that can be evaluated is the responsibility of the application architect.

No provision is made to store a value in encrypted form, however encrypted values can be created using the set property command and the value copied to the spreadsheet.

Example 1:

A single sheet table with columns representing the current development status is shown in the following image.

Assume a special register where is set to uat. The transform for editransform might be entered as follows:

_excel('/excel/users.xlsx','app1','property',dif, editransform,_sreg(where),'asis')

This function assumes an imaginary transform that is used for debugging. The function will search the app1 spreadsheet to locate the row that has editransform in the property column. If found, then it returns the value in the uat column. If not, then it returns asis.

The following is the equivalent for raw addressing:

_excel('/excel/users.xlsx','app1','A', false, editransform,'C','asis')

The form of addressing used depends upon application needs.

Example 2:

A multicolumn workbook holding information about specific or general EDI trading partners. This example uses the _excelsheets() function described. In iWay Service Manager, the EDI facilities provide a special register frompartner holding the name of the source partner in the EDI message. The names of the worksheets in the workbook represent specific trading partner names that do not use the general defaults entered in sheet defaultPartner, as shown in the following image.

The sheet for partner1 might be as shown in the following image.

Note that cells of partner1 can refer to other sheets, in this example the defaultPartner sheet.

To locate the transform for an EDI 850 message for partner1:

_excel('/info.xslx',_if(_inlist(),_sreg(frompartner),'defaultPartner')),'key','dif',850,'For This Partner','trans850default')

The following table lists and describes this command structure.

_excel('/info.xslx',

_if(inlist(_excellist('/info.xslx',_sreg(frompartner),'string'),
sreg(frompartner)), 'defaultPartner)),

'key',dif,

'850'

'For This Partner',

'trans850default'

The result returned will be trans850part1.

The _excelsheets() function returns a list of the worksheets in a specified workbook. The returned list can be used in the _inlist() iFL function, as shown in the example under _excel().

Note: The _excelsheets() function requires the Excel extension to be installed.

The _excelsheets() function uses the following format:

_excelsheets(workbook [,keep])

workbook	string	The path to the workbook.
keep	keyword	The keyword to control workbook load operation: check. Check for file modification. (default) keep. Do not check for file modification and retain the worksheet in memory. Note: The setting of this parameter cannot vary based on the input document.

A Java Archive (JAR) manifest contains information that is added when a .jar file is built. There can be standard or application-specific information contained in a manifest. This function makes the value of a manifest variable available to the application.

The _manifest() function uses the following format:

_manifest(jarname, attribute, [,default])

jarname	string	Name of the .jar file from which the manifest is to be read. A relative path is resolved to the classpath.
attribute	string	Name (case-sensitive) of the attribute to be read.
default	string	Value to be returned if the attribute is not present or has no value.

For example, you can compose the _manifest() function as follows to determine the build date for this version of the iwcore.jar file:

_manifest('iwcore','Built-On')

It is sometimes useful to set the parameter of one component (for example, a listener), called the target, to reflect the setting of another component, called the source. This can, for example, allow a target listener to reflect (shadow) a source listener. The configuration parameter is taken from the settings of the source, not the current runtime value. It is immaterial whether the source component is actually in execution. The setting will be evaluated on the target as if the source setting had directly been present on that target.

The source can be defined in the runtime dictionary of the same or another configuration (iWay Integration Application (iIA)).

The _parmof() function uses the following format:

_parmof(sourcetype, sourcename, key [,default][, configuration] )

sourcetype	keyword	The type of component to provide the information (need not be the type of the target component): listener. The value is to be taken from a listener definition. system. The value is to be taken from a system (server) definition.
sourcename	string	The name of the component. Not applicable to system requests.
key	string	The (internal) name of the parameter.
default	string	Value to return if the parameter is not found in the source.
configuration	string	Name of the configuration in which the source is defined. The default is the current configuration.

As an example, set the number of workers (threads) for a channel to match the number in a channel named S1 in an iIA named APP3:

The _eval() function evaluates a string as an expression of the function. The use of this tracing facility is to help debug by reporting the setting of parameters that are set by iFL.

The _eval() function uses the following format:

_eval(expression [,tracemsg [,level]])

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]])

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])

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.

_xquery(expression)

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 _exists() function uses the following format:

_exists(statement)

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]])

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])

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]])

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 SREG service (com.ibi.agents.XDSREGAgent).

Metrics can be referenced as special registers. The lock is desirable when one or more of the registers might be changed by an SREG service (com.ibi.agents.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'))

If the lock is being used to serialize activity within the server, then it is recommended to create a Special Register (SREG) at an appropriate level, such as a configuration register of any type. You can then use that register for locking. Configuration registers can be created in the Registers page of the iSM Administration Console, which allows the scope of the lock to be server-wide. Use the name of this register as the lock value. For example, to serialize accesses to an LDAP data source:

_lock('config_level_lock',_ldap(…))

As a general rule, locks should be as granular as possible. Avoid using a single lock name for all locks of any purpose. The lock should be unique to the resource being protected under the lock.

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:

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)

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:

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])

d71648c0-1485-11dc-a269-0019b92fe248

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. The following actions are supported: document. Saves the entire contents of the input document, including status flags, attachments, and so on. A value of true is returned if successful. payload. Saves the contents of the document payload (for example, XML tree). A value of true is returned if successful. 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: local. The scope is the local register context. This scope is set by default. flow. The scope is the head of the process flow. message. The scope is the message (worker).
serialization	keyword	Determines how the saved data is stored. Specify one of the following settings: internal. The saved information is stored in memory. This is the default setting. external. The saved information is stored on disk.

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: clear. The register used to hold the saved document is deleted, which releases the memory used to store the information. This action is set by default. keep. The register is not cleared, making it possible to restore the document again at a later point in the process flow.

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.