Parameters in XPath Functions
A user-defined XPath function can be assigned any number of parameters. The function's parameters are defined in the Parameters pane of the XPath Functions dialog (see screenshot below). These parameters can then be used in the definition of the user-defined XPath function (in the Function Body pane).
User-defined XPath function mechanism
The steps below explain how an XPath function works.
1.In a function call (for example, in an Auto-Calculation), the number of arguments in the function call must match the number of parameters defined for the user-defined function (as defined in the Parameters pane of the user-defined function; see screenshot below). Additionally, the number of items submitted by each argument (in the function call) must match the Occurrence definition of the corresponding parameter. If a datatype restriction has been specified for a parameter (in the Type column of the Parameters pane), the value/s submitted by the argument must match this datatype.
2.The arguments passed to the function's parameters are then used in the XPath function (as defined in the Function Body pane; see screenshot below). The result obtained by evaluating the XPath expression is then checked against the optional Return Type definition (see screenshot below). If the datatype is as expected, the result is used in the XPath expression from which the function was called.
Order of parameters
The order of the user-defined function's parameters is important because, when the function is called, the arguments submitted in the function call will be assigned to the parameters according to the order in which they are defined in the Parameters pane (see screenshot below).
So if the sps:Stock user-defined XPath function is defined as in the screenshot above and if it is called with the following XPath expression:
sps:Stock($XML, Node1, Node2)
then these three arguments—$XML, Node1, Node2— will be assigned, in that order, respectively, to the parameters $ContextStock, $Selection, and $StockInfo.
Note that each argument in the function call is separated from the next by a comma. So, each argument, as delimited by the commas in the function call, will be passed to the corresponding parameter (as ordered in the Parameters pane; see screenshot above).
The order of parameters in the Parameters pane can be controlled with the Append, Insert, and Delete icons of the Parameters pane.
Datatype of parameters
Optionally, the datatypes of parameters of the user-defined function can be defined. If a datatype is specified, then the datatype of the incoming argument will be checked against the parameter's datatype, and an error will be returned if the types do not match. This feature enables the input data (from the function call's arguments) to be checked.
Occurrence
Each parameter of the user-defined XPath function can be considered to be a sequence. The Occurrence property of a parameter specifies how many items must be submitted for that parameter by the corresponding argument of the function-call.
In both function definitions and in function calls, commas are used to separate one parameter or argument from another as well as to separate items within a sequence. It is important, therefore, to note the context in which a comma is used: to separate parameters/arguments or to separate sequence items.
•In parameters/arguments, if required, parentheses are used to delimit sequences—in the function definition (parameters) or in the function call (arguments).
•In sequences, parentheses are ignored.
In this context, the following examples and points should be noted:
•Parentheses in parameters/arguments: Several XPath functions take a single sequence as an argument, for example, the avg() and count() functions. If this sequence is enumerated using comma separators or range operators, the sequence must be enclosed in parentheses to unambiguously show that it is a single sequence—and not multiple comma-separated sequences. For example, in the function avg((count($a), $b, $c)), the XPath 2.0 avg() function takes the single sequence (count($a),$b,$c) as its argument. Since the items of the sequence are enumerated, making up a sequence of three items, the sequence must be enclosed in parentheses and submitted as a single argument to the avg() function: avg((count($a),$b,$c)). Without the inner pair of parentheses, the definition of the avg() function would have three parameters, and that would be an error (since the avg() function expects one argument consisting of a single sequence).
•No parentheses in parameters/arguments: Similarly, the count() function also takes a single sequence as its one-parameter argument. However, since in our example count($a) the single sequence is not a comma-separated enumerated list, but is fetched instead by the variable/parameter $a, the argument does not need to be enclosed by an inner set of parentheses: So the expression count($a) is correct.
•Parentheses and commas in function calls: In a function call, parentheses must be correctly used so that each argument corresponds to a parameter (as defined in the Parameters pane of the XPath Functions dialog). For example, if a user-defined XPath function named MyAverage() is defined with the XPath 2.0 expression: avg((count($a),$b,$c)), then the following function call would be valid: MyAverage((1,2,3),4,5). The values corresponding to the three parameters $a, $b, and $c would be, respectively, the sequence (1,2,3), the singleton-sequence 4, and the singleton sequence 5. Singleton-sequences can, optionally, be enclosed in parentheses. The value returned by MyAverage()in this case would be 4.