Namespace Gda

The returned pointer is %NULL if there is no default data handler available for the for_type data type

out_username and out_password may be set to %NULL depending on string's format.

This function is a wrapper around the g_type_from_name() function, but also recognizes some type synonyms such as: "int" for G_TYPE_INT "uint" for G_TYPE_UINT "int64" for G_TYPE_INT64 "uint64" for G_TYPE_UINT64 "char" for G_TYPE_CHAR "uchar" for G_TYPE_UCHAR "short" for GDA_TYPE_SHORT "ushort" for GDA_TYPE_USHORT "string" for G_TYPE_STRING "date" for G_TYPE_DATE "time" for GDA_TYPE_TIME "timestamp" for GDA_TYPE_TIMESTAMP "boolean" for G_TYPE_BOOLEAN "blob" for GDA_TYPE_BLOB "binary" for GDA_TYPE_BINARY "null" for GDA_TYPE_NULL

This function wraps g_type_name() but for common types it provides an easier to understand and remember name. For Example the G_TYPE_STRING is converted to "string" whereas g_type_name() converts it to "gchararray".

Please note that if you call setlocale() to modify the current locale, you should also call gda_locale_changed() before using Libgda again.

Failing to call this function after having changed the current locale may result in Libgda reverting to the previous set locale.

Accepted date format is "YYYY-MM-DD" (more or less than 4 digits for years and less than 2 digits for month and day are accepted). Years must be in the 1-65535 range, a limitation imposed by #GDate.

Accepted date format is "HH:MM:SS[.ms][TZ]" where TZ is +hour or -hour

Accepted date format is "YYYY-MM-DD HH:MM:SS[.ms][TZ]" where TZ is +hour or -hour

For example the following SELECT: SELECT * FROM data WHERE id = ##id::int::null AND name = ##name::string in case the "id" parameter is set to NULL, is converted to: SELECT * FROM data WHERE id IS NULL AND name = ##name::string

if out_stmt is not %NULL, then it will contain: the modified statement if some modifications were required and no error occured (the function returns %TRUE) %NULL if no modification to stmt were required and no erro occurred (the function returns %FALSE) %NULL if an error occured (the function returns %TRUE)

This function is used by provider's implementations to make sure one can use parameters with NULL values in statements without having to rewrite statements, as database usually don't consider that "xxx = NULL" is the same as "xxx IS NULL" when using parameters.

string should respect the RFC 1738 encoding. If this is not the case (for example if there is a "%2z" because 2z is not an hexadecimal value), then the part with the problem is not decoded, and the function returns FALSE.

string is decoded in place, no new string gets created.

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):

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.

For example the string will result in the array:

I str is %NULL, then an empty (i.e. where the data part is %NULL) #GdaBinary is created and returned.

Warning: this function uses a #GdaDataModelIter iterator, and if model does not offer a random access (check using gda_data_model_get_access_flags()), the iterator will be the same as normally used to access data in model previously to calling this method, and this iterator will be moved (point to another row).

The two values must be of the same type, with the exception that a value of any type can be compared to a GDA_TYPE_NULL value, specifically: if value1 and value2 are both GDA_TYPE_NULL values then the returned value is 0 if value1 is a GDA_TYPE_NULL value and value2 is of another type then the returned value is 1 if value1 is of another type and value2 is a GDA_TYPE_NULL value then the returned value is 1 in all other cases, value1 and value2 must be of the same type and their values are compared

Output is in the "C" locale for numbers, and dates are converted in a YYYY-MM-DD format.