1 /* @include ajsql *************************************************************
2 **
3 ** AJAX SQL functions
4 **
5 ** @author Copyright (C) 2006 Michael K. Schuster
6 ** @version $Revision: 1.14 $
7 ** @modified $Date: 2011/10/18 14:23:40 $ by $Author: rice $
8 ** @@
9 **
10 ** This library is free software; you can redistribute it and/or
11 ** modify it under the terms of the GNU Lesser General Public
12 ** License as published by the Free Software Foundation; either
13 ** version 2.1 of the License, or (at your option) any later version.
14 **
15 ** This library is distributed in the hope that it will be useful,
16 ** but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
18 ** Lesser General Public License for more details.
19 **
20 ** You should have received a copy of the GNU Lesser General Public
21 ** License along with this library; if not, write to the Free Software
22 ** Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
23 ** MA  02110-1301,  USA.
24 **
25 ******************************************************************************/
26 
27 #ifndef AJSQL_H
28 #define AJSQL_H
29 
30 /* ========================================================================= */
31 /* ============================= include files ============================= */
32 /* ========================================================================= */
33 
34 #include "ajdefine.h"
35 #include "ajstr.h"
36 #include "ajarr.h"
37 #include "ajtime.h"
38 
39 AJ_BEGIN_DECLS
40 
41 
42 
43 
44 /* ========================================================================= */
45 /* =============================== constants =============================== */
46 /* ========================================================================= */
47 
48 
49 
50 
51 /* ========================================================================= */
52 /* ============================== public data ============================== */
53 /* ========================================================================= */
54 
55 
56 
57 
58 /* @data AjPVoid **************************************************************
59 **
60 ** Ajax address object.
61 **
62 ** Holds a void array with additional data.
63 ** The length is known and held internally.
64 **
65 ** Saves on length calculation, and allows growth in reserved memory without
66 ** changing the pointer in the calling routine.
67 **
68 ** AjPVoid is implemented as a pointer to a C data structure.
69 **
70 ** @alias AjSVoid
71 ** @alias AjOVoid
72 **
73 ** @new    ajVoidNew Default constructor
74 ** @new    ajVoidNewRes Constructor with reserved size
75 ** @delete ajVoidDel Default destructor
76 ** @cast   ajVoidGet Retrieve a pointer from an array
77 ** @modify ajVoidPut Load a pointer array element
78 **
79 ** @attr Res [ajuint] Reserved space in case of extension
80 ** @attr Len [ajuint] Actual length used
81 ** @attr Ptr [void**] Array of void pointers
82 ** @@
83 ******************************************************************************/
84 
85 typedef struct AjSVoid
86 {
87     ajuint Res;
88     ajuint Len;
89     void **Ptr;
90 } AjOVoid;
91 
92 #define AjPVoid AjOVoid*
93 
94 
95 
96 
97 /* @enum AjESqlconnectionClient ***********************************************
98 **
99 ** AJAX SQL Connection client library enumeration.
100 **
101 ** @alias AjOSqlconnectionClient
102 **
103 ** @value ajESqlconnectionClientNULL       Null
104 ** @value ajESqlconnectionClientMySQL      MySQL client
105 ** @value ajESqlconnectionClientPostgreSQL PostgreSQL client
106 ******************************************************************************/
107 
108 typedef enum AjOSqlconnectionClient
109 {
110     ajESqlconnectionClientNULL,
111     ajESqlconnectionClientMySQL,
112     ajESqlconnectionClientPostgreSQL
113 } AjESqlconnectionClient;
114 
115 
116 
117 
118 /* @data AjPSqlconnection *****************************************************
119 **
120 ** AJAX SQL Connection.
121 **
122 ** Holds the client type and a pointer to a SQL client library-specific
123 ** connection object.
124 **
125 ** @alias AjSSqlconnection
126 ** @alias AjOSqlconnection
127 **
128 ** @attr Pconnection [void*]  SQL client library-specific connection object
129 **                            (MYSQL*) for the MySQL client library
130 **                            (PGconn*) for the PostgreSQL client library
131 ** @attr Client [AjESqlconnectionClient] Client library
132 ** @attr Use [ajuint] Use counter
133 ** @@
134 ******************************************************************************/
135 
136 typedef struct AjSSqlconnection
137 {
138     void *Pconnection;
139     AjESqlconnectionClient Client;
140     ajuint Use;
141 } AjOSqlconnection;
142 
143 #define AjPSqlconnection AjOSqlconnection*
144 
145 
146 
147 
148 /* @data AjPSqlstatement ******************************************************
149 **
150 ** AJAX SQL Statement.
151 **
152 ** Holds pointers to an AJAX SQL Connection and to a client library-specific
153 ** result object.
154 **
155 ** @alias AjSSqlstatement
156 ** @alias AjOSqlstatement
157 **
158 ** @attr Sqlconnection [AjPSqlconnection] AJAX SQL Connection.
159 ** @attr Presult [void*] SQL client library-specific result object
160 **                        (MYSQL_RES*) for the MySQL client library
161 **                        (PGresult*) for the PostgreSQL client library
162 ** @attr AffectedRows [ajulong] Number of rows affected by non-SELECT SQL
163 **                              statements
164 ** @attr SelectedRows [ajulong] Number of rows selected by SELECT-like SQL
165 **                              statements
166 ** @attr Columns [ajuint] Number of columns returned by SELECT-like statements
167 ** @attr Use [ajuint] Use counter
168 ** @@
169 ******************************************************************************/
170 
171 typedef struct AjSSqlstatement
172 {
173     AjPSqlconnection Sqlconnection;
174     void *Presult;
175     ajulong AffectedRows;
176     ajulong SelectedRows;
177     ajuint Columns;
178     ajuint Use;
179 } AjOSqlstatement;
180 
181 #define AjPSqlstatement AjOSqlstatement*
182 
183 
184 
185 
186 /* @data AjPSqlrow ************************************************************
187 **
188 ** AJAX SQL Result Row.
189 **
190 ** Holds an AjPChar array of C-type character strings and an AjLong array of
191 ** data lengths for each column data values in SQL client library-specific
192 ** result objects.
193 **
194 ** @alias AjSSqlrow
195 ** @alias AjOSqlrow
196 **
197 ** @attr Values [AjPVoid] AJAX Character Array of SQL column values
198 ** @attr Lengths [AjPLong] AJAX Long Integer Array of SQL column value lengths
199 ** @attr Columns [ajuint] Number of columns per row
200 ** @attr Current [ajuint] Current column in column interactions
201 ** @@
202 ******************************************************************************/
203 
204 typedef struct AjSSqlrow
205 {
206     AjPVoid Values;
207     AjPLong Lengths;
208     ajuint Columns;
209     ajuint Current;
210 } AjOSqlrow;
211 
212 #define AjPSqlrow AjOSqlrow*
213 
214 
215 
216 
217 /* @data AjISqlrow ************************************************************
218 **
219 ** AJAX SQL Row Iterator.
220 **
221 ** Allows iteration over AJAX SQL Rows of an AJAX SQL Statement.
222 **
223 ** @alias AjSSqlrowiter
224 ** @alias AjOSqlrowiter
225 ** @alias AjPSqlrowiter
226 **
227 ** @attr Sqlstatement [AjPSqlstatement] AJAX SQL Statement
228 ** @attr Sqlrow [AjPSqlrow] AJAX SQL Result Row
229 ** @attr Current [ajulong] Current row number
230 ** @@
231 ******************************************************************************/
232 
233 typedef struct AjSSqlrowiter
234 {
235     AjPSqlstatement Sqlstatement;
236     AjPSqlrow Sqlrow;
237     ajulong Current;
238 } AjOSqlrowiter;
239 
240 #define AjISqlrow AjOSqlrowiter*
241 #define AjPSqlrowiter AjOSqlrowiter*
242 
243 
244 
245 
246 /* ========================================================================= */
247 /* =========================== public functions ============================ */
248 /* ========================================================================= */
249 
250 
251 
252 
253 /*
254 ** Prototype definitions
255 */
256 
257 AjBool ajSqlInit(void);
258 
259 void ajSqlExit(void);
260 
261 /* AJAX SQL Connection */
262 
263 AjPSqlconnection ajSqlconnectionNewData(AjESqlconnectionClient client,
264                                         const AjPStr user,
265                                         const AjPStr password,
266                                         const AjPStr host,
267                                         const AjPStr port,
268                                         const AjPStr socketfile,
269                                         const AjPStr database);
270 
271 AjPSqlconnection ajSqlconnectionNewRef(AjPSqlconnection sqlc);
272 
273 void ajSqlconnectionDel(AjPSqlconnection* Psqlc);
274 
275 AjESqlconnectionClient ajSqlconnectionGetClient(const AjPSqlconnection sqlc);
276 
277 ajuint ajSqlconnectionGetUse(const AjPSqlconnection sqlc);
278 
279 AjBool ajSqlconnectionTrace(const AjPSqlconnection sqlc, ajuint level);
280 
281 AjBool ajSqlconnectionEscapeC(const AjPSqlconnection sqlc,
282                               char **Ptxt,
283                               const AjPStr str);
284 
285 AjBool ajSqlconnectionEscapeS(const AjPSqlconnection sqlc,
286                               AjPStr *Pstr,
287                               const AjPStr str);
288 
289 AjESqlconnectionClient ajSqlconnectionClientFromStr(const AjPStr client);
290 
291 const char* ajSqlconnectionClientToChar(AjESqlconnectionClient client);
292 
293 /* AJAX SQL Statement */
294 
295 AjPSqlstatement ajSqlstatementNewRun(AjPSqlconnection sqlc,
296                                      const AjPStr statement);
297 
298 AjPSqlstatement ajSqlstatementNewRef(AjPSqlstatement sqls);
299 
300 void ajSqlstatementDel(AjPSqlstatement* Psqls);
301 
302 ajulong ajSqlstatementGetAffectedrows(const AjPSqlstatement sqls);
303 
304 ajulong ajSqlstatementGetSelectedrows(const AjPSqlstatement sqls);
305 
306 ajuint ajSqlstatementGetColumns(const AjPSqlstatement sqls);
307 
308 ajuint ajSqlstatementGetIdentifier(const AjPSqlstatement sqls);
309 
310 /* AJAX SQL Row Iterator */
311 
312 AjISqlrow ajSqlrowiterNew(AjPSqlstatement sqls);
313 
314 void ajSqlrowiterDel(AjISqlrow *Psqli);
315 
316 AjBool ajSqlrowiterDone(const AjISqlrow sqli);
317 
318 AjPSqlrow ajSqlrowiterGet(AjISqlrow sqli);
319 
320 AjBool ajSqlrowiterRewind(AjISqlrow sqli);
321 
322 /* AJAX SQL Row */
323 
324 AjPSqlrow ajSqlrowNew(ajuint columns);
325 
326 void ajSqlrowDel(AjPSqlrow *Psqlr);
327 
328 AjPVoid ajSqlrowGetValues(const AjPSqlrow sqlr);
329 
330 AjPLong ajSqlrowGetLengths(const AjPSqlrow sqlr);
331 
332 ajuint ajSqlrowGetColumns(const AjPSqlrow sqlr);
333 
334 ajuint ajSqlrowGetCurrent(const AjPSqlrow sqlr);
335 
336 AjBool ajSqlcolumnGetValue(AjPSqlrow sqlr, void **Pvalue,
337                            ajulong *Plength);
338 
339 AjBool ajSqlcolumnToStr(AjPSqlrow sqlr, AjPStr *Pvalue);
340 
341 AjBool ajSqlcolumnToInt(AjPSqlrow sqlr, ajint *Pvalue);
342 
343 AjBool ajSqlcolumnToUint(AjPSqlrow sqlr, ajuint *Pvalue);
344 
345 AjBool ajSqlcolumnToLong(AjPSqlrow sqlr, ajlong *Pvalue);
346 
347 AjBool ajSqlcolumnToUlong(AjPSqlrow sqlr, ajulong *Pvalue);
348 
349 AjBool ajSqlcolumnToFloat(AjPSqlrow sqlr, float *Pvalue);
350 
351 AjBool ajSqlcolumnToDouble(AjPSqlrow sqlr, double *Pvalue);
352 
353 AjBool ajSqlcolumnToBool(AjPSqlrow sqlr, AjBool *Pvalue);
354 
355 AjBool ajSqlcolumnToTime(AjPSqlrow sqlr, AjPTime *Pvalue);
356 
357 AjBool ajSqlcolumnRewind(AjPSqlrow sqlr);
358 
359 AjBool ajSqlcolumnNumberGetValue(const AjPSqlrow sqlr,
360                                  ajuint column,
361                                  void **Pvalue,
362                                  ajulong *Plength);
363 
364 AjBool ajSqlcolumnNumberToStr(const AjPSqlrow sqlr, ajuint column,
365                               AjPStr *Pvalue);
366 
367 AjBool ajSqlcolumnNumberToInt(const AjPSqlrow sqlr, ajuint column,
368                               ajint *Pvalue);
369 
370 AjBool ajSqlcolumnNumberToUint(const AjPSqlrow sqlr, ajuint column,
371                                ajuint *Pvalue);
372 
373 AjBool ajSqlcolumnNumberToLong(const AjPSqlrow sqlr, ajuint column,
374                                ajlong *Pvalue);
375 
376 AjBool ajSqlcolumnNumberToFloat(const AjPSqlrow sqlr, ajuint column,
377                                 float *Pvalue);
378 
379 AjBool ajSqlcolumnNumberToDouble(const AjPSqlrow sqlr, ajuint column,
380                                  double *Pvalue);
381 
382 AjBool ajSqlcolumnNumberToBool(const AjPSqlrow sqlr, ajuint column,
383                                AjBool *Pvalue);
384 
385 AjBool ajSqlcolumnNumberToTime(const AjPSqlrow sqlr, ajuint column,
386                                AjPTime *Pvalue);
387 
388 AjBool ajSqlcolumnNumberToUlong(const AjPSqlrow sqlr, ajuint column,
389                                 ajulong *Pvalue);
390 
391 AjBool ajSqlcolumnNumberIsDefined(const AjPSqlrow sqlr, ajuint column);
392 
393 /* AJAX Void Array */
394 
395 AjPVoid ajVoidNew(void);
396 
397 AjPVoid ajVoidNewRes(ajuint size);
398 
399 void ajVoidDel(AjPVoid *thys);
400 
401 void *ajVoidGet(const AjPVoid thys, ajuint elem);
402 
403 ajuint ajVoidLen(const AjPVoid thys);
404 
405 AjBool ajVoidPut(AjPVoid *thys, ajuint elem, void *v);
406 
407 /*
408 ** End of prototype definitions
409 */
410 
411 
412 
413 
414 AJ_END_DECLS
415 
416 #endif /* !AJSQL_H */
417