![]() |
![]() |
![]() |
GNOME Data Access 4 manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Properties |
#include <sql-parser/gda-sql-parser.h> GdaSqlParser; enum GdaSqlParserMode; GdaSqlParser * gda_sql_parser_new (void
); GdaStatement * gda_sql_parser_parse_string (GdaSqlParser *parser
,const gchar *sql
,const gchar **remain
,GError **error
); GdaBatch * gda_sql_parser_parse_string_as_batch (GdaSqlParser *parser
,const gchar *sql
,const gchar **remain
,GError **error
); GdaBatch * gda_sql_parser_parse_file_as_batch (GdaSqlParser *parser
,const gchar *filename
,GError **error
); gchar * gda_sql_identifier_quote (const gchar *id
,GdaConnection *cnc
,GdaServerProvider *prov
,gboolean meta_store_convention
,gboolean force_quotes
); gboolean gda_sql_identifier_needs_quotes (const gchar *str
); gchar * gda_sql_identifier_add_quotes (const gchar *str
); gchar * gda_sql_identifier_remove_quotes (gchar *str
); gchar ** gda_sql_identifier_split (const gchar *id
);
"column-error" gint : Read "line-error" gint : Read "mode" gint : Read / Write "tokenizer-flavour" gint : Read / Write
typedef enum { GDA_SQL_PARSER_MODE_PARSE, GDA_SQL_PARSER_MODE_DELIMIT } GdaSqlParserMode;
GdaSqlParser * gda_sql_parser_new (void
);
Creates a new GdaSqlParser object
Returns : |
the new object |
GdaStatement * gda_sql_parser_parse_string (GdaSqlParser *parser
,const gchar *sql
,const gchar **remain
,GError **error
);
Parses sql
and creates a GdaStatement statement from the first SQL statement contained in sql
: if sql
contains more than one statement, then the remaining part of the string is not parsed at all, and remain
(if
not NULL
) will point at the first non parsed character.
To include variables in the sql
string, see the
GdaSqlParser's object description.
|
a GdaSqlParser object |
|
the SQL string to parse |
|
location to store a pointer to remaining part of sql in case sql has multiple statement, or NULL . [out][allow-none]
|
|
location to store error, or NULL
|
Returns : |
a new GdaStatement object, or NULL if an error occurred. [transfer full][allow-none]
|
GdaBatch * gda_sql_parser_parse_string_as_batch (GdaSqlParser *parser
,const gchar *sql
,const gchar **remain
,GError **error
);
Parse sql
and creates a GdaBatch object which contains all the GdaStatement objects created while parsing (one object
per SQL statement). Empty statements (composed of spaces only) do not appear in the resulting object.
sql
is parsed and GdaStatement objects are created as long as no error is found in sql
. If an error is found
at some point, then the parsing stops and remain
may contain a non NULL
pointer, error
may be set, and NULL
is returned.
if sql
is NULL
, then the returned GdaBatch object will contain no statement.
To include variables in the sql
string, see the
GdaSqlParser's object description.
|
a GdaSqlParser object |
|
the SQL string to parse |
|
location to store a pointer to remaining part of sql in case an error occurred while parsing sql , or NULL . [out][allow-none]
|
|
location to store error, or NULL
|
Returns : |
a new GdaBatch object, or NULL if an error occurred. [transfer full][allow-none]
|
GdaBatch * gda_sql_parser_parse_file_as_batch (GdaSqlParser *parser
,const gchar *filename
,GError **error
);
Parse filename
's contents and creates a GdaBatch object which contains all the
GdaStatement objects created while parsing (one object per SQL statement).
filename
's contents are parsed and GdaStatement objects are created as long as no error is found. If an error is found
at some point, then the parsing stops, error
may be set and NULL
is returned
if sql
is NULL
, then the returned GdaBatch object will contain no statement.
|
a GdaSqlParser object |
|
name of the file to parse |
|
location to store error, or NULL
|
Returns : |
a new GdaBatch object, or NULL if an error occurred. [transfer full][allow-none]
|
gchar * gda_sql_identifier_quote (const gchar *id
,GdaConnection *cnc
,GdaServerProvider *prov
,gboolean meta_store_convention
,gboolean force_quotes
);
Use this function for any SQL identifier to make sure that:
it is correctly formatted
to be used with cnc
(if cnc
is NULL
, then some default SQL quoting rules will be applied,
similar to PostgreSQL's way) if for_meta_store
is FALSE
;
it is correctly formatted to be used with the GdaMetaStore's object associated to cnc
is for_meta_store
is TRUE
.
The force_quotes
allow some control of how to interpret id
: if FALSE
, then id
will be left
unchanged most of the time (except for example if it's a reserved keyword), otherwise
if force_quotes
is TRUE
, then the returned string will most probably have quotes around it
to request that the database keep the case sensitiveness (but again, this may vary depending
on the database being accessed through cnc
).
For example, the following table gives the result of this function depending on the arguments
when cnc
is NULL
(and prov
is also NULL
):
Table 3.
id | for_meta_store=FALSE , force_quotes=FALSE
|
for_meta_store=TRUE , force_quotes=FALSE
|
for_meta_store=FALSE , force_quotes=TRUE
|
for_meta_store=TRUE , force_quotes=TRUE
|
remark |
---|---|---|---|---|---|
"double word" | "double word" | "double word" | "double word" | "double word" | non allowed character in SQL identifier |
"CapitalTest" | "CapitalTest" | "CapitalTest" | "CapitalTest" | "CapitalTest" | Mixed case SQL identifier, already quoted |
CapitalTest | CapitalTest | capitaltest | "CapitalTest" | "CapitalTest" | Mixed case SQL identifier, non quoted |
"mytable" | "mytable" | mytable | "mytable" | mytable | All lowser case, quoted |
mytable | mytable | mytable | "mytable" | mytable | All lowser case |
MYTABLE | MYTABLE | mytable | "MYTABLE" | "MYTABLE" | All upper case |
"MYTABLE" | "MYTABLE" | "MYTABLE" | "MYTABLE" | "MYTABLE" | All upper case, quoted |
desc | "desc" | "desc" | "desc" | "desc" | SQL reserved keyword |
5ive | "5ive" | "5ive" | "5ive" | "5ive" | SQL identifier starting with a digit |
Here are a few examples of when and how to use this function:
When creating a table, the user has entered the table name, this function can be used to create a valid SQL identifier from the user provided table name:
gchar *user_sqlid=... gchar *valid_sqlid = gda_sql_identifier_quote (user_sqlid, cnc, NULL, FALSE, FALSE); gchar *sql = g_strdup_printf ("CREATE TABLE %s ...", valid_sqlid); g_free (valid_sqlid);
Note that this is an illustration and creating a table should be sone using a GdaServerOperation object.
When updating the meta data associated to a table which has been created with the code above:
GValue table_name_value = { 0 }; gchar* column_names[] = { (gchar*)"table_name" }; GValue* column_values[] = { &table_name_value }; GdaMetaContext mcontext = { (gchar*)"_tables", 1, column_names, column_values }; g_value_init (&table_name_value, G_TYPE_STRING); g_value_take_string (&table_name_value, gda_sql_identifier_quote (user_sqlid, cnc, NULL, TRUE, FALSE); gda_connection_update_meta_store (cnc, &mcontext, NULL); g_value_reset (&table_name_value);
When using a GdaMetaStruct object to fetch information about a table (which has been created with the code above):
GValue table_name_value = { 0 }; g_value_init (&table_name_value, G_TYPE_STRING); g_value_take_string (&table_name_value, gda_sql_identifier_quote (user_sqlid, cnc, NULL, TRUE, FALSE); GdaMetaDbObject *dbo; dbo = gda_meta_struct_complement (mstruct, GDA_META_DB_TABLE, NULL, NULL, &table_name_value, NULL); g_value_reset (&table_name_value);
Note that id
must not be a composed SQL identifier (such as "mytable.mycolumn" which should be
treated as the "mytable" and "mycolumn" SQL identifiers). If unsure, use gda_sql_identifier_split()
.
Also note that if cnc
is NULL
, then it's possible to pass an non NULL
prov
to have a result specific
to prov
.
For more information, see the SQL identifiers and abstraction and SQL identifiers in meta data sections.
|
an SQL identifier |
|
a GdaConnection object, or NULL
|
|
a GdaServerProvider object, or NULL
for_meta_store set to TRUE if the returned string will be used in a GdaMetaStore
|
|
set to TRUE to force the returned string to be quoted |
Returns : |
the representation of id ready to be used in SQL statement, as a new string,
or NULL if id is in a wrong format |
Since 4.0.3
gboolean gda_sql_identifier_needs_quotes (const gchar *str
);
gda_sql_identifier_needs_quotes
has been deprecated since version 4.0.3 and should not be used in newly-written code. Not needed anymore because of the gda_sql_identifier_quote()
function.
Tells if str
needs to be quoted before using it in an SQL statement. To actually add quotes,
use gda_sql_identifier_add_quotes()
.
To determine if quotes are needed: the following rules are applied:
|
an SQL identifier |
Returns : |
TRUE if str needs some quotes |
gchar * gda_sql_identifier_add_quotes (const gchar *str
);
gda_sql_identifier_add_quotes
has been deprecated since version 4.0.3 and should not be used in newly-written code. Use gda_sql_identifier_quote()
instead.
Add double quotes around the str
identifier. Use the gda_sql_identifier_needs_quotes()
function to tell if an identifier needs to be quoted.
|
an SQL identifier |
Returns : |
a new string |
gchar * gda_sql_identifier_remove_quotes (gchar *str
);
gda_sql_identifier_remove_quotes
has been deprecated since version 4.0.3 and should not be used in newly-written code. Not needed anymore because of the gda_sql_identifier_quote()
function.
Prepares str
to be compared:
if surrounded by double quotes or single quotes, then just remove the quotes
otherwise convert to lower case
The quoted string:
- must start and finish with the same single or double quotes character
- can contain the delimiter character (the single or double quotes) in the string if every instance of it is preceeded with a backslash character or with the delimiter character itself
WARNING: str
must NOT be a composed identifier (<part1>."<part2>" for example)
|
a quoted string |
Returns : |
str |
gchar ** gda_sql_identifier_split (const gchar *id
);
Splits id
into an array of it sub parts. id
's format has to be "<part>[.<part>[...]]" where
each part is either a text surrounded by double quotes which can contain upper and lower cases or
an SQL identifier in lower case.
For example the "test.\"ATable\"" string will result in the array: {"test", "\"ATable\"", NULL}
|
an SQL identifier |
Returns : |
a new NULL -terminated array of strings, or NULL (use g_strfreev() to free the returned array). [transfer full][array zero-terminated=1][allow-none]
|
"tokenizer-flavour"
property"tokenizer-flavour" gint : Read / Write
Allowed values: [0,4]
Default value: 0