QOF Command Line Interface
[Query Object Framework]

Detailed Description

Includes common functions for all QOF CLI programs and provides generic functions to implement command line and interactive shell options.

QOF provides an outline CLI that is easily patched from the qof-generator project to make it easier to keep various QOF projects updated.

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.


Files

file  qof-main.c
 Common functions for the QOF external framework.
file  qof-main.h
 Common functions for the QOF external framework.

Data Structures

struct  QofMain_s
 The qof-main context struct. More...

Defines

#define _GNU_SOURCE
#define MAX_LINE   79
#define ERR_INDENT   strlen(PACKAGE) + 2
 Indent error messages as paragraphs.
#define QOF_DATE_STRING_LENGTH   MAX_DATE_LENGTH
#define QOF_MAIN_CLI   "QOF-mod-command-line"
#define CATEGORY_NAME   "category"
 Category name.
#define QSF_COMPRESS   "compression_level"
#define QSF_ENCODING   "encoding_string"
#define QSF_DATE_CONVERT   "convert_date_to_time"
#define QOF_SQL_SUPPORTED   "^SELECT|INSERT"
#define QOF_CLI_OPTIONS
 Common QOF CLI options.
#define QOF_MAIN_OP
#define QOF_OP_VARS
#define QOF_OP_INIT

Typedefs

typedef QofMain_s QofMainContext
 The qof-main context struct.

Functions

