1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
-
- This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
- project.
-
- Copyright (C) 1998-2018 OpenLink Software
-
- This project is free software; you can redistribute it and/or modify it
- under the terms of the GNU General Public License as published by the
- Free Software Foundation; only version 2 of the License, dated June 1991.
-
- This program is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- General Public License for more details.
-
- You should have received a copy of the GNU General Public License along
- with this program; if not, write to the Free Software Foundation, Inc.,
- 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
-
-
-->
<refentry id="fn_xpf_extension">
<refmeta>
<refentrytitle>xpf_extension</refentrytitle>
<refmiscinfo>xml</refmiscinfo>
</refmeta>
<refnamediv>
<refname>xpf_extension</refname>
<refpurpose>declare an XPath extension function </refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="fsyn_xpf_extension">
<funcprototype id="fproto_xpf_extension">
<funcdef>void <function>xpf_extension</function></funcdef>
<paramdef>in <parameter>fname</parameter> varchar</paramdef>
<paramdef>in <parameter>procedure_name</parameter> varchar</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="desc_xpf_extension"><title>Description</title>
<para>
This function is used to declare a new XPath extension function or
redefine an existing function. It can be used in XPath queries and
XSLT stylesheets. You should use QNames for extension functions.
Note that the standard XPath functions cannot be redefined.</para>
<para><function>xpf_extension()</function> stores the functions into
the SYS_XPF_EXTENSIONS system table.
</para>
<programlisting>
CREATE TABLE
DB.DBA.SYS_XPF_EXTENSIONS (
XPE_NAME VARCHAR PRIMARY KEY,
XPE_PNAME VARCHAR
)
</programlisting>
<para>
The input parameters will be retrieved as a strings and then will be converted to the datatype of
the corresponding argument of the stored procedure.
</para>
</refsect1>
<refsect1 id="params_xpf_extension"><title>Parameters</title>
<refsect2><title>fname</title>
<para>The name of the extension function, which must be the expanded QName
of the extension function</para></refsect2>
<refsect2><title>procedure_name</title>
<para>The fully qualified name of the PL procedure which acts as
the extension function. The procedure in question must be granted to PUBLIC,
otherwise it will not be registered and error will be signalled.
</para></refsect2>
</refsect1>
<refsect1 id="ret_xpf_extension"><title>Return Types</title>
<para>None (void).</para></refsect1>
<refsect1 id="errors_xpf_extension"><title>Errors</title>
<table><title>Errors signalled by</title>
<tgroup cols="4">
<thead><row><entry>SQLState</entry><entry>Error Code</entry><entry>Error Text</entry><entry>Description</entry></row></thead>
<tbody>
<row>
<entry><errorcode>42001</errorcode></entry>
<entry><errorcode>XPE01</errorcode></entry>
<entry><errorname>The function <procedure_name> does not exist</errorname></entry>
<entry>if procedure to define as a XPATH extension function is not existing one.</entry>
</row>
<row>
<entry><errorcode>42001</errorcode></entry>
<entry><errorcode>XPE02</errorcode></entry>
<entry><errorname><![CDATA[The <built-in XPATH|XQUERY> function "<func name>" cannot be re-defined]]></errorname></entry>
<entry>if XPATH or XQUERY function to be registered is a core function.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1 id="examples_xpf_extension"><title>Examples</title>
<example id="ex_xpf_extension"><title>Declaring a New XSLT Function</title>
<para>First define a PL procedure, then declare an XPath extension
function and to represent it.</para>
<programlisting>
<![CDATA[
SQL> create procedure DB.DBA.str_concat (in a varchar, in b varchar)
{
return concat (a, ':', b);
};
SQL> xpf_extension ('http://example.com/virtuoso/xslt:concat_strings', 'DB.DBA.str_concat');
]]>
</programlisting>
<para> The source of the ([http_root]/ext.xsl) XSLT stylesheet </para>
<programlisting>
<![CDATA[
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/TR/WD-xsl"
xmlns:virt="http://example.com/virtuoso/xslt">
<xsl:template match="/doc">
<HTML>
<BODY>
<xsl:if test="function-available('virt:concat_strings')">
<xsl:value-of select="virt:concat_strings ('foo', 'bar')"/>
</xsl:if>
</BODY>
</HTML>
</xsl:template>
</xsl:stylesheet>
]]>
</programlisting>
<para>The source of the
<programlisting>([http_root]/ext.vsp)</programlisting> VSP page:
</para>
<programlisting>
<![CDATA[
<?vsp
http_xslt ('file:/ext.xsl');
?>
<doc>
<a/>
</doc>
]]>
</programlisting>
<para>
This will produce the following HTML page:
</para>
<programlisting>
<HTML><BODY>foo:bar</BODY></HTML>
</programlisting>
<para>Using the definition of the XPath extension function, we can
include it in XPath expressions.</para>
<programlisting>
SQL> select p from ws..sys_dav_res
where xpath_contains (RES_CONTENT,
'[xmlns:virt=''http://example.com/virtuoso/xslt'']
virt:concat_strings (''Title '', string(/chapter/title))', p);
</programlisting>
<para>This will return the contents of any '/chapter/title' nodes, prefixed
with constant string 'Title'.</para>
</example>
</refsect1>
<refsect1 id="seealso_xpf_extension"><title>See Also</title>
<para><link linkend="fn_xpf_extension_remove"><function>xpf_extension_remove</function></link></para>
</refsect1>
</refentry>
|
