GRASS GIS 8 Programmer's Manual  8.2.2dev(2023)-3d2c704037
cursor.c
Go to the documentation of this file.
1 /*!
2  \file lib/db/dbmi_base/cursor.c
3 
4  \brief DBMI Library (base) - cursors management
5 
6  (C) 1999-2009 by the GRASS Development Team
7 
8  This program is free software under the GNU General Public
9  License (>=v2). Read the file COPYING that comes with GRASS
10  for details.
11 
12  \author Joel Jones (CERL/UIUC), Radim Blazek
13 */
14 
15 #include <stdlib.h>
16 #include <grass/dbmi.h>
17 
18 /*!
19  \brief Initialize dbCursor
20 
21  \param cursor pointer to dbCursor to be initialized
22 */
23 void db_init_cursor(dbCursor *cursor)
24 {
25  G_zero(cursor, sizeof(dbCursor));
26  cursor->token = -1;
27 }
28 
29 /*!
30  \brief Allocate table for cursor
31 
32  \param cursor pointer to dbCursor
33  \param ncols number of column in table
34 
35  \return DB_OK on success
36  \return error code on error
37  */
38 int db_alloc_cursor_table(dbCursor *cursor, int ncols)
39 {
40  cursor->table = db_alloc_table(ncols);
41  if (cursor->table == NULL)
42  return db_get_error_code();
43  return DB_OK;
44 }
45 
46 /*!
47  \brief Free allocated dbCursor
48 
49  \param cursor pointer to dbCursor
50 */
51 void db_free_cursor(dbCursor *cursor)
52 {
53  if (cursor->table)
54  db_free_table(cursor->table);
55  if (cursor->column_flags)
57  db_init_cursor(cursor);
58 }
59 
60 /*!
61  \brief Get table allocated by cursor
62 
63  \param cursor pointer to dbCursor
64 
65  \return pointer to dbTable
66 */
68 {
69  return cursor->table;
70 }
71 
72 /*!
73  \brief Set table for given cursor
74 
75  \param cursor pointer to dbCursor
76  \param table pointer to dbTable
77 */
78 void db_set_cursor_table(dbCursor *cursor, dbTable *table)
79 {
80  cursor->table = table;
81 }
82 
83 /*!
84  \brief Get cursor token
85 
86  \param cursor pointer to dbCursor
87 
88  \return pointer to dbToken
89 */
91 {
92  return cursor->token;
93 }
94 
95 /*!
96  \brief Set cursor token
97 
98  \param cursor pointer to dbCursor
99  \param token pointer to dbToken
100 */
102 {
103  cursor->token = token;
104 }
105 
106 /*!
107  \brief Set cursor to be read-only (select)
108 
109  \param cursor pointer to dbCursor
110 */
112 {
113  cursor->type = DB_READONLY;
114 }
115 
116 /*!
117  \brief Set cursor to be writable (update)
118 
119  \param cursor pointer to dbCursor
120 */
122 {
123  cursor->type = DB_UPDATE;
124 }
125 
126 /*!
127  \brief Set cursor to be writable (insert)
128 
129  \param cursor pointer to dbCursor
130 */
132 {
133  cursor->type = DB_INSERT;
134 }
135 
136 /*!
137  \brief Check cursor type
138 
139  \param cursor pointer to dbCursor
140 
141  \return 1 for known cursor type
142  \return 0 for unknown cursor type
143 */
145 {
146  return (cursor->type == DB_READONLY ||
147  cursor->type == DB_UPDATE ||
148  cursor->type == DB_INSERT);
149 }
150 
151 /*!
152  \brief Check if cursor type is 'update'
153 
154  \param cursor pointer to dbCursor
155 
156  \return 1 if cursor type is 'update'
157  \return 0 otherwise
158 */
160 {
161  return (cursor->type == DB_UPDATE);
162 }
163 
164 /*!
165  \brief Check if cursor type is 'insert'
166 
167  \param cursor pointer to dbCursor
168 
169  \return 1 if cursor type is 'insert'
170  \return 0 otherwise
171 */
173 {
174  return (cursor->type == DB_INSERT);
175 }
176 
177 /*!
178  \brief Set cursor mode
179 
180  Modes:
181  - DB_SCROLL
182  - DB_INSENSITIVE
183 
184  \param cursor pointer to dbCursor
185  \param mode cursor mode
186  */
187 void db_set_cursor_mode(dbCursor *cursor, int mode)
188 {
189  cursor->mode = mode;
190 }
191 
192 /*!
193  \brief Set 'scroll' cursor mode
194 
195  \param cursor pointer to dbCursor
196 */
198 {
199  cursor->mode |= DB_SCROLL;
200 }
201 
202 /*!
203  \brief Unset 'scroll' cursor mode
204 
205  \param cursor pointer to dbCursor
206 */
208 {
209  cursor->mode &= ~DB_SCROLL;
210 }
211 
212 /*!
213  \brief Unset cursor mode
214 
215  \param cursor pointer to dbCursor
216 */
218 {
219  cursor->mode = 0;
220 }
221 
222 /*!
223  \brief Set 'intensive' cursor mode
224 
225  \param cursor pointer to dbCursor
226 */
228 {
229  cursor->mode |= DB_INSENSITIVE;
230 }
231 
232 /*!
233  \brief Unset 'intensive' cursor mode
234 
235  \param cursor pointer to dbCursor
236 */
238 {
239  cursor->mode &= ~DB_INSENSITIVE;
240 }
241 
242 /*!
243  \brief Check if cursor mode is 'scroll'
244 
245  \param cursor pointer to dbCursor
246 
247  \return 1 if true
248  \return 0 if false
249 */
251 {
252  return (cursor->mode & DB_SCROLL);
253 }
254 
255 /*!
256  \brief Check if cursor mode is 'intensive'
257 
258  \param cursor pointer to dbCursor
259 
260  \return 1 if true
261  \return 0 if false
262 */
264 {
265  return (cursor->mode & DB_INSENSITIVE);
266 }
267 
268 /*!
269  \brief Allocate columns' flags for cursor
270 
271  \param cursor pointer to dbCursor
272 
273  \return DB_OK on success
274  \return error code on failure
275 */
277 {
278  int ncols;
279  int col;
280 
281  ncols = db_get_cursor_number_of_columns(cursor);
282  cursor->column_flags = (short *)db_calloc(ncols, sizeof(short));
283  if (cursor->column_flags == NULL)
284  return db_get_error_code();
285  for (col = 0; col < ncols; col++)
286  db_unset_cursor_column_flag(cursor, col);
287  return DB_OK;
288 }
289 
290 /*!
291  \brief Free columns' flags of cursor
292 
293  \param cursor pointer to dbCursor
294 */
296 {
297  if (cursor->column_flags)
298  db_free(cursor->column_flags);
299  cursor->column_flags = NULL;
300 }
301 
302 /*!
303  \brief Set Column flag to 'update'
304 
305  \param cursor pointer to dbCursor
306  \param col column index (starting with '0')
307 */
309 {
310  db_set_cursor_column_flag(cursor, col);
311 }
312 
313 /*!
314  \brief Unset 'update' column flag
315 
316  \param cursor pointer to dbCursor
317  \param col column index (starting with '0')
318 */
320 {
321  db_unset_cursor_column_flag(cursor, col);
322 }
323 
324 /*!
325  \brief Check if column flag is 'update'
326 
327  \param cursor pointer to dbCursor
328  \param col column index (starting with '0')
329 
330  \return 1 if true
331  \return 0 if false
332 */
334 {
335  return db_test_cursor_column_flag(cursor, col);
336 }
337 
338 /*!
339  \brief Check if columns' flag is 'update'
340 
341  \param cursor pointer to dbCursor
342 
343  \return 1 if true
344  \return 0 if false
345 */
347 {
348  return db_test_cursor_any_column_flag(cursor);
349 }
350 
351 /*!
352  \brief Set column's flag
353 
354  \param cursor pointer to dbCursor
355  \param col column index (starting with '0')
356  */
357 void db_set_cursor_column_flag(dbCursor *cursor, int col)
358 {
359  if (cursor->column_flags)
360  cursor->column_flags[col] = 1;
361 }
362 
363 /*!
364  \brief Unset column's flag
365 
366  \param cursor pointer to dbCursor
367  \param col column index (starting with '0')
368  */
369 void db_unset_cursor_column_flag(dbCursor *cursor, int col)
370 {
371  if (cursor->column_flags)
372  cursor->column_flags[col] = 0;
373 }
374 
375 /*!
376  \brief Checks column's flag
377 
378  \param cursor pointer to dbCursor
379  \param col column index (starting with '0')
380 
381  \return 1 if flag is defined
382  \return 0 otherwise
383 */
385 {
386  return cursor->column_flags && cursor->column_flags[col] ? 1 : 0;
387 }
388 
389 /*!
390  \brief Get number of columns
391 
392  \param cursor pointer to dbCursor
393 */
395 {
396  dbTable *table;
397 
398  table = db_get_cursor_table(cursor);
399  if (table)
400  return db_get_table_number_of_columns(table);
401  return 0;
402 }
403 
404 /*!
405  \brief Checks columns' flag
406 
407  Is any cursor column flag set?
408 
409  \param cursor pointer to dbCursor
410 
411  \return 1 if true
412  \return 0 if false
413 */
415 {
416  int ncols, col;
417 
418  ncols = db_get_cursor_number_of_columns(cursor);
419  for (col = 0; col < ncols; col++)
420  if (db_test_cursor_column_flag(cursor, col))
421  return 1;
422  return 0;
423 }
int db_test_cursor_mode_scroll(dbCursor *cursor)
Check if cursor mode is &#39;scroll&#39;.
Definition: cursor.c:250
void db_unset_cursor_mode_insensitive(dbCursor *cursor)
Unset &#39;intensive&#39; cursor mode.
Definition: cursor.c:237
void db_unset_cursor_column_for_update(dbCursor *cursor, int col)
Unset &#39;update&#39; column flag.
Definition: cursor.c:319
#define DB_INSENSITIVE
Definition: dbmi.h:125
#define DB_INSERT
Definition: dbmi.h:121
void db_unset_cursor_mode_scroll(dbCursor *cursor)
Unset &#39;scroll&#39; cursor mode.
Definition: cursor.c:207
void db_set_cursor_column_for_update(dbCursor *cursor, int col)
Set Column flag to &#39;update&#39;.
Definition: cursor.c:308
void db_free_table(dbTable *)
Free the table.
int db_test_cursor_column_flag(dbCursor *cursor, int col)
Checks column&#39;s flag.
Definition: cursor.c:384
int db_test_cursor_mode_insensitive(dbCursor *cursor)
Check if cursor mode is &#39;intensive&#39;.
Definition: cursor.c:263
void db_free(void *)
Free allocated memory.
int dbToken
Definition: dbmi.h:145
#define NULL
Definition: ccmath.h:32
void db_set_cursor_type_readonly(dbCursor *cursor)
Set cursor to be read-only (select)
Definition: cursor.c:111
void db_set_cursor_type_update(dbCursor *cursor)
Set cursor to be writable (update)
Definition: cursor.c:121
#define DB_UPDATE
Definition: dbmi.h:122
#define DB_SCROLL
Definition: dbmi.h:124
void db_init_cursor(dbCursor *cursor)
Initialize dbCursor.
Definition: cursor.c:23
int type
Definition: dbmi.h:236
void db_set_cursor_type_insert(dbCursor *cursor)
Set cursor to be writable (insert)
Definition: cursor.c:131
dbToken db_get_cursor_token(dbCursor *cursor)
Get cursor token.
Definition: cursor.c:90
dbTable * db_get_cursor_table(dbCursor *cursor)
Get table allocated by cursor.
Definition: cursor.c:67
#define DB_READONLY
Definition: dbmi.h:120
int db_get_error_code(void)
Get error code.
void db_set_cursor_column_flag(dbCursor *cursor, int col)
Set column&#39;s flag.
Definition: cursor.c:357
int db_alloc_cursor_column_flags(dbCursor *cursor)
Allocate columns&#39; flags for cursor.
Definition: cursor.c:276
void db_unset_cursor_column_flag(dbCursor *cursor, int col)
Unset column&#39;s flag.
Definition: cursor.c:369
int db_test_cursor_any_column_for_update(dbCursor *cursor)
Check if columns&#39; flag is &#39;update&#39;.
Definition: cursor.c:346
int db_test_cursor_type_insert(dbCursor *cursor)
Check if cursor type is &#39;insert&#39;.
Definition: cursor.c:172
void db_free_cursor_column_flags(dbCursor *cursor)
Free columns&#39; flags of cursor.
Definition: cursor.c:295
dbToken token
Definition: dbmi.h:232
void * db_calloc(int, int)
Allocate memory.
void db_set_cursor_mode(dbCursor *cursor, int mode)
Set cursor mode.
Definition: cursor.c:187
void db_free_cursor(dbCursor *cursor)
Free allocated dbCursor.
Definition: cursor.c:51
dbTable * db_alloc_table(int)
Allocate a table with a specific number of columns.
short * column_flags
Definition: dbmi.h:235
int db_test_cursor_type_fetch(dbCursor *cursor)
Check cursor type.
Definition: cursor.c:144
void G_zero(void *, int)
Zero out a buffer, buf, of length i.
Definition: gis/zero.c:23
int db_get_cursor_number_of_columns(dbCursor *cursor)
Get number of columns.
Definition: cursor.c:394
void db_unset_cursor_mode(dbCursor *cursor)
Unset cursor mode.
Definition: cursor.c:217
void db_set_cursor_token(dbCursor *cursor, dbToken token)
Set cursor token.
Definition: cursor.c:101
void db_set_cursor_table(dbCursor *cursor, dbTable *table)
Set table for given cursor.
Definition: cursor.c:78
void db_set_cursor_mode_insensitive(dbCursor *cursor)
Set &#39;intensive&#39; cursor mode.
Definition: cursor.c:227
int db_get_table_number_of_columns(dbTable *)
Return the number of columns of the table.
int db_alloc_cursor_table(dbCursor *cursor, int ncols)
Allocate table for cursor.
Definition: cursor.c:38
int db_test_cursor_any_column_flag(dbCursor *cursor)
Checks columns&#39; flag.
Definition: cursor.c:414
int mode
Definition: dbmi.h:237
dbTable * table
Definition: dbmi.h:234
int db_test_cursor_type_update(dbCursor *cursor)
Check if cursor type is &#39;update&#39;.
Definition: cursor.c:159
void db_set_cursor_mode_scroll(dbCursor *cursor)
Set &#39;scroll&#39; cursor mode.
Definition: cursor.c:197
int db_test_cursor_column_for_update(dbCursor *cursor, int col)
Check if column flag is &#39;update&#39;.
Definition: cursor.c:333
#define DB_OK
Definition: dbmi.h:71