GRASS GIS 8 Programmer's Manual  8.4.0dev(2024)-7413740dd8
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 || cursor->type == DB_UPDATE ||
147  cursor->type == DB_INSERT);
148 }
149 
150 /*!
151  \brief Check if cursor type is 'update'
152 
153  \param cursor pointer to dbCursor
154 
155  \return 1 if cursor type is 'update'
156  \return 0 otherwise
157  */
159 {
160  return (cursor->type == DB_UPDATE);
161 }
162 
163 /*!
164  \brief Check if cursor type is 'insert'
165 
166  \param cursor pointer to dbCursor
167 
168  \return 1 if cursor type is 'insert'
169  \return 0 otherwise
170  */
172 {
173  return (cursor->type == DB_INSERT);
174 }
175 
176 /*!
177  \brief Set cursor mode
178 
179  Modes:
180  - DB_SCROLL
181  - DB_INSENSITIVE
182 
183  \param cursor pointer to dbCursor
184  \param mode cursor mode
185  */
186 void db_set_cursor_mode(dbCursor *cursor, int mode)
187 {
188  cursor->mode = mode;
189 }
190 
191 /*!
192  \brief Set 'scroll' cursor mode
193 
194  \param cursor pointer to dbCursor
195  */
197 {
198  cursor->mode |= DB_SCROLL;
199 }
200 
201 /*!
202  \brief Unset 'scroll' cursor mode
203 
204  \param cursor pointer to dbCursor
205  */
207 {
208  cursor->mode &= ~DB_SCROLL;
209 }
210 
211 /*!
212  \brief Unset cursor mode
213 
214  \param cursor pointer to dbCursor
215  */
217 {
218  cursor->mode = 0;
219 }
220 
221 /*!
222  \brief Set 'intensive' cursor mode
223 
224  \param cursor pointer to dbCursor
225  */
227 {
228  cursor->mode |= DB_INSENSITIVE;
229 }
230 
231 /*!
232  \brief Unset 'intensive' cursor mode
233 
234  \param cursor pointer to dbCursor
235  */
237 {
238  cursor->mode &= ~DB_INSENSITIVE;
239 }
240 
241 /*!
242  \brief Check if cursor mode is 'scroll'
243 
244  \param cursor pointer to dbCursor
245 
246  \return 1 if true
247  \return 0 if false
248  */
250 {
251  return (cursor->mode & DB_SCROLL);
252 }
253 
254 /*!
255  \brief Check if cursor mode is 'intensive'
256 
257  \param cursor pointer to dbCursor
258 
259  \return 1 if true
260  \return 0 if false
261  */
263 {
264  return (cursor->mode & DB_INSENSITIVE);
265 }
266 
267 /*!
268  \brief Allocate columns' flags for cursor
269 
270  \param cursor pointer to dbCursor
271 
272  \return DB_OK on success
273  \return error code on failure
274  */
276 {
277  int ncols;
278  int col;
279 
280  ncols = db_get_cursor_number_of_columns(cursor);
281  cursor->column_flags = (short *)db_calloc(ncols, sizeof(short));
282  if (cursor->column_flags == NULL)
283  return db_get_error_code();
284  for (col = 0; col < ncols; col++)
285  db_unset_cursor_column_flag(cursor, col);
286  return DB_OK;
287 }
288 
289 /*!
290  \brief Free columns' flags of cursor
291 
292  \param cursor pointer to dbCursor
293  */
295 {
296  if (cursor->column_flags)
297  db_free(cursor->column_flags);
298  cursor->column_flags = NULL;
299 }
300 
301 /*!
302  \brief Set Column flag to 'update'
303 
304  \param cursor pointer to dbCursor
305  \param col column index (starting with '0')
306  */
308 {
309  db_set_cursor_column_flag(cursor, col);
310 }
311 
312 /*!
313  \brief Unset 'update' column flag
314 
315  \param cursor pointer to dbCursor
316  \param col column index (starting with '0')
317  */
319 {
320  db_unset_cursor_column_flag(cursor, col);
321 }
322 
323 /*!
324  \brief Check if column flag is 'update'
325 
326  \param cursor pointer to dbCursor
327  \param col column index (starting with '0')
328 
329  \return 1 if true
330  \return 0 if false
331  */
333 {
334  return db_test_cursor_column_flag(cursor, col);
335 }
336 
337 /*!
338  \brief Check if columns' flag is 'update'
339 
340  \param cursor pointer to dbCursor
341 
342  \return 1 if true
343  \return 0 if false
344  */
346 {
347  return db_test_cursor_any_column_flag(cursor);
348 }
349 
350 /*!
351  \brief Set column's flag
352 
353  \param cursor pointer to dbCursor
354  \param col column index (starting with '0')
355  */
356 void db_set_cursor_column_flag(dbCursor *cursor, int col)
357 {
358  if (cursor->column_flags)
359  cursor->column_flags[col] = 1;
360 }
361 
362 /*!
363  \brief Unset column's flag
364 
365  \param cursor pointer to dbCursor
366  \param col column index (starting with '0')
367  */
368 void db_unset_cursor_column_flag(dbCursor *cursor, int col)
369 {
370  if (cursor->column_flags)
371  cursor->column_flags[col] = 0;
372 }
373 
374 /*!
375  \brief Checks column's flag
376 
377  \param cursor pointer to dbCursor
378  \param col column index (starting with '0')
379 
380  \return 1 if flag is defined
381  \return 0 otherwise
382  */
384 {
385  return cursor->column_flags && cursor->column_flags[col] ? 1 : 0;
386 }
387 
388 /*!
389  \brief Get number of columns
390 
391  \param cursor pointer to dbCursor
392  */
394 {
395  dbTable *table;
396 
397  table = db_get_cursor_table(cursor);
398  if (table)
399  return db_get_table_number_of_columns(table);
400  return 0;
401 }
402 
403 /*!
404  \brief Checks columns' flag
405 
406  Is any cursor column flag set?
407 
408  \param cursor pointer to dbCursor
409 
410  \return 1 if true
411  \return 0 if false
412  */
414 {
415  int ncols, col;
416 
417  ncols = db_get_cursor_number_of_columns(cursor);
418  for (col = 0; col < ncols; col++)
419  if (db_test_cursor_column_flag(cursor, col))
420  return 1;
421  return 0;
422 }
#define NULL
Definition: ccmath.h:32
void db_set_cursor_mode_scroll(dbCursor *cursor)
Set 'scroll' cursor mode.
Definition: cursor.c:196
void db_set_cursor_token(dbCursor *cursor, dbToken token)
Set cursor token.
Definition: cursor.c:101
int db_test_cursor_any_column_for_update(dbCursor *cursor)
Check if columns' flag is 'update'.
Definition: cursor.c:345
int db_alloc_cursor_table(dbCursor *cursor, int ncols)
Allocate table for cursor.
Definition: cursor.c:38
void db_free_cursor(dbCursor *cursor)
Free allocated dbCursor.
Definition: cursor.c:51
void db_free_cursor_column_flags(dbCursor *cursor)
Free columns' flags of cursor.
Definition: cursor.c:294
dbToken db_get_cursor_token(dbCursor *cursor)
Get cursor token.
Definition: cursor.c:90
int db_test_cursor_type_fetch(dbCursor *cursor)
Check cursor type.
Definition: cursor.c:144
int db_test_cursor_mode_scroll(dbCursor *cursor)
Check if cursor mode is 'scroll'.
Definition: cursor.c:249
void db_unset_cursor_mode_insensitive(dbCursor *cursor)
Unset 'intensive' cursor mode.
Definition: cursor.c:236
void db_unset_cursor_column_for_update(dbCursor *cursor, int col)
Unset 'update' column flag.
Definition: cursor.c:318
void db_set_cursor_table(dbCursor *cursor, dbTable *table)
Set table for given cursor.
Definition: cursor.c:78
int db_test_cursor_column_flag(dbCursor *cursor, int col)
Checks column's flag.
Definition: cursor.c:383
void db_set_cursor_type_readonly(dbCursor *cursor)
Set cursor to be read-only (select)
Definition: cursor.c:111
void db_init_cursor(dbCursor *cursor)
Initialize dbCursor.
Definition: cursor.c:23
int db_test_cursor_type_update(dbCursor *cursor)
Check if cursor type is 'update'.
Definition: cursor.c:158
int db_alloc_cursor_column_flags(dbCursor *cursor)
Allocate columns' flags for cursor.
Definition: cursor.c:275
int db_test_cursor_column_for_update(dbCursor *cursor, int col)
Check if column flag is 'update'.
Definition: cursor.c:332
void db_set_cursor_mode_insensitive(dbCursor *cursor)
Set 'intensive' cursor mode.
Definition: cursor.c:226
void db_set_cursor_type_insert(dbCursor *cursor)
Set cursor to be writable (insert)
Definition: cursor.c:131
void db_set_cursor_column_for_update(dbCursor *cursor, int col)
Set Column flag to 'update'.
Definition: cursor.c:307
void db_unset_cursor_mode_scroll(dbCursor *cursor)
Unset 'scroll' cursor mode.
Definition: cursor.c:206
dbTable * db_get_cursor_table(dbCursor *cursor)
Get table allocated by cursor.
Definition: cursor.c:67
int db_get_cursor_number_of_columns(dbCursor *cursor)
Get number of columns.
Definition: cursor.c:393
void db_unset_cursor_mode(dbCursor *cursor)
Unset cursor mode.
Definition: cursor.c:216
void db_set_cursor_type_update(dbCursor *cursor)
Set cursor to be writable (update)
Definition: cursor.c:121
int db_test_cursor_type_insert(dbCursor *cursor)
Check if cursor type is 'insert'.
Definition: cursor.c:171
int db_test_cursor_any_column_flag(dbCursor *cursor)
Checks columns' flag.
Definition: cursor.c:413
void db_set_cursor_mode(dbCursor *cursor, int mode)
Set cursor mode.
Definition: cursor.c:186
int db_test_cursor_mode_insensitive(dbCursor *cursor)
Check if cursor mode is 'intensive'.
Definition: cursor.c:262
void db_unset_cursor_column_flag(dbCursor *cursor, int col)
Unset column's flag.
Definition: cursor.c:368
void db_set_cursor_column_flag(dbCursor *cursor, int col)
Set column's flag.
Definition: cursor.c:356
int dbToken
Definition: dbmi.h:145
#define DB_INSENSITIVE
Definition: dbmi.h:125
#define DB_SCROLL
Definition: dbmi.h:124
#define DB_UPDATE
Definition: dbmi.h:122
#define DB_OK
Definition: dbmi.h:71
#define DB_INSERT
Definition: dbmi.h:121
#define DB_READONLY
Definition: dbmi.h:120
void * db_calloc(int, int)
Allocate memory.
void db_free_table(dbTable *)
Free the table.
int db_get_error_code(void)
Get error code.
void db_free(void *)
Free allocated memory.
dbTable * db_alloc_table(int)
Allocate a table with a specific number of columns.
int db_get_table_number_of_columns(dbTable *)
Return the number of columns of the table.
void G_zero(void *, int)
Zero out a buffer, buf, of length i.
Definition: gis/zero.c:23
short * column_flags
Definition: dbmi.h:225
int mode
Definition: dbmi.h:227
dbTable * table
Definition: dbmi.h:224
int type
Definition: dbmi.h:226
dbToken token
Definition: dbmi.h:222