void qof_main_wrap_line (FILE *fp, gint indent, const gchar *template_str,...) __attribute__((format(printf
 Wrap long lines in popt-style.
gchar * qof_main_make_utf8 (gchar *string)
 Convert strings received from the wrapped objects into UTF-8.
static void qof_main_run_sql (QofMainContext *context)
static void qof_main_run_query (QofMainContext *context)
void qof_main_free (QofMainContext *context)
static void find_param_cb (QofParam *param, gpointer user_data)
static void build_database_list (QofIdTypeConst obj_type, QofMainContext *context)
static void select_cb (QofObject *obj, gpointer data)
void qof_main_moderate_query (QofMainContext *context)
 Assemble the components of the query.
static void option_cb (QofBackendOption *option, gpointer data)
void qof_mod_compression (gint64 gz_level, QofMainContext *context)
void qof_mod_encoding (const gchar *encoding, QofMainContext *context)
void qof_mod_convert_deprecated (gint64 convert, QofMainContext *context)
void qof_cmd_xmlfile (QofMainContext *context)
static void qof_main_list (QofObject *obj, gpointer data)
void qof_main_select (QofMainContext *context)
void qof_cmd_list (void)
 Lists all databases supported by the current QOF framework.
static void explain_cb (QofParam *param, gpointer user_data)
void qof_cmd_explain (QofMainContext *context)
void qof_mod_category (const gchar *category, QofMainContext *data)
 Shorthand to only query objects that are set to the specified category.
glong qof_mod_get_local_offset (void)
 Get the gmt_off offset for this locale.
void qof_mod_database (const gchar *database, QofMainContext *data)
 Shorthand to only query objects within one specific supported database.
void qof_mod_time (const gchar *date_time, QofMainContext *data)
 Shorthand to only query objects that contain the specified date.
void qof_mod_exclude (const gchar *exclude, QofMainContext *data)
 Shorthand to exclude a supported database from the query.
void qof_mod_sql (const gchar *sql_query, QofMainContext *data)
 Specify a SQL query on the command line.
void qof_mod_sql_file (const gchar *sql_file, QofMainContext *data)
 Specify one or more SQL queries contained in a file.
void qof_mod_write (const gchar *write_file, QofMainContext *data)
 Write the results of any query to the file.
void qof_main_show_error (QofSession *session)
 Output error messages from QOF.
GSList * qof_main_get_param_list (QofIdTypeConst object_type, QofType param_type)
 List of all parameters for this object of one QOF type.

Variables

static QofLogModule log_module = "QOF-mod-command-line"

Define Documentation

#define CATEGORY_NAME   "category"

Category name.

The name of the parameter that holds the category of the entity.

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: 

{"category", 'c', POPT_ARG_STRING, &category, qof_op_category,
_("Shorthand to only query objects that are set to the specified category."),
"string"},

Definition at line 118 of file qof-main.h.

Referenced by build_database_list(), find_invoice_contact(), and pilot_qof_pack().

#define QOF_CLI_OPTIONS

Common QOF CLI options.

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.

Definition at line 433 of file qof-main.h.

Referenced by main().

#define QOF_DATE_STRING_LENGTH   MAX_DATE_LENGTH

Maximum length of the UTC timestamp used by QSF

QOF_UTC_DATE_FORMAT "%Y-%m-%dT%H:%M:%SZ"

Definition at line 100 of file qof-main.h.

#define QOF_MAIN_CLI   "QOF-mod-command-line"

Debug module for qof-main

Definition at line 103 of file qof-main.h.

Referenced by main().

#define QOF_MAIN_OP

Value:

_(qof_op_noop, = 0) \
    _(qof_op_list,)     \
    _(qof_op_xmlfile,)  \
    _(qof_op_category,) \
    _(qof_op_database,) \
    _(qof_op_time,) \
    _(qof_op_exclude,)  \
    _(qof_op_sql,)      \
    _(qof_op_sql_file,) \
    _(qof_op_write, )   \
    _(qof_op_explain,)  \
    _(qof_op_vers,)     \
    _(qof_op_compress,) \
    _(qof_op_debug,)
use only if you have no extended options, otherwise use as a template.

Definition at line 470 of file qof-main.h.

#define QOF_OP_INIT

Value:

exclude = NULL;    \
    category = NULL;   \
    database = NULL;   \
    sql_file = NULL;   \
    write_file = NULL; \
    sql_query = NULL;  \
    filename = NULL;
initialise the standard QOF CLI option variables.

A simple convenience macro.

Definition at line 499 of file qof-main.h.

Referenced by main().

#define QOF_OP_VARS

Value:

const gchar *exclude,  *date_time,  *category,  *database; \
    const gchar *sql_file, *write_file, *sql_query, *filename;
Define the variables for the standard QOF CLI options.

If you remove any QOF CLI options, ensure you also remove the option variable and it's initialiser.

Definition at line 491 of file qof-main.h.

Referenced by main().

#define QOF_SQL_SUPPORTED   "^SELECT|INSERT"

The SQL commands supported by QOF

A regular expression used to exclude unsupported commands from SQL files. Anything that does not match the expression will be silently ignored. This allows genuine SQL dump files to be parsed without errors.

A QOF object is similar to a definition of a SQL table.
A QOF entity is similar to an instance of a SQL record.
A QOF parameter is similar to data in a SQL field.

Certain SQL commands have no QOF equivalent and should always be ignored silently:

Definition at line 159 of file qof-main.h.

Referenced by qof_mod_sql_file().

#define QSF_COMPRESS   "compression_level"

backend configuration index string for QSF

The identifier for the configuration option within QSF supported by the CLI. Matches the QofBackendOption->option_name in the KvpFrame holding the options.

Definition at line 127 of file qof-main.h.

Referenced by option_cb().

#define QSF_DATE_CONVERT   "convert_date_to_time"

convert deprecated date fields into times.

Definition at line 133 of file qof-main.h.

Referenced by option_cb().

#define QSF_ENCODING   "encoding_string"

backend configuration encoding string

Definition at line 130 of file qof-main.h.

Referenced by option_cb().

Typedef Documentation

typedef struct QofMain_s QofMainContext

The qof-main context struct.

Intended as a core type for QOF-based CLI programs, wrap your own context struct around qof_main_context

Function Documentation

void qof_cmd_explain ( QofMainContext *  context  ) 

Print a list of available parameters for a database.

Used with qof_mod_database to print a list of QofParam for the QofObject set in context->database.

Definition at line 465 of file qof-main.c.

References QofMain_s::database, QofMain_s::error, and explain_cb().

Referenced by main().

00466 {
00467     if (context->error)
00468         return;
00469     fprintf (stdout, _("\nParameters of the %s database:\n\n"),
00470         context->database);
00471     qof_class_param_foreach (context->database, explain_cb, NULL);
00472     fprintf (stdout, _("\nThank you for using %s\n\n"), PACKAGE);
00473 }

void qof_cmd_list ( void   ) 

Lists all databases supported by the current QOF framework.

Prints the name and description for each object type registered with this instance of QOF. No options are used.

Definition at line 441 of file qof-main.c.

References qof_main_list(), and qof_main_wrap_line().

Referenced by main().

00442 {
00443     qof_main_wrap_line (stdout, 0,
00444         _("\n%s: You can use the supported database names with '%s -d' "
00445             "and in SQL queries (as the table name) with '%s -s|f'. "
00446             "Descriptions are shown only for readability.\n"),
00447         PACKAGE, PACKAGE, PACKAGE);
00448     fprintf (stdout, "%-20s%-20s\n", _("Name"), _("Description"));
00449     qof_object_foreach_type (qof_main_list, NULL);
00450     qof_main_wrap_line (stdout, 0,
00451         _("\nUse '%s -d <database> --explain' to see the list of fields "
00452             "within any supported database."), PACKAGE);
00453     fprintf (stdout, _("\nThank you for using %s\n\n"), PACKAGE);
00454 }

void qof_cmd_xmlfile ( QofMainContext *  context  ) 

query the QSF XML data

Definition at line 384 of file qof-main.c.

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.

Referenced by main().

00385 {
00386     QofSession *input_session, *export_session;
00387 
00388     ENTER (" ");
00389     input_session = context->input_session;
00390     if (0 == safe_strcmp (context->exclude, context->database)
00391         && (context->exclude != NULL))
00392     {
00393         qof_main_wrap_line (stderr, ERR_INDENT,
00394             _("%s: Error: Cannot exclude database \"%s\" with option -e "
00395                 "because option -d is set to include the database: \"%s\". "
00396                 "Use the \'-l\' command to see the full list of supported "
00397                 "databases.\n"), PACKAGE, context->exclude,
00398             context->database);
00399         qof_session_end (input_session);
00400         LEAVE (" conflicting options");
00401         return;
00402     }
00403     qof_session_begin (input_session, context->filename, TRUE, FALSE);
00404     if (0 != safe_strcmp (QOF_STDOUT, context->filename))
00405         qof_session_load (input_session, NULL);
00406     export_session = qof_session_new ();
00407     context->export_session = export_session;
00408     if (context->write_file)
00409     {
00410         qof_session_begin (export_session, context->write_file, TRUE,
00411             TRUE);
00412         qof_mod_compression (context->gz_level, context);
00413     }
00414     else
00415         qof_session_begin (export_session, QOF_STDOUT, TRUE, TRUE);
00416     /* ensure encoding value is set in the new export_session */
00417     qof_mod_encoding (context->encoding, context);
00418     qof_main_moderate_query (context);
00419     qof_session_save (export_session, NULL);
00420     qof_main_show_error (export_session);
00421     qof_main_show_error (input_session);
00422     qof_session_end (input_session);
00423     qof_session_end (export_session);
00424     LEAVE (" ");
00425 }

void qof_main_free ( QofMainContext *  context  ) 

Free qof_main_context values when work is done.

Definition at line 162 of file qof-main.c.

References QofMain_s::category, QofMain_s::database, QofMain_s::filename, QofMain_s::sql_file, and QofMain_s::write_file.

Referenced by pilot_qof_free().

00163 {
00164     g_free (context->filename);
00165     g_free (context->write_file);
00166     g_free (context->sql_file);
00167     g_free (context->database);
00168     g_free (context->category);
00169 }

GSList* qof_main_get_param_list ( QofIdTypeConst  object_type,
QofType  param_type 
)

List of all parameters for this object of one QOF type.

Return a GSList of all parameters of this object that are a particular QOF type, QOF_TYPE_STRING, QOF_TYPE_BOOLEAN etc.

The returned GSList should be freed by the caller.

Note:
The return list is a singly linked list - GSList - not the doubly-linked list - GList - returned by qof_class_get_referenceList.
Parameters:
object_type object->e_type for the relevant object.
param_type The type of parameter to match, QOF_TYPE_STRING etc.
Returns:
GSList of all matching parameters or NULL if none exist.

gchar * qof_main_make_utf8 ( gchar *  string  ) 

Convert strings received from the wrapped objects into UTF-8.

A wrapper for g_locale_to_utf8 that removes the extra arguments. If the string is already valid UTF-8, it is returned unchanged.

Returns:
the converted string or the original, unchanged, string on error or if the string is already UTF-8.

Definition at line 103 of file qof-main.c.

Referenced by addr_setAddress(), addr_setCategory(), addr_setCity(), addr_setCompany(), addr_setCountry(), addr_setCustomFour(), addr_setCustomOne(), addr_setCustomThree(), addr_setCustomTwo(), addr_setFirstname(), addr_setLastname(), addr_setNote(), addr_setPhoneFive(), addr_setPhoneFour(), addr_setPhoneOne(), addr_setPhoneThree(), addr_setPhoneTwo(), addr_setState(), addr_setTitle(), addr_setZip(), datebook_setCategory(), datebook_setDescription(), datebook_setNote(), exp_setAttendees(), exp_setCategory(), exp_setCity(), exp_setNote(), exp_setVendor(), pq_currency_lookup(), todo_setCategory(), todo_setDescription(), and todo_setNote().

00104 {
00105     gchar *value;
00106 
00107     if (!string)
00108         return NULL;
00109     if (g_utf8_validate (string, -1, NULL))
00110         return string;
00111     value = g_locale_to_utf8 (string, -1, NULL, NULL, NULL);
00112     if (!value)
00113     {
00114         PWARN (" unable to convert from locale %s", string);
00115         PINFO ("trying to convert from ISO-8859-15.");
00116         value = g_convert (string, -1, "UTF-8", "ISO-8859-15",
00117             NULL, NULL, NULL);
00118         if (!value)
00119         {
00120             PERR (" conversion failed");
00121             return string;
00122         }
00123         return value;
00124     }
00125     return value;
00126 }

void qof_main_moderate_query ( QofMainContext *  context  ) 

Assemble the components of the query.

If any SQL statements are found, run separately from any -c, -d or -t options.

All queries are additive: Successive queries add more entities to the result set but no entity is set more than once.

Definition at line 251 of file qof-main.c.

References build_database_list(), QofMain_s::database, QofMain_s::exclude, qof_main_run_query(), qof_main_run_sql(), QofMain_s::query, select_cb(), QofMain_s::sql_list, and QofMain_s::sql_str.

Referenced by pq_invoice_xmlfile(), qof_cmd_hotsync(), and qof_cmd_xmlfile().

00252 {
00253     GSList *date_param_list, *category_param_list;
00254     gboolean all;
00255 
00256     ENTER (" ");
00257     all = TRUE;
00258     context->query = qof_query_create ();
00259     date_param_list = NULL;
00260     category_param_list = NULL;
00261     while (context->sql_list)
00262     {
00263         PINFO ("running sql_list");
00264         context->sql_str = g_strdup (context->sql_list->data);
00265         qof_main_run_sql (context);
00266         qof_main_run_query (context);
00267         if (context->query)
00268             qof_query_clear (context->query);
00269         g_free (context->sql_str);
00270         context->sql_str = NULL;
00271         all = FALSE;
00272         context->sql_list = g_list_next (context->sql_list);
00273     }
00274     if (0 < g_list_length (context->sql_list))
00275     {
00276         context->sql_str = NULL;
00277         g_list_free (context->sql_list);
00278         all = FALSE;
00279     }
00280     if (context->sql_str != NULL)
00281     {
00282         PINFO ("running sql_str");
00283         qof_main_run_sql (context);
00284         qof_main_run_query (context);
00285         if (context->query)
00286             qof_query_clear (context->query);
00287         all = FALSE;
00288     }
00289     if ((context->exclude != NULL)
00290         && (qof_class_is_registered (context->exclude)))
00291     {
00292         qof_object_foreach_type (select_cb, context);
00293         all = FALSE;
00294     }
00295     if ((context->database != NULL)
00296         && (qof_class_is_registered (context->database)))
00297     {
00298         build_database_list (context->database, context);
00299         all = FALSE;
00300     }
00301     if (all == TRUE)
00302         qof_object_foreach_type (select_cb, context);
00303     LEAVE (" ");
00304 }

void qof_main_show_error ( QofSession *  session  ) 

Output error messages from QOF.

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.

Parameters:
session Any current session.

Definition at line 621 of file qof-main.c.

References ERR_INDENT, and qof_main_wrap_line().

Referenced by pq_invoice_xmlfile(), qof_cmd_hotsync(), and qof_cmd_xmlfile().

00622 {
00623     gchar *newfile;
00624     const gchar *fmt;
00625     QofErrorId id;
00626 
00627     newfile = g_strdup (qof_session_get_file_path (session));
00628     id = qof_error_check (session);
00629     if (id != QOF_SUCCESS)
00630     {
00633         fmt = _("%s: %d %s\n");
00634         qof_main_wrap_line (stderr, ERR_INDENT, fmt, PACKAGE,
00635             id, qof_error_get_message (session));
00636         qof_error_clear (session);
00637     }
00638     g_free (newfile);
00639 }

void qof_main_wrap_line ( FILE *  fp,
gint  indent,
const gchar *  template_str,
  ... 
)

Wrap long lines in popt-style.

Defaults to a line width of 79 characters. Indents lines following the first according to the value of indent.

Parameters:
fp A file stream, including stdout or stderr.
indent The number of characters to indent from the left. Values over or equal to 79 or less than zero are adjusted.
template_str String to be wrapped, containing positional parameters, as specified in the Single Unix Specification. Can be translated but should not contain newline characters except at the beginning or end of the message.
Note:
Once wrapped, the line has a newline appended. Adding a newline to the incoming string will generate a blank line.

Definition at line 56 of file qof-main.c.

References MAX_LINE.

Referenced by main(), qof_cmd_hotsync(), qof_cmd_list(), qof_cmd_xmlfile(), qof_main_show_error(), and qof_mod_sql_file().

00058 {
00059     gint line_length, msg_length;
00060     va_list wraps;
00061     gchar *message;
00062 
00063     line_length = MAX_LINE;
00064     /* note the modulus. Don't use CLAMP here */
00065     /* indent != line_length or particularly close to it. */
00066     indent = indent >= line_length ? indent % line_length : indent;
00067     indent = indent < 0 ? 0 : indent;
00068     message = NULL;
00069     g_return_if_fail (template);
00070     va_start (wraps, template);
00071     message = g_strdup_vprintf (template, wraps);
00072     va_end (wraps);
00073     g_return_if_fail (message);
00074     msg_length = strlen (message);
00075     while (msg_length > line_length)
00076     {
00077         gchar *chunk;
00078         gchar format[16];
00079 
00080         chunk = message + line_length - 1;
00081         while (chunk > message && !g_ascii_isspace (*chunk))
00082             chunk--;
00083         if (chunk == message)
00084             break;              /* give up */
00085         while (chunk > (message + 1) && g_ascii_isspace (*chunk))
00086             chunk--;
00087         chunk++;
00088         g_sprintf (format, "%%.%ds\n%%%ds", (gint) (chunk - message),
00089             indent);
00090         g_fprintf (fp, format, message, "");
00091         message = chunk;
00092         while (g_ascii_isspace (*message) && *message)
00093             message++;
00094         msg_length = strlen (message);
00095         if (line_length == MAX_LINE)
00096             line_length -= indent;
00097     }
00098     if (msg_length)
00099         g_fprintf (fp, "%s\n", message);
00100 }

void qof_mod_category ( const gchar *  category,
QofMainContext *  data 
)

Shorthand to only query objects that are set to the specified category.

Modifies the QOF query to only query objects that are set to category.

Definition at line 476 of file qof-main.c.

References QofMain_s::category.

Referenced by main().

00477 {
00478     data->category = g_strdup (category);
00479 }

void qof_mod_compression ( gint64  gz_level,
QofMainContext *  context 
)

Pass the requested compression to QSF

Parameters:
gz_level Integer between 0 and 9, 9 highest compression, 0 for none.
context The QofMain context.

Definition at line 328 of file qof-main.c.

References QofMain_s::export_session, QofMain_s::gz_level, and option_cb().

Referenced by pq_invoice_xmlfile(), qof_cmd_hotsync(), and qof_cmd_xmlfile().

00329 {
00330     KvpFrame *be_config;
00331     QofBook *book;
00332     QofBackend *be;
00333 
00334     ENTER (" compression=%" G_GINT64_FORMAT, gz_level);
00335     if ((gz_level > 0) && (gz_level <= 9))
00336     {
00337         book = qof_session_get_book (context->export_session);
00338         be = qof_book_get_backend (book);
00339         be_config = qof_backend_get_config (be);
00340         context->gz_level = gz_level;
00341         qof_backend_option_foreach (be_config, option_cb, context);
00342         qof_backend_load_config (be, be_config);
00343     }
00344     LEAVE (" ");
00345 }

void qof_mod_convert_deprecated ( gint64  convert,
QofMainContext *  context 
)

configure handling of deprecated date fields.

Definition at line 365 of file qof-main.c.

References QofMain_s::convert, QofMain_s::export_session, and option_cb().

Referenced by main().

00366 {
00367     KvpFrame *be_config;
00368     QofBook *book;
00369     QofBackend *be;
00370     gboolean set;
00371 
00372     set = (convert == 0) ? FALSE : TRUE;
00373     ENTER (" convert deprecated date values? %i No if 0.", set);
00374     book = qof_session_get_book (context->export_session);
00375     be = qof_book_get_backend (book);
00376     be_config = qof_backend_get_config (be);
00377     context->convert = convert;
00378     qof_backend_option_foreach (be_config, option_cb, context);
00379     qof_backend_load_config (be, be_config);
00380     LEAVE (" ");
00381 }

void qof_mod_database ( const gchar *  database,
QofMainContext *  data 
)

Shorthand to only query objects within one specific supported database.

Used to only query objects within the specified database.

Definition at line 496 of file qof-main.c.

References QofMain_s::database.

Referenced by main().

00497 {
00498     if (qof_class_is_registered (database))
00499         data->database = g_strdup (database);
00500 }

void qof_mod_encoding ( const gchar *  encoding,
QofMainContext *  context 
)

Pass an encoding string to the backend.

Definition at line 348 of file qof-main.c.

References QofMain_s::encoding, QofMain_s::export_session, and option_cb().

Referenced by main(), and qof_cmd_xmlfile().

00349 {
00350     KvpFrame *be_config;
00351     QofBook *book;
00352     QofBackend *be;
00353 
00354     ENTER (" encode to %s", encoding);
00355     book = qof_session_get_book (context->export_session);
00356     be = qof_book_get_backend (book);
00357     be_config = qof_backend_get_config (be);
00358     context->encoding = encoding;
00359     qof_backend_option_foreach (be_config, option_cb, context);
00360     qof_backend_load_config (be, be_config);
00361     LEAVE (" ");
00362 }

void qof_mod_exclude ( const gchar *  exclude,
QofMainContext *  data 
)

Shorthand to exclude a supported database from the query.

Excludes the (single) specified database from the query.

Definition at line 551 of file qof-main.c.

References QofMain_s::exclude.

Referenced by main().

00552 {
00553     if (qof_class_is_registered (exclude))
00554         data->exclude = g_strdup (exclude);
00555 }

glong qof_mod_get_local_offset ( void   ) 

Get the gmt_off offset for this locale.

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.

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.

Returns:
the number of seconds difference between localtime and UTC.

Definition at line 482 of file qof-main.c.

Referenced by qof_mod_time().

00483 {
00484     glong local_offset;
00485     struct tm local;
00486     time_t now;
00487 
00488     local_offset = 0; /* UTC */
00489     now = time (NULL);
00490     local = *localtime_r (&now, &local);
00491     local_offset -= local.tm_gmtoff;
00492     return local_offset;
00493 }

void qof_mod_sql ( const gchar *  sql_query,
QofMainContext *  data 
)

Specify a SQL query on the command line.

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.

For INSERT, the returned list is a list containing the newly created instance of 'SomeObj'.

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

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,
SELECT * FROM SomeObj WHERE (param_a < '/some/kvp:10.0')
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.

Parameters:
sql_query Examples:
"select * from pilot_address"

"select * from pilot_expenses where type_of_expense = 'Mileage';"

"SELECT * from pilot_datebook where start_time > '2004-04-06T00:00Z' and end_time < '2005-04-05T23:59:59Z';"

"insert into pilot_todo (description, date_due, todo_priority) values ('put the cat out', '2005-11-24T21:30:00Z', 1)"

Parameters:
data The QofMain context.

Definition at line 558 of file qof-main.c.

References QofMain_s::sql_str.

Referenced by main().

00559 {
00560     data->sql_str = g_strdup (sql_query);
00561 }

void qof_mod_sql_file ( const gchar *  sql_file,
QofMainContext *  data 
)

Specify one or more SQL queries contained in a file.

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.

See qof_mod_sql for information on the queries supported.

Definition at line 564 of file qof-main.c.

References ERR_INDENT, qof_main_wrap_line(), QOF_SQL_SUPPORTED, QofMain_s::sql_file, and QofMain_s::sql_list.

Referenced by main().

00565 {
00566     FILE *filehandle;
00567 #ifndef HAVE_GETLINE
00568     gchar lineptr[1024];
00569 #else
00570     gchar *lineptr;
00571 #endif
00572     gchar *buf;
00573     size_t n;
00574     QofQuery *q;
00575     regex_t *r;
00576     gint reg_exp_check;
00577     const gchar *fmt;
00578     static gchar *pattern = QOF_SQL_SUPPORTED;
00579 
00580     ENTER (" ");
00581     data->sql_file = g_strdup (sql_file);
00582     n = 0;
00583     q = NULL;
00584     data->sql_list = NULL;
00585     filehandle = fopen (sql_file, "r");
00586     if (!filehandle)
00587     {
00588         fmt = _("%s: There was an error reading the file '%s'.\n");
00589         qof_main_wrap_line (stderr, ERR_INDENT, fmt, PACKAGE, sql_file);
00590         return;
00591     }
00592     r = g_new (regex_t, 1);
00593 #ifndef HAVE_GETLINE
00594     while (NULL != (fgets (lineptr, sizeof (lineptr), filehandle)))
00595 #else
00596     lineptr = NULL;
00597     while (0 < getline (&lineptr, &n, filehandle))
00598 #endif
00599     {
00600         reg_exp_check =
00601             regcomp (r, pattern, REG_ICASE | REG_NOSUB | REG_EXTENDED);
00602         g_return_if_fail (reg_exp_check == 0);
00603         if (0 != regexec (r, lineptr, 0, NULL, 0))
00604             continue;
00605         buf = g_strdup (g_strchomp (lineptr));
00606         data->sql_list = g_list_prepend (data->sql_list, buf);
00607     }
00608     regfree (r);
00609     g_free (r);
00610     fclose (filehandle);
00611     LEAVE (" sql_list=%d", g_list_length (data->sql_list));
00612 }

void qof_mod_time ( const gchar *  date_time,
QofMainContext *  data 
)

Shorthand to only query objects that contain the specified date.

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.

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.

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:

"SELECT * from pilot_datebook where start_time > '2004-04-06T00:00Z'
and end_time < '2005-04-05T23:59:59Z';"

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.

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.

Definition at line 503 of file qof-main.c.

References QofMain_s::max_qt, QofMain_s::min_qt, and qof_mod_get_local_offset().

Referenced by main().

00504 {
00505     QofDate *qd;
00506     gboolean all_year, all_month;
00507     gint adding_days;
00508     gchar *info;
00509 
00510     /* incoming date is assumed to be localtime */
00511     ENTER (" date_time=%s", date_time);
00512     all_month = all_year = FALSE;
00513     g_return_if_fail (date_time);
00514     qd = qof_date_parse (date_time, QOF_DATE_FORMAT_ISO);
00515     if (!qd)
00516         qd = qof_date_parse (date_time, QOF_DATE_FORMAT_UTC);
00517     info = qof_date_print (qd, QOF_DATE_FORMAT_ISO8601);
00518     PINFO (" parsed start_time=%s", info);
00519     g_free (info);
00520     /* set first second of day, UTC */
00521     qof_date_set_day_start (qd);
00522     data->min_qt = qof_date_to_qtime (qd);
00523     /* adjust for incoming localtime */
00524     qof_time_add_secs (data->min_qt, 
00525         qof_mod_get_local_offset());
00526     /* year specified but no month or day, select the entire year */
00527     if (strlen (date_time) == 4)
00528     {
00529         PINFO (" match entire year %s", date_time);
00530         /* go to end of this year, not first day of next. */
00531         adding_days = qof_date_isleap(qd->qd_year) ? 365 : 364;
00532         qof_date_adddays (qd, adding_days);
00533     }
00534     /* month specified, but no day, select entire month */
00535     if (strlen (date_time) == 7)
00536     {
00537         PINFO (" match entire month %s", date_time);
00538         adding_days = qof_date_get_mday (qd->qd_mon, qd->qd_year);
00539         qof_date_adddays (qd, adding_days - 1);
00540     }
00541     /* set last second of day */
00542     qof_date_set_day_end (qd);
00543     data->max_qt = qof_date_to_qtime (qd);
00544     /* adjust for incoming localtime */
00545     qof_time_add_secs (data->max_qt, 
00546         qof_mod_get_local_offset());
00547     LEAVE (" ");
00548 }

void qof_mod_write ( const gchar *  write_file,
QofMainContext *  data 
)

Write the results of any query to the file.

filename of the file to be written out.

Definition at line 615 of file qof-main.c.

References QofMain_s::write_file.

Referenced by main().

00616 {
00617     data->write_file = g_strdup (write_file);
00618 }

Generated on Tue Mar 6 00:08:10 2007 for pilot-qof by  doxygen 1.5.1