source: trunk/matreshka/source/sql/sql-queries.ads

Last change on this file was 3757, checked in by vadim.godunko, 9 years ago

Add Is_Valid function for SQL_Query to be able to detect situation when
result value is obtained after query was prepared and executed, but not
retrieved by Next.

Refs #286.

  • Property svn:keywords set to Author Date Revision
File size: 8.2 KB
Line 
1------------------------------------------------------------------------------
2-- --
3-- Matreshka Project --
4-- --
5-- SQL Database Access --
6-- --
7-- Runtime Library Component --
8-- --
9------------------------------------------------------------------------------
10-- --
11-- Copyright © 2011-2013, Vadim Godunko <vgodunko@gmail.com> --
12-- All rights reserved. --
13-- --
14-- Redistribution and use in source and binary forms, with or without --
15-- modification, are permitted provided that the following conditions --
16-- are met: --
17-- --
18-- * Redistributions of source code must retain the above copyright --
19-- notice, this list of conditions and the following disclaimer. --
20-- --
21-- * Redistributions in binary form must reproduce the above copyright --
22-- notice, this list of conditions and the following disclaimer in the --
23-- documentation and/or other materials provided with the distribution. --
24-- --
25-- * Neither the name of the Vadim Godunko, IE nor the names of its --
26-- contributors may be used to endorse or promote products derived from --
27-- this software without specific prior written permission. --
28-- --
29-- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS --
30-- "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT --
31-- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR --
32-- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT --
33-- HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, --
34-- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED --
35-- TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR --
36-- PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF --
37-- LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING --
38-- NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS --
39-- SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. --
40-- --
41------------------------------------------------------------------------------
42-- $Revision: 3757 $ $Date: 2013-02-11 07:00:53 +0000 (Mon, 11 Feb 2013) $
43------------------------------------------------------------------------------
44pragma Ada_2012;
45
46private with Ada.Finalization;
47
48with League.Holders;
49with League.Strings;
50private with Matreshka.Internals.SQL_Drivers.Dummy;
51
52package SQL.Queries is
53
54 type SQL_Query is tagged private;
55
56 procedure Bind_Value
57 (Self : in out SQL_Query'Class;
58 Name : League.Strings.Universal_String;
59 Value : League.Holders.Holder;
60 Direction : Parameter_Directions := In_Parameter);
61 -- Set the placeholder Name to be bound to value Value in the prepared
62 -- statement.
63 --
64 -- XXX Add description of Direction and how to set value to NULL.
65
66 function Bound_Value
67 (Self : SQL_Query'Class;
68 Name : League.Strings.Universal_String) return League.Holders.Holder;
69
70 function Error_Message
71 (Self : SQL_Query'Class) return League.Strings.Universal_String;
72
73 function Execute (Self : in out SQL_Query'Class) return Boolean;
74 -- Executes a previously prepared SQL query. Returns True if the query
75 -- executed successfully; otherwise returns False.
76 --
77 -- After the query is executed, the query is positioned on an invalid
78 -- record and must be navigated to a valid record before data values can be
79 -- retrieved.
80 --
81 -- Note that the last error for this query is reset when Execute is called.
82
83 procedure Execute (Self : in out SQL_Query'Class);
84 -- Executes a previously prepared SQL query. Raises SQL_Error when query
85 -- is not executed successfully.
86 --
87 -- After the query is executed, the query is positioned on an invalid
88 -- record and must be navigated to a valid record before data values can be
89 -- retrieved.
90 --
91 -- Note that the last error for this query is reset when Execute is called.
92
93 procedure Finish (Self : in out SQL_Query'Class);
94 -- Instruct the database driver that no more data will be fetched from this
95 -- query until it is re-executed. There is normally no need to call this
96 -- function, but it may be helpful in order to free resources such as locks
97 -- or cursors if you intend to re-use the query at a later time.
98 --
99 -- Sets the query to inactive. Bound values retain their values.
100
101 function Is_Active (Self : SQL_Query'Class) return Boolean;
102 -- Returns True if the query is active. An active SQL_Query is one that has
103 -- been executed successfully but not yet finished with. When you are
104 -- finished with an active query, you can make make the query inactive by
105 -- calling Finish, or you can delete the SQL_Query instance.
106 --
107 -- Note: Of particular interest is an active query that is a SELECT
108 -- statement. For some databases that support transactions, an active query
109 -- that is a SELECT statement can cause a Commit or a Rollback to fail, so
110 -- before committing or rolling back, you should make your active SELECT
111 -- statement query inactive using one of the ways listed above.
112
113 function Is_Valid (Self : SQL_Query'Class) return Boolean;
114 -- Returns True if the query is currently positioned on a valid record;
115 -- otherwise returns false.
116
117 function Next (Self : in out SQL_Query'Class) return Boolean;
118
119 function Prepare
120 (Self : in out SQL_Query'Class;
121 Query : League.Strings.Universal_String) return Boolean;
122 -- Prepares the SQL query query for execution. Returns True if the query is
123 -- prepared successfully; otherwise returns False.
124 --
125 -- The query may contain placeholders for binding values. Both Oracle style
126 -- colon-name (e.g., :surname), and ODBC style (?) placeholders are
127 -- supported; but they cannot be mixed in the same query.
128 --
129 -- Portability note: Some databases choose to delay preparing a query until
130 -- it is executed the first time. In this case, preparing a syntactically
131 -- wrong query succeeds, but every consecutive Execute will fail.
132
133 procedure Prepare
134 (Self : in out SQL_Query'Class; Query : League.Strings.Universal_String);
135 -- Prepares the SQL query query for execution. Raises SQL_Error if query is
136 -- not prepared successfully.
137 --
138 -- The query may contain placeholders for binding values. Both Oracle style
139 -- colon-name (e.g., :surname), and ODBC style (?) placeholders are
140 -- supported; but they cannot be mixed in the same query.
141 --
142 -- Portability note: Some databases choose to delay preparing a query until
143 -- it is executed the first time. In this case, preparing a syntactically
144 -- wrong query succeeds, but every consecutive Execute will fail.
145
146-- function Previous (Self : in out SQL_Query'Class) return Boolean;
147-- procedure Previous (Self : in out SQL_Query'Class);
148
149 function Value
150 (Self : SQL_Query'Class;
151 Index : Positive) return League.Holders.Holder;
152
153private
154
155 type SQL_Query is new Ada.Finalization.Controlled with record
156 Data : Matreshka.Internals.SQL_Drivers.Query_Access
157 := Matreshka.Internals.SQL_Drivers.Dummy.Empty_Query'Access;
158 end record;
159
160 overriding procedure Adjust (Self : in out SQL_Query);
161
162 overriding procedure Finalize (Self : in out SQL_Query);
163
164end SQL.Queries;
Note: See TracBrowser for help on using the repository browser.