/usr/share/gtk-doc/html/libgda-4.0/prov-metadata.html is in libgda-4.0-doc 4.2.8-2build1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Methods - metadata</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="index.html" title="GNOME Data Access 4 manual">
<link rel="up" href="libgda-provider-class.html" title="Virtual methods for providers">
<link rel="prev" href="ch41s08.html" title="Methods - data representation">
<link rel="next" href="ch41s10.html" title="Methods - misc.">
<meta name="generator" content="GTK-Doc V1.17 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
<td><a accesskey="p" href="ch41s08.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="libgda-provider-class.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">GNOME Data Access 4 manual</th>
<td><a accesskey="n" href="ch41s10.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="prov-metadata"></a>Methods - metadata</h2></div></div></div>
<p>
The <a class="link" href="GdaServerProvider.html#GdaServerProviderMeta" title="GdaServerProviderMeta">GdaServerProviderMeta</a> structure defines all the methods
which database providers must implement for the meta data extraction feature to work. Each method is
used internally by the <a class="link" href="GdaConnection.html" title="GdaConnection">GdaConnection</a> object when one calls the
<a class="link" href="GdaConnection.html#gda-connection-update-meta-store" title="gda_connection_update_meta_store ()">gda_connection_update_meta_store()</a> method (where the
connection object itself computes the list and order of methods to call).
Each method must update the contents of one table in the connection's associated metadata
(in its associated <a class="link" href="GdaMetaStore.html" title="GdaMetaStore">GdaMetaStore</a> object), each has the same
"base" arguments and some have extra arguments further specifying what needs to be updated.
</p>
<p>
For each table to update, there are two methods, which differ in their name only by the fact that one is starting
with an underscore '_'. The method starting with an underscore must update the whole contents of the meta data
table, and the other one must accept some more parameters to refine what gets updated. There are exception
to this rule (such as the
"tables_views()" method which must update both the <a class="link" href="information_schema.html#is:_tables" title="_tables table">"_tables"</a> and
<a class="link" href="information_schema.html#is:_views" title="_views table">"_views"</a> tables, or the for the
tables which have no foreign key (no dependency) to any other table).
</p>
<p>
Also, by convetion, the arguments can't be NULL unless the argument name has the "_n" suffix. For example
the signature of the "tables_views()" method has the following signature (as defined in the
<code class="filename">gda-server-provider.h</code> file)
</p>
<pre class="programlisting">
gboolean (*tables_views) (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
GdaMetaContext *, GError **,
const GValue *table_catalog, const GValue *table_schema,
const GValue *table_name_n);
</pre>
<p>
which means that the <em class="parameter"><code>table_catalog</code></em> and <em class="parameter"><code>table_schema</code></em>
arguments can't be NULL, whereas the <em class="parameter"><code>table_name</code></em> can be NULL (and in this case the
"tables_views()" method must update the <a class="link" href="information_schema.html#is:_tables" title="_tables table">"_tables"</a> and
<a class="link" href="information_schema.html#is:_views" title="_views table">"_views"</a> tables regarding all the tables which
are in the specified catalog and schema.
</p>
<p>
Make sure you read the information about the meta data's database structure in the
<a class="link" href="information_schema.html" title="Database structure">Database structure</a>, and specifically the
<a class="link" href="information_schema.html#information_schema:data_types" title="Data types">data types</a> section and the
<a class="link" href="information_schema.html#information_schema:sql_identifiers" title="SQL identifiers">SQL identifiers</a> section.
</p>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="id1011018"></a>Important note about SQL identifiers</h3></div></div></div>
<p>
As mentioned in the <a class="link" href="information_schema.html#information_schema:sql_identifiers" title="SQL identifiers">SQL identifiers</a> section,
any SQL identifier in the meta store is represented either:
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem"><p>between double quotes if the SQL identifier is case sensitive</p></li>
<li class="listitem"><p>all in lower case if the SQL identifier is not case sensitive</p></li>
</ul></div>
<p>
</p>
<p>
For database engines which internally store case insensitive SQL identifiers in lower case
(such as PostgreSQL),
the meta data reported by the database engine can be used almost AS IS, but for database
engines which internally store case insensitive SQL identifiers in upper case (such as Oracle),
the upper case needs to be converted to lower case. Also case sensitive SQL identifiers also need
to be double quoted.
</p>
<p>
To minimize the work required to implement a database provider, <span class="application">Libgda</span> allows the database
provider to specifiy how case insensitive SQL identifiers are represented using
<a class="link" href="libgda-4.0-Misc-API.html#gda-meta-store-set-identifiers-style" title="gda_meta_store_set_identifiers_style ()">gda_meta_store_set_identifiers_style()</a>
and the <a class="link" href="GdaMetaStore.html" title="GdaMetaStore">GdaMetaStore</a> object will perform the work itself (the
default being GDA_SQL_IDENTIFIERS_LOWER_CASE in <a class="link" href="libgda-4.0-Misc-API.html#GdaSqlIdentifierStyle" title="enum GdaSqlIdentifierStyle">GdaSqlIdentifierStyle</a>.
</p>
<p>
Also note that the extra arguments for each virtual method listed below, when they are present
and when they represent an SQL identifier, will be represented:
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem"><p>for case insensitive SQL identifiers: using all lower or all upper case (depending on the setting
set using <a class="link" href="libgda-4.0-Misc-API.html#gda-meta-store-set-identifiers-style" title="gda_meta_store_set_identifiers_style ()">gda_meta_store_set_identifiers_style()</a>
</p></li>
<li class="listitem"><p>for case sensitive SQL identifiers: without the double quotes, but possibily with
mixed or not lower and upper characters</p></li>
</ul></div>
<p>
</p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="id1011114"></a>Reserved SQL keywords</h3></div></div></div>
<p>
Every database engine reserves some keywords for its own usage or because they are part of the SQL
language. Reserved keywords can be used as SQL identifiers if they are put between double quotes.
</p>
<p>
As Each database engine has its own set of reserved keywords, the database provider has to tell the
<a class="link" href="GdaMetaStore.html" title="GdaMetaStore">GdaMetaStore</a> object what its keywords are, which is done using
<a class="link" href="libgda-4.0-Misc-API.html#gda-meta-store-set-reserved-keywords-func" title="gda_meta_store_set_reserved_keywords_func ()">gda_meta_store_set_reserved_keywords_func()</a>
and passing a function which determines if a specific string is a reserved keyword. The usage of
this function is similar to the usage of the
<a class="link" href="libgda-4.0-Misc-API.html#gda-meta-store-set-identifiers-style" title="gda_meta_store_set_identifiers_style ()">gda_meta_store_set_identifiers_style()</a>
mentioned above.
</p>
<p>
Writing a function which tests if a string is a reserved keyword is a non complicated but error
prone and not optimized, in the same way as writing a parser/lexer directly, so <span class="application">Libgda</span> has a tool
which generates a static hash table from a list of reserved keywords, which is in the
<code class="filename">keywords.list</code> (several keywords can appear on the same line, separated by spaces or commas
but the last line must remain empty).
</p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="id1011172"></a>_info()</h3></div></div></div>
<p>
</p>
<pre class="programlisting">
gboolean (*_info) (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
GdaMetaContext *, GError **);
</pre>
<p>
This method must update the contents of the
<a class="link" href="information_schema.html#is:_information_schema_catalog_name" title="_information_schema_catalog_name table">"_information_schema_catalog_name"</a>
table, which must contain exactly
one row describing the catalog name for the connection.
</p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="id1011197"></a>_btypes()</h3></div></div></div>
<p>
</p>
<pre class="programlisting">
gboolean (*_btypes) (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
GdaMetaContext *, GError **);
</pre>
<p>
This method must update the contents of the <a class="link" href="information_schema.html#is:_builtin_data_types" title="_builtin_data_types table">"_builtin_data_types"</a>
table which lists all the
database's built in data types. There is no specific parameter.
</p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="id1011221"></a>schemata() and _schemata()</h3></div></div></div>
<p>
</p>
<pre class="programlisting">
gboolean (*_schemata) (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
GdaMetaContext *, GError **);
gboolean (*schemata) (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
GdaMetaContext *, GError **,
const GValue *catalog_name, const GValue *schema_name_n);
</pre>
<p>
This method must update the contents of the <a class="link" href="information_schema.html#is:_schemata" title="_schemata table">"_schemata"</a> table,
which lists all the schemas (namespaces).
</p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="id1011248"></a>tables_views() and _tables_views()</h3></div></div></div>
<p>
</p>
<pre class="programlisting">
gboolean (*_tables_views) (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
GdaMetaContext *, GError **);
gboolean (*tables_views) (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
GdaMetaContext *, GError **,
const GValue *table_catalog, const GValue *table_schema,
const GValue *table_name_n);
</pre>
<p>
This method must update the contents of the <a class="link" href="information_schema.html#is:_tables" title="_tables table">"_tables"</a> and
<a class="link" href="information_schema.html#is:_views" title="_views table">"_views"</a> tables which list all the
tables and views.
</p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="id1011282"></a>columns() and _columns()</h3></div></div></div>
<p>
</p>
<pre class="programlisting">
gboolean (*_columns) (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
GdaMetaContext *, GError **);
gboolean (*columns) (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
GdaMetaContext *, GError **,
const GValue *table_catalog, const GValue *table_schema,
const GValue *table_name);
</pre>
<p>
This method must update the contents of the <a class="link" href="information_schema.html#is:_columns" title="_columns table">"_columns"</a> table which lists all the
columns of all the tables and views.
</p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="id1011308"></a>constraints_tab() and _constraints_tab()</h3></div></div></div>
<p>
</p>
<pre class="programlisting">
gboolean (*_constraints_tab) (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
GdaMetaContext *, GError **);
gboolean (*constraints_tab) (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
GdaMetaContext *, GError **,
const GValue *table_catalog, const GValue *table_schema,
const GValue *table_name, const GValue *constraint_name_n);
</pre>
<p>
This method must update the contents of the <a class="link" href="information_schema.html#is:_table_constraints" title="_table_constraints table">"_table_constraints"</a>
table which lists all the
constraints (primary key, foreign key, unique or check constraints) for each table.
</p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="id1011336"></a>constraints_ref() and _constraints_ref()</h3></div></div></div>
<p>
</p>
<pre class="programlisting">
gboolean (*_constraints_ref) (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
GdaMetaContext *, GError **);
gboolean (*constraints_ref) (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
GdaMetaContext *, GError **,
const GValue *table_catalog, const GValue *table_schema,
const GValue *table_name, const GValue *constraint_name);
</pre>
<p>
This method must update the contents of the
<a class="link" href="information_schema.html#is:_referential_constraints" title="_referential_constraints table">"_referential_constraints"</a> table which lists all the
referential constraints (which are also listed in the
<a class="link" href="information_schema.html#is:_table_constraints" title="_table_constraints table">"_table_constraints"</a> table).
</p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="id1011372"></a>key_columns() and _key_columns()</h3></div></div></div>
<p>
</p>
<pre class="programlisting">
gboolean (*_key_columns) (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
GdaMetaContext *, GError **);
gboolean (*key_columns) (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
GdaMetaContext *, GError **,
const GValue *table_catalog, const GValue *table_schema,
const GValue *table_name, const GValue *constraint_name);
</pre>
<p>
This method must update the contents of the <a class="link" href="information_schema.html#is:_key_column_usage" title="_key_column_usage table">"_key_column_usage"</a>
table which lists all the
columns involved in each table constraint (as listed in the
<a class="link" href="information_schema.html#is:_table_constraints" title="_table_constraints table">"_table_constraints"</a> table).
</p>
</div>
</div>
<div class="footer">
<hr>
Generated by GTK-Doc V1.17</div>
</body>
</html>
|