6 New Functions

XQuery Update Facility 3.0 provides extensions to XQuery built-in function library, as specified in this section.

6.1 fn:put

fn:put($node as node(), $uri as xs:string) as empty-sequence()
fn:put($node as node(), $uri as xs:string, $params as element(output:serialization-parameters)?) as empty-sequence()

The fn:put function stores a document or element to the location specified by $uri. This function is normally invoked to create a resource on an external storage system such as a file system or a database.

The external effects of fn:put are implementation-defined, since they occur outside the domain of XQuery. The intent is that, if fn:put is invoked on a document node and no error is raised, a subsequent query can access the stored document by invoking fn:doc with the same URI.

The $params argument is used to identify a set of serialization parameters. These are supplied in the form of an output:serialization-parameters element, having the format described in Section 3.1 Setting Serialization Parameters by Means of a Data Model Instance SER30. The two-argument version of this function, or the three argument version with the empty sequence as the third argument, are equivalent to passing an output:serialization-parameters element with no child elements.

Category Rules:

fn:put is an updating function.

Semantics:
  1. If $node is not a document node or an element node, and the implementation does not support fn:put on the given node kind, a dynamic error is raised [err:FOUP0001].

  2. If $uri is not a valid lexical representation of the xs:anyURI type, a dynamic error is raised [err:FOUP0002]. If $uri is a relative URI reference, it is resolved relative to the value of the base URI property in the static context.

  3. An implementation that serializes $node during storage MUST use the serialization parameters to determine how serialization is performed. In this case, the implementation should raise a dynamic error if setting the serialization parameters produces a serialization error or if an invalid parameter value is detected. An implementation may ignore the $params argument (because it does not perform serialization) but must not raise an error because serialization parameters are specified.

  4. The result of a call to fn:put is an empty XDM instance and a pending update list containing the following update primitive: upd:put($node,$uri,$params).

Notes:

  • The results of fn:put do not become effective until after completion of the current snapshot. The fn:put function has no effect on the set of available documents or collections seen by the current snapshot.

  • If a node that is an operand of fn:put is affected by updating expressions in the current snapshot, the fn:put function operates on the node after these updating expressions are made effective. As a result, after completion of the current snapshot, the effects of updates to $node can be seen via $uri. (For details on application of updates, see [8.2.3 upd:applyUpdates].)

  • If multiple calls to fn:put in the same snapshot operate on the same URI (after any necessary resolution of relative URIs), a dynamic error [err:XUDY0031] is raised. The dynamic error is raised by an expression at some level of the query that contains more than one call to fn:put. For a normative description of this error, see [8.2.2 upd:mergeUpdates] and [8.2.3 upd:applyUpdates].