« back to all changes in this revision
Viewing changes to doc/man/man3/QOFCLI.3
- browse files at revision 8
- compare with another revision
- download diff
- download tarball
- view history from revision 8
- Committer: Bazaar Package Importer
- Author(s): Neil Williams
- Date: 2009-05-24 08:46:26 UTC
- mfrom: (1.1.6 upstream) (3.1.2 squeeze)
- Revision ID: james.westby@ubuntu.com-20090524084626-aj2m6clr8fwoigoz
Tags: 0.1.7-1
* New upstream release
* (Closes: #505073): FTBFS with GCC 4.4: expected
'gint *' but argument is of type 'guint *'
* Add new package to remove translation files from library in
accordance with Policy 8.2 (libqofexpensesobjects-data)
* Add devhelp support.
* Remove Section and Priority duplication in debian/control.
* use upstream symbol versioning support.
* Update Standards Version (no changes)
* SONAME bump for libqofexpensesobjects to enhance support in other
applications.
* Add xsltproc to build depends for doc generation.
* (Closes: #505073): FTBFS with GCC 4.4: expected
'gint *' but argument is of type 'guint *'
* Add new package to remove translation files from library in
accordance with Policy 8.2 (libqofexpensesobjects-data)
* Add devhelp support.
* Remove Section and Priority duplication in debian/control.
* use upstream symbol versioning support.
* Update Standards Version (no changes)
* SONAME bump for libqofexpensesobjects to enhance support in other
applications.
* Add xsltproc to build depends for doc generation.
- files added:
- debian/libqofexpensesobjects-data.install
- files removed:
- debian/libqofexpensesobjects0.install
- doc/man/man3
- files modified:
- ChangeLog
added
removed
doc/man/man3/QOFCLI.3
1
.TH "QOF Command Line Interface" 3 "26 Jun 2008" "Version 0.1.6" "gpe-expenses" \" -*- nroff -*-
2
.ad l
3
.nh
4
.SH NAME
5
QOF Command Line Interface \-
6
.SH "Detailed Description"
7
.PP
8
Includes common functions for all QOF CLI programs and provides generic functions to implement command line and interactive shell options.
9
.PP
10
QOF provides an outline CLI that is easily patched from the qof-generator project to make it easier to keep various QOF projects updated.
11
.PP
12
This CLI is easily extended to support your own functions and options and includes macros to help you keep up to date with changes in main QOF options. It is recommended that you do not edit this file, instead please feed patches back to the QOF-devel mailing list at http://lists.sourceforge.net/mailman/listinfo/qof-devel so that other projects can be updated.
13
.PP
14
.SS "Files"
15
16
.in +1c
17
.ti -1c
18
.RI "file \fBqof-main.c\fP"
19
.br
20
.RI "\fICommon functions for the QOF external framework. \fP"
21
.PP
22
.in +1c
23
24
.ti -1c
25
.RI "file \fBqof-main.h\fP"
26
.br
27
.RI "\fICommon functions for the QOF external framework. \fP"
28
.PP
29
30
.in -1c
31
.SS "Data Structures"
32
33
.in +1c
34
.ti -1c
35
.RI "struct \fBQofMain_s\fP"
36
.br
37
.RI "\fIThe qof-main context struct. \fP"
38
.in -1c
39
.SS "Defines"
40
41
.in +1c
42
.ti -1c
43
.RI "#define \fB_GNU_SOURCE\fP"
44
.br
45
.ti -1c
46
.RI "#define \fBMAX_LINE\fP 79"
47
.br
48
.ti -1c
49
.RI "#define \fBERR_INDENT\fP strlen(PACKAGE) + 2"
50
.br
51
.RI "\fIIndent error messages as paragraphs. \fP"
52
.ti -1c
53
.RI "#define \fBQOF_DATE_STRING_LENGTH\fP MAX_DATE_LENGTH"
54
.br
55
.ti -1c
56
.RI "#define \fBQOF_MAIN_CLI\fP 'QOF-mod-command-line'"
57
.br
58
.ti -1c
59
.RI "#define \fBCATEGORY_NAME\fP 'category'"
60
.br
61
.RI "\fICategory name. \fP"
62
.ti -1c
63
.RI "#define \fBQSF_COMPRESS\fP 'compression_level'"
64
.br
65
.ti -1c
66
.RI "#define \fBQSF_ENCODING\fP 'encoding_string'"
67
.br
68
.ti -1c
69
.RI "#define \fBQSF_DATE_CONVERT\fP 'convert_date_to_time'"
70
.br
71
.ti -1c
72
.RI "#define \fBQOF_SQL_SUPPORTED\fP '^SELECT|INSERT'"
73
.br
74
.ti -1c
75
.RI "#define \fBQOF_CLI_OPTIONS\fP"
76
.br
77
.RI "\fICommon QOF CLI options. \fP"
78
.ti -1c
79
.RI "#define \fBQOF_MAIN_OP\fP"
80
.br
81
.ti -1c
82
.RI "#define \fBQOF_OP_VARS\fP"
83
.br
84
.ti -1c
85
.RI "#define \fBQOF_OP_INIT\fP"
86
.br
87
.in -1c
88
.SS "Typedefs"
89
90
.in +1c
91
.ti -1c
92
.RI "typedef struct \fBQofMain_s\fP \fBQofMainContext\fP"
93
.br
94
.RI "\fIThe qof-main context struct. \fP"
95
.in -1c
96
.SS "Functions"
97
98
.in +1c
99
.ti -1c
100
.RI "void \fBqof_main_wrap_line\fP (FILE *fp, gint indent, const gchar *template_str,...) __attribute__((format(printf"
101
.br
102
.RI "\fIWrap long lines in popt-style. \fP"
103
.ti -1c
104
.RI "gchar * \fBqof_main_make_utf8\fP (gchar *string)"
105
.br
106
.RI "\fIConvert strings received from the wrapped objects into UTF-8. \fP"
107
.ti -1c
108
.RI "static void \fBqof_main_run_sql\fP (\fBQofMainContext\fP *context)"
109
.br
110
.ti -1c
111
.RI "static void \fBqof_main_run_query\fP (\fBQofMainContext\fP *context)"
112
.br
113
.ti -1c
114
.RI "void \fBqof_main_free\fP (\fBQofMainContext\fP *context)"
115
.br
116
.ti -1c
117
.RI "static void \fBfind_param_cb\fP (QofParam *param, gpointer user_data)"
118
.br
119
.ti -1c
120
.RI "static void \fBbuild_database_list\fP (QofIdTypeConst obj_type, \fBQofMainContext\fP *context)"
121
.br
122
.ti -1c
123
.RI "static void \fBselect_cb\fP (QofObject *obj, gpointer data)"
124
.br
125
.ti -1c
126
.RI "void \fBqof_main_moderate_query\fP (\fBQofMainContext\fP *context)"
127
.br
128
.RI "\fIAssemble the components of the query. \fP"
129
.ti -1c
130
.RI "static void \fBoption_cb\fP (QofBackendOption *option, gpointer data)"
131
.br
132
.ti -1c
133
.RI "void \fBqof_mod_compression\fP (gint64 gz_level, \fBQofMainContext\fP *context)"
134
.br
135
.ti -1c
136
.RI "void \fBqof_mod_encoding\fP (const gchar *encoding, \fBQofMainContext\fP *context)"
137
.br
138
.ti -1c
139
.RI "void \fBqof_mod_convert_deprecated\fP (gint64 convert, \fBQofMainContext\fP *context)"
140
.br
141
.ti -1c
142
.RI "void \fBqof_cmd_xmlfile\fP (\fBQofMainContext\fP *context)"
143
.br
144
.ti -1c
145
.RI "static void \fBqof_main_list\fP (QofObject *obj, gpointer G_GNUC_UNUSED data)"
146
.br
147
.ti -1c
148
.RI "void \fBqof_main_select\fP (\fBQofMainContext\fP *context)"
149
.br
150
.ti -1c
151
.RI "void \fBqof_cmd_list\fP (void)"
152
.br
153
.RI "\fILists all databases supported by the current QOF framework. \fP"
154
.ti -1c
155
.RI "static void \fBexplain_cb\fP (QofParam *param, gpointer G_GNUC_UNUSED user_data)"
156
.br
157
.ti -1c
158
.RI "void \fBqof_cmd_explain\fP (\fBQofMainContext\fP *context)"
159
.br
160
.ti -1c
161
.RI "void \fBqof_mod_category\fP (const gchar *category, \fBQofMainContext\fP *data)"
162
.br
163
.RI "\fIShorthand to only query objects that are set to the specified category. \fP"
164
.ti -1c
165
.RI "glong \fBqof_mod_get_local_offset\fP (void)"
166
.br
167
.RI "\fIGet the gmt_off offset for this locale. \fP"
168
.ti -1c
169
.RI "void \fBqof_mod_database\fP (const gchar *database, \fBQofMainContext\fP *data)"
170
.br
171
.RI "\fIShorthand to only query objects within one specific supported database. \fP"
172
.ti -1c
173
.RI "void \fBqof_mod_time\fP (const gchar *date_time, \fBQofMainContext\fP *data)"
174
.br
175
.RI "\fIShorthand to only query objects that contain the specified date. \fP"
176
.ti -1c
177
.RI "void \fBqof_mod_exclude\fP (const gchar *exclude, \fBQofMainContext\fP *data)"
178
.br
179
.RI "\fIShorthand to exclude a supported database from the query. \fP"
180
.ti -1c
181
.RI "void \fBqof_mod_sql\fP (const gchar *sql_query, \fBQofMainContext\fP *data)"
182
.br
183
.RI "\fISpecify a SQL query on the command line. \fP"
184
.ti -1c
185
.RI "void \fBqof_mod_sql_file\fP (const gchar *sql_file, \fBQofMainContext\fP *data)"
186
.br
187
.RI "\fISpecify one or more SQL queries contained in a file. \fP"
188
.ti -1c
189
.RI "void \fBqof_mod_write\fP (const gchar *write_file, \fBQofMainContext\fP *data)"
190
.br
191
.RI "\fIWrite the results of any query to the file. \fP"
192
.ti -1c
193
.RI "void \fBqof_main_show_error\fP (QofSession *session)"
194
.br
195
.RI "\fIOutput error messages from QOF. \fP"
196
.ti -1c
197
.RI "GSList * \fBqof_main_get_param_list\fP (QofIdTypeConst object_type, QofType param_type)"
198
.br
199
.RI "\fIList of all parameters for this object of one QOF type. \fP"
200
.in -1c
201
.SS "Variables"
202
203
.in +1c
204
.ti -1c
205
.RI "static QofLogModule \fBlog_module\fP = 'QOF-mod-command-line'"
206
.br
207
.in -1c
208
.SH "Define Documentation"
209
.PP
210
.SS "#define CATEGORY_NAME 'category'"
211
.PP
212
Category name.
213
.PP
214
The name of the parameter that holds the category of the entity.
215
.PP
216
Many CLI data sources categorise data by user-editable category strings. If your program does not, simply implement a modified QOF_CLI_OPTIONS in your code without the category option:
217
.PP
218
.nf
219
220
{"category", 'c', POPT_ARG_STRING, &category, qof_op_category,
221
_("Shorthand to only query objects that are set to the specified category."),
222
"string"},
223
224
.fi
225
.PP
226
227
.PP
228
Definition at line 118 of file qof-main.h.
229
.SS "#define QOF_CLI_OPTIONS"
230
.PP
231
Common QOF CLI options.
232
.PP
233
These are definitions for popt support in the CLI. Every program's popt table should start with QOF_CLI_OPTIONS or a replacement to insert the standard options into it. Also enables autohelp. End your popt option list with POPT_TABLEEND. If you want to remove any of these options, simply copy QOF_CLI_OPTIONS into a macro of your own and remove the options you do not need.
234
.PP
235
Definition at line 433 of file qof-main.h.
236
.SS "#define QOF_DATE_STRING_LENGTH MAX_DATE_LENGTH"
237
.PP
238
Maximum length of the UTC timestamp used by QSF
239
.PP
240
QOF_UTC_DATE_FORMAT '%Y-%m-%dT%H:%M:%SZ'
241
.PP
242
Definition at line 100 of file qof-main.h.
243
.SS "#define QOF_MAIN_CLI 'QOF-mod-command-line'"
244
.PP
245
Debug module for qof-main
246
.PP
247
Definition at line 103 of file qof-main.h.
248
.SS "#define QOF_MAIN_OP"
249
.PP
250
\fBValue:\fP
251
.PP
252
.nf
253
_(qof_op_noop, = 0) \
254
_(qof_op_list,) \
255
_(qof_op_xmlfile,) \
256
_(qof_op_category,) \
257
_(qof_op_database,) \
258
_(qof_op_time,) \
259
_(qof_op_exclude,) \
260
_(qof_op_sql,) \
261
_(qof_op_sql_file,) \
262
_(qof_op_write, ) \
263
_(qof_op_explain,) \
264
_(qof_op_vers,) \
265
_(qof_op_compress,) \
266
_(qof_op_debug,)
267
.fi
268
use only if you have no extended options, otherwise use as a template.
269
.PP
270
Definition at line 470 of file qof-main.h.
271
.SS "#define QOF_OP_INIT"
272
.PP
273
\fBValue:\fP
274
.PP
275
.nf
276
exclude = NULL; \
277
category = NULL; \
278
database = NULL; \
279
sql_file = NULL; \
280
write_file = NULL; \
281
sql_query = NULL; \
282
filename = NULL;
283
.fi
284
initialise the standard QOF CLI option variables.
285
.PP
286
A simple convenience macro.
287
.PP
288
Definition at line 499 of file qof-main.h.
289
.SS "#define QOF_OP_VARS"
290
.PP
291
\fBValue:\fP
292
.PP
293
.nf
294
const gchar *exclude, *date_time, *category, *database; \
295
const gchar *sql_file, *write_file, *sql_query, *filename;
296
.fi
297
Define the variables for the standard QOF CLI options.
298
.PP
299
If you remove any QOF CLI options, ensure you also remove the option variable and it's initialiser.
300
.PP
301
Definition at line 491 of file qof-main.h.
302
.SS "#define QOF_SQL_SUPPORTED '^SELECT|INSERT'"
303
.PP
304
The SQL commands supported by QOF
305
.PP
306
A regular expression used to exclude unsupported commands from SQL files. Anything that does \fBnot\fP match the expression will be silently ignored. This allows genuine SQL dump files to be parsed without errors.
307
.PP
308
A QOF object is similar to a definition of a SQL table.
309
.br
310
A QOF entity is similar to an instance of a SQL record.
311
.br
312
A QOF parameter is similar to data in a SQL field.
313
.PP
314
Certain SQL commands have no QOF equivalent and should always be ignored silently:
315
.IP "\(bu" 2
316
ALTER (the object parameters cannot be changed at runtime)
317
.IP "\(bu" 2
318
CREATE (new tables - new objects - cannot be created at runtime)
319
.IP "\(bu" 2
320
DROP (an object cannot be 'de-registered' without re-compiling)
321
.IP "\(bu" 2
322
FLUSH (QOF has no permissions system)
323
.IP "\(bu" 2
324
GRANT
325
.IP "\(bu" 2
326
KILL
327
.IP "\(bu" 2
328
LOCK
329
.IP "\(bu" 2
330
OPTIMIZE
331
.IP "\(bu" 2
332
REVOKE
333
.IP "\(bu" 2
334
USE (QOF only has one database, itself.)
335
.PP
336
337
.PP
338
Definition at line 159 of file qof-main.h.
339
.PP
340
Referenced by qof_mod_sql_file().
341
.SS "#define QSF_COMPRESS 'compression_level'"
342
.PP
343
backend configuration index string for QSF
344
.PP
345
The identifier for the configuration option within QSF supported by the CLI. Matches the QofBackendOption->option_name in the KvpFrame holding the options.
346
.PP
347
Definition at line 127 of file qof-main.h.
348
.SS "#define QSF_DATE_CONVERT 'convert_date_to_time'"
349
.PP
350
convert deprecated date fields into times.
351
.PP
352
Definition at line 133 of file qof-main.h.
353
.SS "#define QSF_ENCODING 'encoding_string'"
354
.PP
355
backend configuration encoding string
356
.PP
357
Definition at line 130 of file qof-main.h.
358
.SH "Typedef Documentation"
359
.PP
360
.SS "typedef struct \fBQofMain_s\fP \fBQofMainContext\fP"
361
.PP
362
The qof-main context struct.
363
.PP
364
Intended as a core type for QOF-based CLI programs, wrap your own context struct around qof_main_context
365
.SH "Function Documentation"
366
.PP
367
.SS "void qof_cmd_explain (\fBQofMainContext\fP * context)"
368
.PP
369
Print a list of available parameters for a database.
370
.PP
371
Used with qof_mod_database to print a list of QofParam for the QofObject set in context->database.
372
.PP
373
Definition at line 473 of file qof-main.c.
374
.PP
375
References QofMain_s::database, and QofMain_s::error.
376
.PP
377
.nf
378
474 {
379
475 if (context->error)
380
476 return;
381
477 fprintf (stdout, _('\nParameters of the %s database:\n\n'),
382
478 context->database);
383
479 qof_class_param_foreach (context->database, explain_cb, NULL);
384
480 fprintf (stdout, _('\nThank you for using %s\n\n'), PACKAGE);
385
481 }
386
.fi
387
.PP
388
.SS "void qof_cmd_list (void)"
389
.PP
390
Lists all databases supported by the current QOF framework.
391
.PP
392
Prints the name and description for each object type registered with this instance of QOF. No options are used.
393
.PP
394
Definition at line 445 of file qof-main.c.
395
.PP
396
References qof_main_wrap_line().
397
.PP
398
.nf
399
446 {
400
447 qof_main_wrap_line (stdout, 0,
401
448 /* Translators: This line is wrapped by the program -
402
449 please make sure you do NOT add line endings here. */
403
450 _('\n%s: You can use the supported database names with '%s -d' '
404
451 'and in SQL queries (as the table name) with '%s -s|f'. '
405
452 'Descriptions are shown only for readability.\n'),
406
453 PACKAGE, PACKAGE, PACKAGE);
407
454 fprintf (stdout, '%-20s%-20s\n', _('Name'), _('Description'));
408
455 qof_object_foreach_type (qof_main_list, NULL);
409
456 qof_main_wrap_line (stdout, 0,
410
457 /* Translators: This line is wrapped by the program -
411
458 please make sure you do NOT add line endings here. */
412
459 _('\nUse '%s -d <database> --explain' to see the list of fields '
413
460 'within any supported database.'), PACKAGE);
414
461 fprintf (stdout, _('\nThank you for using %s\n\n'), PACKAGE);
415
462 }
416
.fi
417
.PP
418
.SS "void qof_cmd_xmlfile (\fBQofMainContext\fP * context)"
419
.PP
420
query the QSF XML data
421
.PP
422
Definition at line 383 of file qof-main.c.
423
.PP
424
References QofMain_s::database, QofMain_s::encoding, ERR_INDENT, QofMain_s::exclude, QofMain_s::export_session, QofMain_s::filename, QofMain_s::gz_level, QofMain_s::input_session, qof_main_moderate_query(), qof_main_show_error(), qof_main_wrap_line(), qof_mod_compression(), qof_mod_encoding(), and QofMain_s::write_file.
425
.PP
426
.nf
427
384 {
428
385 QofSession *input_session, *export_session;
429
386
430
387 ENTER (' ');
431
388 input_session = context->input_session;
432
389 if (0 == safe_strcmp (context->exclude, context->database)
433
390 && (context->exclude != NULL))
434
391 {
435
392 qof_main_wrap_line (stderr, ERR_INDENT,
436
393 /* Translators: This line is wrapped by the program -
437
394 please make sure you do NOT add line endings here. */
438
395 _('%s: Error: Cannot exclude database \'%s\' with option -e '
439
396 'because option -d is set to include the database: \'%s\'. '
440
397 'Use the \'-l\' command to see the full list of supported '
441
398 'databases.\n'), PACKAGE, context->exclude,
442
399 context->database);
443
400 qof_session_end (input_session);
444
401 LEAVE (' conflicting options');
445
402 return;
446
403 }
447
404 qof_session_begin (input_session, context->filename, TRUE, FALSE);
448
405 qof_main_show_error (input_session);
449
406 if (0 != safe_strcmp (QOF_STDOUT, context->filename))
450
407 qof_session_load (input_session, NULL);
451
408 qof_main_show_error (input_session);
452
409 export_session = qof_session_new ();
453
410 context->export_session = export_session;
454
411 if (context->write_file)
455
412 {
456
413 qof_session_begin (export_session, context->write_file, TRUE,
457
414 TRUE);
458
415 qof_mod_compression (context->gz_level, context);
459
416 }
460
417 else
461
418 qof_session_begin (export_session, QOF_STDOUT, TRUE, FALSE);
462
419 qof_main_show_error (export_session);
463
420 /* ensure encoding value is set in the new export_session */
464
421 qof_mod_encoding (context->encoding, context);
465
422 qof_main_moderate_query (context);
466
423 qof_session_save (export_session, NULL);
467
424 qof_main_show_error (export_session);
468
425 qof_main_show_error (input_session);
469
426 qof_session_end (input_session);
470
427 qof_session_end (export_session);
471
428 LEAVE (' ');
472
429 }
473
.fi
474
.PP
475
.SS "void qof_main_free (\fBQofMainContext\fP * context)"
476
.PP
477
Free qof_main_context values when work is done.
478
.PP
479
Definition at line 162 of file qof-main.c.
480
.PP
481
References QofMain_s::category, QofMain_s::database, QofMain_s::filename, QofMain_s::sql_file, and QofMain_s::write_file.
482
.PP
483
Referenced by gpe_expense_close().
484
.PP
485
.nf
486
163 {
487
164 g_free (context->filename);
488
165 g_free (context->write_file);
489
166 g_free (context->sql_file);
490
167 g_free (context->database);
491
168 g_free (context->category);
492
169 }
493
.fi
494
.PP
495
.SS "GSList* qof_main_get_param_list (QofIdTypeConst object_type, QofType param_type)"
496
.PP
497
List of all parameters for this object of one QOF type.
498
.PP
499
Return a GSList of all parameters of this object that are a particular QOF type, QOF_TYPE_STRING, QOF_TYPE_BOOLEAN etc.
500
.PP
501
The returned GSList should be freed by the caller.
502
.PP
503
\fBNote:\fP
504
.RS 4
505
The return list is a singly linked list - GSList - \fBnot\fP the doubly-linked list - GList - returned by qof_class_get_referenceList.
506
.RE
507
.PP
508
\fBParameters:\fP
509
.RS 4
510
\fIobject_type\fP object->e_type for the relevant object.
511
.br
512
\fIparam_type\fP The type of parameter to match, QOF_TYPE_STRING etc.
513
.RE
514
.PP
515
\fBReturns:\fP
516
.RS 4
517
GSList of all matching parameters or NULL if none exist.
518
.RE
519
.PP
520
521
.SS "gchar * qof_main_make_utf8 (gchar * string)"
522
.PP
523
Convert strings received from the wrapped objects into UTF-8.
524
.PP
525
\fBDeprecated\fP
526
.RS 4
527
use qof_util_make_utf8 from QOF 0.7.3
528
.RE
529
.PP
530
A wrapper for g_locale_to_utf8 that removes the extra arguments. If the string is already valid UTF-8, it is returned unchanged.
531
.PP
532
\fBReturns:\fP
533
.RS 4
534
the converted string or the original, unchanged, string on error or if the string is already UTF-8.
535
.RE
536
.PP
537
538
.PP
539
Definition at line 103 of file qof-main.c.
540
.PP
541
Referenced by gpe_currency_lookup().
542
.PP
543
.nf
544
104 {
545
105 gchar *value;
546
106
547
107 if (!string)
548
108 return NULL;
549
109 if (g_utf8_validate (string, -1, NULL))
550
110 return string;
551
111 value = g_locale_to_utf8 (string, -1, NULL, NULL, NULL);
552
112 if (!value)
553
113 {
554
114 PWARN (' unable to convert from locale %s', string);
555
115 PINFO ('trying to convert from ISO-8859-15.');
556
116 value = g_convert (string, -1, 'UTF-8', 'ISO-8859-15',
557
117 NULL, NULL, NULL);
558
118 if (!value)
559
119 {
560
120 PERR (' conversion failed');
561
121 return string;
562
122 }
563
123 return value;
564
124 }
565
125 return value;
566
126 }
567
.fi
568
.PP
569
.SS "void qof_main_moderate_query (\fBQofMainContext\fP * context)"
570
.PP
571
Assemble the components of the query.
572
.PP
573
If any SQL statements are found, run separately from any -c, -d or -t options.
574
.PP
575
All queries are additive: Successive queries add more entities to the result set but no entity is set more than once.
576
.PP
577
Definition at line 250 of file qof-main.c.
578
.PP
579
References QofMain_s::database, QofMain_s::exclude, QofMain_s::query, QofMain_s::sql_list, and QofMain_s::sql_str.
580
.PP
581
Referenced by qof_cmd_xmlfile().
582
.PP
583
.nf
584
251 {
585
252 GSList *date_param_list, *category_param_list;
586
253 gboolean all;
587
254
588
255 ENTER (' ');
589
256 all = TRUE;
590
257 context->query = qof_query_create ();
591
258 date_param_list = NULL;
592
259 category_param_list = NULL;
593
260 while (context->sql_list)
594
261 {
595
262 PINFO ('running sql_list');
596
263 context->sql_str = g_strdup (context->sql_list->data);
597
264 qof_main_run_sql (context);
598
265 qof_main_run_query (context);
599
266 if (context->query)
600
267 qof_query_clear (context->query);
601
268 g_free (context->sql_str);
602
269 context->sql_str = NULL;
603
270 all = FALSE;
604
271 context->sql_list = g_list_next (context->sql_list);
605
272 }
606
273 if (0 < g_list_length (context->sql_list))
607
274 {
608
275 context->sql_str = NULL;
609
276 g_list_free (context->sql_list);
610
277 all = FALSE;
611
278 }
612
279 if (context->sql_str != NULL)
613
280 {
614
281 PINFO ('running sql_str');
615
282 qof_main_run_sql (context);
616
283 qof_main_run_query (context);
617
284 if (context->query)
618
285 qof_query_clear (context->query);
619
286 all = FALSE;
620
287 }
621
288 if ((context->exclude != NULL)
622
289 && (qof_class_is_registered (context->exclude)))
623
290 {
624
291 qof_object_foreach_type (select_cb, context);
625
292 all = FALSE;
626
293 }
627
294 if ((context->database != NULL)
628
295 && (qof_class_is_registered (context->database)))
629
296 {
630
297 build_database_list (context->database, context);
631
298 all = FALSE;
632
299 }
633
300 if (all == TRUE)
634
301 qof_object_foreach_type (select_cb, context);
635
302 LEAVE (' ');
636
303 }
637
.fi
638
.PP
639
.SS "void qof_main_show_error (QofSession * session)"
640
.PP
641
Output error messages from QOF.
642
.PP
643
QOF will set errors in the QofSession. The application determines how to output those messages and for the CLI, this will be to stderr. Not all these messages are implemented in any one QOF CLI.
644
.PP
645
\fBParameters:\fP
646
.RS 4
647
\fIsession\fP Any current session.
648
.RE
649
.PP
650
651
.PP
652
Definition at line 629 of file qof-main.c.
653
.PP
654
References ERR_INDENT, and qof_main_wrap_line().
655
.PP
656
Referenced by qof_cmd_xmlfile().
657
.PP
658
.nf
659
630 {
660
631 const gchar *fmt;
661
632
662
633 if (qof_error_check (session))
663
634 {
664
635 fmt = '%s: %s\n';
665
636 qof_main_wrap_line (stderr, ERR_INDENT, fmt, PACKAGE,
666
637 qof_error_get_message (session));
667
638 }
668
639 }
669
.fi
670
.PP
671
.SS "void qof_main_wrap_line (FILE * fp, gint indent, const gchar * template_str, ...)"
672
.PP
673
Wrap long lines in popt-style.
674
.PP
675
Defaults to a line width of 79 characters. Indents lines following the first according to the value of indent.
676
.PP
677
\fBParameters:\fP
678
.RS 4
679
\fIfp\fP A file stream, including stdout or stderr.
680
.br
681
\fIindent\fP The number of characters to indent from the left. Values over or equal to 79 or less than zero are adjusted.
682
.br
683
\fItemplate_str\fP String to be wrapped, containing positional parameters, as specified in the Single Unix Specification. Can be translated but should \fBnot\fP contain newline characters except at the beginning or end of the message.
684
.RE
685
.PP
686
\fBNote:\fP
687
.RS 4
688
Once wrapped, the line has a newline appended. Adding a newline to the incoming string will generate a blank line.
689
.RE
690
.PP
691
692
.PP
693
Definition at line 56 of file qof-main.c.
694
.PP
695
Referenced by qof_cmd_list(), qof_cmd_xmlfile(), qof_main_show_error(), and qof_mod_sql_file().
696
.PP
697
.nf
698
58 {
699
59 gint line_length, msg_length;
700
60 va_list wraps;
701
61 gchar *message;
702
62
703
63 line_length = MAX_LINE;
704
64 /* note the modulus. Don't use CLAMP here */
705
65 /* indent != line_length or particularly close to it. */
706
66 indent = indent >= line_length ? indent % line_length : indent;
707
67 indent = indent < 0 ? 0 : indent;
708
68 message = NULL;
709
69 g_return_if_fail (template);
710
70 va_start (wraps, template);
711
71 message = g_strdup_vprintf (template, wraps);
712
72 va_end (wraps);
713
73 g_return_if_fail (message);
714
74 msg_length = strlen (message);
715
75 while (msg_length > line_length)
716
76 {
717
77 gchar *chunk;
718
78 gchar format[16];
719
79
720
80 chunk = message + line_length - 1;
721
81 while (chunk > message && !g_ascii_isspace (*chunk))
722
82 chunk--;
723
83 if (chunk == message)
724
84 break; /* give up */
725
85 while (chunk > (message + 1) && g_ascii_isspace (*chunk))
726
86 chunk--;
727
87 chunk++;
728
88 g_sprintf (format, '%%.%ds\n%%%ds', (gint) (chunk - message),
729
89 indent);
730
90 g_fprintf (fp, format, message, '');
731
91 message = chunk;
732
92 while (g_ascii_isspace (*message) && *message)
733
93 message++;
734
94 msg_length = strlen (message);
735
95 if (line_length == MAX_LINE)
736
96 line_length -= indent;
737
97 }
738
98 if (msg_length)
739
99 g_fprintf (fp, '%s\n', message);
740
100 }
741
.fi
742
.PP
743
.SS "void qof_mod_category (const gchar * category, \fBQofMainContext\fP * data)"
744
.PP
745
Shorthand to only query objects that are set to the specified category.
746
.PP
747
Modifies the QOF query to only query objects that are set to \fIcategory\fP.
748
.PP
749
Definition at line 484 of file qof-main.c.
750
.PP
751
References QofMain_s::category.
752
.PP
753
.nf
754
485 {
755
486 data->category = g_strdup (category);
756
487 }
757
.fi
758
.PP
759
.SS "void qof_mod_compression (gint64 gz_level, \fBQofMainContext\fP * context)"
760
.PP
761
Pass the requested compression to QSF
762
.PP
763
\fBParameters:\fP
764
.RS 4
765
\fIgz_level\fP Integer between 0 and 9, 9 highest compression, 0 for none.
766
.br
767
\fIcontext\fP The QofMain context.
768
.RE
769
.PP
770
771
.PP
772
Definition at line 327 of file qof-main.c.
773
.PP
774
References QofMain_s::export_session, and QofMain_s::gz_level.
775
.PP
776
Referenced by qof_cmd_xmlfile().
777
.PP
778
.nf
779
328 {
780
329 KvpFrame *be_config;
781
330 QofBook *book;
782
331 QofBackend *be;
783
332
784
333 ENTER (' compression=%' G_GINT64_FORMAT, gz_level);
785
334 if ((gz_level > 0) && (gz_level <= 9))
786
335 {
787
336 book = qof_session_get_book (context->export_session);
788
337 be = qof_book_get_backend (book);
789
338 be_config = qof_backend_get_config (be);
790
339 context->gz_level = gz_level;
791
340 qof_backend_option_foreach (be_config, option_cb, context);
792
341 qof_backend_load_config (be, be_config);
793
342 }
794
343 LEAVE (' ');
795
344 }
796
.fi
797
.PP
798
.SS "void qof_mod_convert_deprecated (gint64 convert, \fBQofMainContext\fP * context)"
799
.PP
800
configure handling of deprecated date fields.
801
.PP
802
Definition at line 364 of file qof-main.c.
803
.PP
804
References QofMain_s::convert, and QofMain_s::export_session.
805
.PP
806
.nf
807
365 {
808
366 KvpFrame *be_config;
809
367 QofBook *book;
810
368 QofBackend *be;
811
369 gboolean set;
812
370
813
371 set = (convert == 0) ? FALSE : TRUE;
814
372 ENTER (' convert deprecated date values? %i No if 0.', set);
815
373 book = qof_session_get_book (context->export_session);
816
374 be = qof_book_get_backend (book);
817
375 be_config = qof_backend_get_config (be);
818
376 context->convert = convert;
819
377 qof_backend_option_foreach (be_config, option_cb, context);
820
378 qof_backend_load_config (be, be_config);
821
379 LEAVE (' ');
822
380 }
823
.fi
824
.PP
825
.SS "void qof_mod_database (const gchar * database, \fBQofMainContext\fP * data)"
826
.PP
827
Shorthand to only query objects within one specific supported database.
828
.PP
829
Used to only query objects within the specified database.
830
.PP
831
Definition at line 504 of file qof-main.c.
832
.PP
833
References QofMain_s::database.
834
.PP
835
.nf
836
505 {
837
506 if (qof_class_is_registered (database))
838
507 data->database = g_strdup (database);
839
508 }
840
.fi
841
.PP
842
.SS "void qof_mod_encoding (const gchar * encoding, \fBQofMainContext\fP * context)"
843
.PP
844
Pass an encoding string to the backend.
845
.PP
846
Definition at line 347 of file qof-main.c.
847
.PP
848
References QofMain_s::encoding, and QofMain_s::export_session.
849
.PP
850
Referenced by qof_cmd_xmlfile().
851
.PP
852
.nf
853
348 {
854
349 KvpFrame *be_config;
855
350 QofBook *book;
856
351 QofBackend *be;
857
352
858
353 ENTER (' encode to %s', encoding);
859
354 book = qof_session_get_book (context->export_session);
860
355 be = qof_book_get_backend (book);
861
356 be_config = qof_backend_get_config (be);
862
357 context->encoding = encoding;
863
358 qof_backend_option_foreach (be_config, option_cb, context);
864
359 qof_backend_load_config (be, be_config);
865
360 LEAVE (' ');
866
361 }
867
.fi
868
.PP
869
.SS "void qof_mod_exclude (const gchar * exclude, \fBQofMainContext\fP * data)"
870
.PP
871
Shorthand to exclude a supported database from the query.
872
.PP
873
Excludes the (single) specified database from the query.
874
.PP
875
Definition at line 559 of file qof-main.c.
876
.PP
877
References QofMain_s::exclude.
878
.PP
879
.nf
880
560 {
881
561 if (qof_class_is_registered (exclude))
882
562 data->exclude = g_strdup (exclude);
883
563 }
884
.fi
885
.PP
886
.SS "glong qof_mod_get_local_offset (void)"
887
.PP
888
Get the gmt_off offset for this locale.
889
.PP
890
User specified strings can be assumed to be in localtime, but values are stored as UTC. This offset allows the application to modify the minimum and maximum time settings for queries so that the user gets the expected results.
891
.PP
892
If the timezone is +0100 and the date is 24th July 2006, values could be stored as 11pm on 23rd July 2006 UTC. qof_mod_get_local_offset returns -86400. Add this value to the minimum and maximum time passed to the query to ensure queries select expected timeframe: 2006-07-23T23:00:00Z to 2006-07-24T22:59:59Z.
893
.PP
894
\fBReturns:\fP
895
.RS 4
896
the number of seconds difference between localtime and UTC.
897
.RE
898
.PP
899
900
.PP
901
Definition at line 490 of file qof-main.c.
902
.PP
903
Referenced by qof_mod_time().
904
.PP
905
.nf
906
491 {
907
492 glong local_offset;
908
493 struct tm local;
909
494 time_t now;
910
495
911
496 local_offset = 0; /* UTC */
912
497 now = time (NULL);
913
498 local = *localtime_r (&now, &local);
914
499 local_offset -= local.tm_gmtoff;
915
500 return local_offset;
916
501 }
917
.fi
918
.PP
919
.SS "void qof_mod_sql (const gchar * sql_query, \fBQofMainContext\fP * data)"
920
.PP
921
Specify a SQL query on the command line.
922
.PP
923
For SELECT, the returned list is a list of all of the instances of 'SomeObj' that match the query. The 'SORT' term is optional. The 'WHERE' term is optional; but if you don't include 'WHERE', you will get a list of all of the object instances. The Boolean operations 'AND' and 'OR' together with parenthesis can be used to construct arbitrarily nested predicates.
924
.PP
925
For INSERT, the returned list is a list containing the newly created instance of 'SomeObj'.
926
.PP
927
Date queries handle full date and time strings, using the format exported by the QSF backend. To query dates and times, convert user input into UTC time using qof_date_print and QOF_DATE_FORMAT_UTC
928
.PP
929
If the param is a KVP frame, then we use a special markup to indicate frame values. The markup should look like /some/kvp/path:value. Thus, for example,
930
.br
931
SELECT * FROM SomeObj WHERE (param_a < '/some/kvp:10.0')
932
.br
933
will search for the object where param_a is a KVP frame, and this KVP frame contains a path '/some/kvp' and the value stored at that path is floating-point and that float value is less than 10.0.
934
.PP
935
\fBParameters:\fP
936
.RS 4
937
\fIsql_query\fP Examples:
938
.RE
939
.PP
940
'select * from pilot_address'
941
.PP
942
'select * from pilot_expenses where type_of_expense = 'Mileage';'
943
.PP
944
'SELECT * from pilot_datebook where start_time > '2004-04-06T00:00Z' and end_time < '2005-04-05T23:59:59Z';'
945
.PP
946
'insert into pilot_todo (description, date_due, todo_priority) values ('put the cat out', '2005-11-24T21:30:00Z', 1)'
947
.PP
948
\fBParameters:\fP
949
.RS 4
950
\fIdata\fP The QofMain context.
951
.RE
952
.PP
953
954
.PP
955
Definition at line 566 of file qof-main.c.
956
.PP
957
References QofMain_s::sql_str.
958
.PP
959
.nf
960
567 {
961
568 data->sql_str = g_strdup (sql_query);
962
569 }
963
.fi
964
.PP
965
.SS "void qof_mod_sql_file (const gchar * sql_file, \fBQofMainContext\fP * data)"
966
.PP
967
Specify one or more SQL queries contained in a file.
968
.PP
969
The rules for single SQL commands also apply with regard to the lack of explicit support for joins and the pending support for selecting only certain parameters from a certain object.
970
.PP
971
See \fBqof_mod_sql\fP for information on the queries supported.
972
.PP
973
Definition at line 572 of file qof-main.c.
974
.PP
975
References ERR_INDENT, qof_main_wrap_line(), QOF_SQL_SUPPORTED, QofMain_s::sql_file, and QofMain_s::sql_list.
976
.PP
977
.nf
978
573 {
979
574 FILE *filehandle;
980
575 #ifndef HAVE_GETLINE
981
576 gchar lineptr[1024];
982
577 #else
983
578 gchar *lineptr;
984
579 #endif
985
580 gchar *buf;
986
581 size_t n;
987
582 QofQuery *q;
988
583 regex_t *r;
989
584 gint reg_exp_check;
990
585 const gchar *fmt;
991
586 static gchar *pattern = QOF_SQL_SUPPORTED;
992
587
993
588 ENTER (' ');
994
589 data->sql_file = g_strdup (sql_file);
995
590 n = 0;
996
591 q = NULL;
997
592 data->sql_list = NULL;
998
593 filehandle = fopen (sql_file, 'r');
999
594 if (!filehandle)
1000
595 {
1001
596 fmt = _('%s: There was an error reading the file '%s'.\n');
1002
597 qof_main_wrap_line (stderr, ERR_INDENT, fmt, PACKAGE, sql_file);
1003
598 return;
1004
599 }
1005
600 r = g_new (regex_t, 1);
1006
601 #ifndef HAVE_GETLINE
1007
602 while (NULL != (fgets (lineptr, sizeof (lineptr), filehandle)))
1008
603 #else
1009
604 lineptr = NULL;
1010
605 while (0 < getline (&lineptr, &n, filehandle))
1011
606 #endif
1012
607 {
1013
608 reg_exp_check =
1014
609 regcomp (r, pattern, REG_ICASE | REG_NOSUB | REG_EXTENDED);
1015
610 g_return_if_fail (reg_exp_check == 0);
1016
611 if (0 != regexec (r, lineptr, 0, NULL, 0))
1017
612 continue;
1018
613 buf = g_strdup (g_strchomp (lineptr));
1019
614 data->sql_list = g_list_prepend (data->sql_list, buf);
1020
615 }
1021
616 regfree (r);
1022
617 g_free (r);
1023
618 fclose (filehandle);
1024
619 LEAVE (' sql_list=%d', g_list_length (data->sql_list));
1025
620 }
1026
.fi
1027
.PP
1028
.SS "void qof_mod_time (const gchar * date_time, \fBQofMainContext\fP * data)"
1029
.PP
1030
Shorthand to only query objects that contain the specified date.
1031
.PP
1032
Used to modify the QOF query to only query objects that contain at least one parameter containing a QOF_TYPE_TIME that matches the range specified. Dates need to be specified as YY-MM-DD, i.e. QOF_DATE_FORMAT_ISO.
1033
.PP
1034
You can specify a UTC timestring, just as normally output by QSF, but the time will not be matched when using the shorthand option, only the year, month and day.
1035
.PP
1036
For more precise time matches or to set a defined period that doesn't follow whole calendar months, (e.g. the UK financial year) use a SQL statement:
1037
.PP
1038
'SELECT * from pilot_datebook where start_time > '2004-04-06T00:00Z'
1039
.br
1040
and end_time < '2005-04-05T23:59:59Z';'
1041
.PP
1042
Partial matches are allowed, so YY-MM matches any object where a date is within the specified month and year, YY matches any object where a date is within the specified year.
1043
.PP
1044
The query range starts at midnight on the first day of the range and ends at 1 second to midnight on the last day of the range.
1045
.PP
1046
Definition at line 511 of file qof-main.c.
1047
.PP
1048
References QofMain_s::max_qt, QofMain_s::min_qt, and qof_mod_get_local_offset().
1049
.PP
1050
.nf
1051
512 {
1052
513 QofDate *qd;
1053
514 gboolean all_year, all_month;
1054
515 gint adding_days;
1055
516 gchar *info;
1056
517
1057
518 /* incoming date is assumed to be localtime */
1058
519 ENTER (' date_time=%s', date_time);
1059
520 all_month = all_year = FALSE;
1060
521 g_return_if_fail (date_time);
1061
522 qd = qof_date_parse (date_time, QOF_DATE_FORMAT_ISO);
1062
523 if (!qd)
1063
524 qd = qof_date_parse (date_time, QOF_DATE_FORMAT_UTC);
1064
525 info = qof_date_print (qd, QOF_DATE_FORMAT_ISO8601);
1065
526 PINFO (' parsed start_time=%s', info);
1066
527 g_free (info);
1067
528 /* set first second of day, UTC */
1068
529 qof_date_set_day_start (qd);
1069
530 data->min_qt = qof_date_to_qtime (qd);
1070
531 /* adjust for incoming localtime */
1071
532 qof_time_add_secs (data->min_qt,
1072
533 qof_mod_get_local_offset());
1073
534 /* year specified but no month or day, select the entire year */
1074
535 if (strlen (date_time) == 4)
1075
536 {
1076
537 PINFO (' match entire year %s', date_time);
1077
538 /* go to end of this year, not first day of next. */
1078
539 adding_days = qof_date_isleap(qd->qd_year) ? 365 : 364;
1079
540 qof_date_adddays (qd, adding_days);
1080
541 }
1081
542 /* month specified, but no day, select entire month */
1082
543 if (strlen (date_time) == 7)
1083
544 {
1084
545 PINFO (' match entire month %s', date_time);
1085
546 adding_days = qof_date_get_mday (qd->qd_mon, qd->qd_year);
1086
547 qof_date_adddays (qd, adding_days - 1);
1087
548 }
1088
549 /* set last second of day */
1089
550 qof_date_set_day_end (qd);
1090
551 data->max_qt = qof_date_to_qtime (qd);
1091
552 /* adjust for incoming localtime */
1092
553 qof_time_add_secs (data->max_qt,
1093
554 qof_mod_get_local_offset());
1094
555 LEAVE (' ');
1095
556 }
1096
.fi
1097
.PP
1098
.SS "void qof_mod_write (const gchar * write_file, \fBQofMainContext\fP * data)"
1099
.PP
1100
Write the results of any query to the file.
1101
.PP
1102
\fIfilename\fP of the file to be written out.
1103
.PP
1104
Definition at line 623 of file qof-main.c.
1105
.PP
1106
References QofMain_s::write_file.
1107
.PP
1108
.nf
1109
624 {
1110
625 data->write_file = g_strdup (write_file);
1111
626 }
1112
.fi
1113
.PP
1114
Loggerhead is a web-based interface for Breezy
Version: 2.0.1