XQuery Update Facility 3.0 provides extensions to XQuery built-in function library, as specified in this section.
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.
fn:put
is an updating function.
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].
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.
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.
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].