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
|
<?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_xml_auto">
<refmeta>
<refentrytitle>xml_auto</refentrytitle>
<refmiscinfo>xml</refmiscinfo>
</refmeta>
<refnamediv>
<refname>xml_auto</refname>
<refpurpose>prepares and executes given SQL for XML string output</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="fsyn_xml_auto">
<funcprototype id="fproto_xml_auto">
<funcdef><function>xml_auto</function></funcdef>
<paramdef>in <parameter>sql_text </parameter>varchar</paramdef>
<paramdef>in <parameter>params </parameter>any</paramdef>
<paramdef><optional>in <parameter>string_output </parameter>any</optional></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="desc_xml_auto"><title>Description</title>
<para>
This function prepares and executes the given SQL string, which should be a query expression with
the FOR XML clause at the end of the last term. The query
is passed the parameters from the params vector, which should have one element for
each ? in the query text, values assigned from left to right. Consider the
query: select a, b from table where a = ? and b = ?; then the params vector
could reasonably be: <screen>vector(1, 'myfilter')</screen>.
</para>
<para>
The result set is converted to XML and appended to the <parameter>string</parameter>_output.
If the <parameter>string</parameter>_output is omitted and the function executes in the context
of a VSP page, the output is sent to the stream going to the user agent.
</para>
</refsect1>
<refsect1 id="params_xml_auto"><title>Parameters</title>
<refsect2><title>sql_text</title>
<para>Valid SQL query using the FOR XML clause. Parameterized
queries can be constructed using the question mark (?) to specify a
parameter place-holder that will be replaced at run time with the appropriate
value from the <parameter>params</parameter> vector.</para></refsect2>
<refsect2><title>params</title>
<para>Vector of parameters, one element per ? used in the query.</para></refsect2>
<refsect2><title>string_output</title>
<para>String variable or stream for receiving the result.</para></refsect2>
</refsect1>
<refsect1 id="ret_xml_auto"><title>Return Types</title><para>If you omit the third parameter,
this function will output to the context of the calling VSP page.</para></refsect1>
<refsect1 id="errors_xml_auto"><title>Errors</title>
<table><title>Errors signalled by <function>xml_auto</function></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>42000</errorcode></entry>
<entry><errorcode></errorcode></entry>
<entry><errorname>http output function outside of http context and no stream specified</errorname></entry>
<entry>From an attempt to send the output directly to a non HTTP target such as ISQL.</entry>
</row>
<row>
<entry><errorcode>42000</errorcode></entry>
<entry><errorcode></errorcode></entry>
<entry><errorname>Column 1 of the result set of the select statement should be of INTEGER type when FOR XML EXPLICIT clause is used</errorname></entry>
<entry></entry>
</row>
<row>
<entry><errorcode>42000</errorcode></entry>
<entry><errorcode></errorcode></entry>
<entry><errorname>Column 2 of the result set of the select statement should be of INTEGER type when FOR XML EXPLICIT clause is used</errorname></entry>
<entry></entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1 id="examples_xml_auto"><title>Examples</title>
<example id="ex_xml_auto"><title>Producing XML from SQL</title>
<para>
The procedure below takes an SQL string, evaluates it — converting
to XML — and
produces a result set where the XML text is returned as a varchar column.
Parameters are not passed in this example for the sake of simplicity.
</para>
<programlisting>
create procedure xmla (in q varchar)
{
declare st any;
st := string_output ();
xml_auto (q, vector (), st);
result_names (q);
result (string_output_string (st));
}
</programlisting> </example>
</refsect1>
<refsect1 id="seealso_xml_auto"><title>See Also</title>
<para><link linkend="fn_xml_auto_schema"><function>xml_auto_schema()</function></link>,<link linkend="fn_xml_auto_dtd"><function>xml_auto_dtd()</function></link></para>
</refsect1>
</refentry>
|
