or null if id is in a wrong format
sqlIdentifierQuote
fn
string sqlIdentifierQuote(string id, gda.connection.Connection cnc, gda.server_provider.ServerProvider prov, bool metaStoreConvention, bool forceQuotes)Use this function for any SQL identifier to make sure that:
<itemizedlist> <listitem> <para>it is correctly formattedto 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;
</para> </listitem> <listitem> <para>it is correctly formatted to be used with the #GdaMetaStore's object associated to cncis for_meta_store is true.
</para> </listitem> </itemizedlist>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):
Here are a few examples of when and how to use this function:
<itemizedlist> <listitem> <para>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:
<programlisting>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.
</para> </listitem> <listitem> <para>When updating the meta data associated to a table which has been created with the code above:
<programlisting>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);
</programlisting> </para> </listitem> <listitem> <para>When using a #GdaMetaStruct object to fetch information about a table (which has been created with the code above):
<programlisting>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);
</programlisting> </para> </listitem> </itemizedlist>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.global.sqlIdentifierSplit].
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 <link linkend="gen:sql_identifiers">SQL identifiers and abstraction</link> and
<link linkend="information_schema:sql_identifiers">SQL identifiers in meta data</link> sections.Parameters
id | an SQL identifier |
cnc | a #GdaConnection object, or null |
prov | a #GdaServerProvider object, or null for_meta_store set to true if the returned string will be used in a #GdaMetaStore |
metaStoreConvention | |
forceQuotes | 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,