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
180
181
182
183
|
<?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_exec">
<refmeta>
<refentrytitle>exec</refentrytitle>
<refmiscinfo>sql</refmiscinfo>
</refmeta>
<refnamediv>
<refname>exec</refname>
<refpurpose>dynamic execution of SQL returning state and result set</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="fsyn_exec">
<funcprototype id="fproto_exec">
<funcdef><function>exec</function></funcdef>
<paramdef>in <parameter>str</parameter> varchar</paramdef>
<paramdef>out <parameter>state</parameter> varchar</paramdef>
<paramdef>out <parameter>message</parameter> varchar</paramdef>
<paramdef>in <parameter>params</parameter> any</paramdef>
<paramdef>in <parameter>maxrows</parameter> integer</paramdef>
<paramdef>out <parameter>metadata</parameter> vector</paramdef>
<paramdef>out <parameter>rows</parameter> vector</paramdef>
<paramdef>out <parameter>cursor_handle</parameter> long</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="desc_exec">
<title>Description</title>
<para>This function provides dynamic SQL capabilities in Virtuoso PL.
The first argument is an arbitrary SQL statement, which may contain
parameter placeholders. The function returns as output parameters a
SQL state, error message, column metadata and result set rows if
the statement is a select.</para>
<para>A stored procedure can be invoked by exec but a procedure's
result set will not be received in the rows output parameter but rather
sent to the client.</para>
</refsect1>
<refsect1 id="params_exec"><title>Parameters</title>
<refsect2><title><parameter>str</parameter></title>
<para>A <type>varchar</type> containing arbitrary SQL using ?'s for parameter markers.</para>
</refsect2>
<refsect2><title>state</title>
<para>An output parameter of type <type>varchar</type> set to the 5 character SQL state if the exec resulted an error. Not set if an error is not present.</para>
</refsect2>
<refsect2><title>message</title>
<para>An output parameter of type <type>varchar</type> set to SQL error message associated with the error. Not set if an error is not present.</para>
</refsect2>
<refsect2><title>params</title>
<para>A <type>vector</type> containing the parameters for the SQL being executed. Element 0 corresponding to first ?, etc.</para>
</refsect2>
<refsect2><title>maxrows</title>
<para>The <type>integer</type> maximum number of rows to retrieve in case of a statement returning a result set.</para>
</refsect2>
<refsect2><title>metadata</title>
<para>An output parameter of type <type>vector</type> returning the metadata of the statement and its result.</para>
<table><title>The stmt_meta array</title>
<tgroup cols="3">
<thead><row><entry>Element</entry><entry>Name</entry><entry>Description</entry></row></thead>
<tbody>
<row>
<entry>0</entry>
<entry>COLS</entry>
<entry>An array containing description of each column in the result
set (see table below for contents)</entry>
</row>
<row>
<entry>1</entry>
<entry>STMT_SELECT</entry>
<entry>An <type>integer</type> 1 indicates that the statement is a
select, otherwise it is a DML statement.</entry>
</row>
<row>
<entry>2..</entry>
<entry>N/A</entry>
<entry>Trailing elements may appear, but they should not be used</entry>
</row>
</tbody>
</tgroup>
</table>
<table><title>Columns array of metadata</title>
<tgroup cols="3">
<thead><row><entry>Element</entry><entry>Name</entry><entry>Description</entry></row></thead>
<tbody>
<row>
<entry>0</entry><entry>name</entry><entry>Column name</entry>
</row>
<row>
<entry>1</entry>
<entry>type</entry>
<entry>Column type as an internal type code corresponding,
but not equal to ODBC SQL type codes.</entry>
</row>
<row>
<entry>2</entry>
<entry>scale</entry>
<entry>column scale</entry>
</row>
<row>
<entry>3</entry>
<entry>precision</entry>
<entry>column precision</entry>
</row>
<row>
<entry>4</entry>
<entry>nullable</entry>
<entry>indicates nullable column</entry>
</row>
<row>
<entry>5</entry>
<entry>updatable</entry>
<entry>indicates updatable column</entry>
</row>
<row>
<entry>6</entry>
<entry>searchable</entry>
<entry>indicates searchable column</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect2>
<refsect2><title>rows</title>
<para>An output array with one element per result row containing an array with the leftmost column as element 0 and so forth.</para>
</refsect2>
<refsect2><title>cursor_handle</title>
<para>The cursor handle for use with related functions.</para>
</refsect2>
</refsect1>
<refsect1 id="examples_exec"><title>Examples</title>
<example id="ex_exec"><title>Procedure Example</title>
<para>This stored procedure returns 1 if a given table is empty. An error such
as a timeout or deadlock would be reported back to the caller as an exception.
Exec always returns, no matter the type of exception. Thus it is also useful
as a universal error catcher.</para>
<screen>
create procedure tb_is_empty (in tb varchar)
{
declare state, msg, descs, rows any;
state := '00000';
exec (sprintf ('select 1 from %s', tb), state,
msg, vector (), 1, descs, rows);
if (state <> '00000')
signal (state, msg);
if (length (rows) = 0)
return 1;
else
return 0;
}
</screen>
</example>
</refsect1>
<refsect1 id="seealso_exec"><title>See Also</title>
<para><link linkend="fn_rexecute"><function>rexecute()</function></link></para>
<para><link linkend="fn_exec_next"><function>exec_next()</function></link></para>
<para><link linkend="fn_exec_close"><function>exec_close()</function></link></para>
</refsect1>
</refentry>
|
