Gentoo Attachment #29775 for bug #48611

View | Details | Raw Unified
Collapse All | Expand All

(-) libgda-1.0.3-orig/doc/C/libgda-docs.sgml (-77 / +79 lines)

Lines 2-8	Link Here

<!ENTITY LIBGDA          "<application>libgda</application>">

<!ENTITY LIBGDA          "<application>libgda</application>">

<!ENTITY GNOMEDB         "<application>GNOME-DB</application>">

<!ENTITY GNOMEDB         "<application>GNOME-DB</application>">

<!ENTITY igalia          '<ulink url="http://www.igalia.com">Igalia, S.L.</ulink>'>

<!ENTITY igalia          '<emphasis><ulink url="http://www.igalia.com">Igalia, S.L.</ulink></emphasis>'>

<!ENTITY API             "<acronym>API</acronym>">

<!ENTITY API             "<acronym>API</acronym>">

<!ENTITY DBMS            "<acronym>DBMS</acronym>">

<!ENTITY DBMS            "<acronym>DBMS</acronym>">

<!ENTITY DSN             "<acronym>DSN</acronym>">

<!ENTITY DSN             "<acronym>DSN</acronym>">

Lines 28-34	Link Here

<!ENTITY GDADATAMODELHASH "<xref linkend='libgda-GdaDataModelHash'>">

<!ENTITY GDADATAMODELHASH "<xref linkend='libgda-GdaDataModelHash'>">

<!ENTITY fullexample SYSTEM "examples/full_example.c" CDATA linespecific>

<!ENTITY fullexample SYSTEM "examples/full_example.c" CDATA linespecific>

<!ENTITY migration.sgml SYSTEM "migration.sgml">

<!ENTITY migration.sgml SYSTEM "migration.sgml">

<!ENTITY libgda-batch SYSTEM "sgml/gda-batch.sgml">

<!ENTITY libgda-blob SYSTEM "sgml/gda-blob.sgml">

<!ENTITY libgda-blob SYSTEM "sgml/gda-blob.sgml">

<!ENTITY libgda-client SYSTEM "sgml/gda-client.sgml">

<!ENTITY libgda-client SYSTEM "sgml/gda-client.sgml">

<!ENTITY libgda-command SYSTEM "sgml/gda-command.sgml">

<!ENTITY libgda-command SYSTEM "sgml/gda-command.sgml">

Lines 391-413	Link Here

	    will need to install a few packages in the following way:

	    will need to install a few packages in the following way:

	  </para>

	  </para>

          <PROGRAMLISTING>

          <PROGRAMLISTING>

            <SYSTEMITEM CLASS="prompt">$</SYSTEMITEM> <USERINPUT> apt-get install <EMPHASIS>package-names</EMPHASIS></USERINPUT>

            <SYSTEMITEM CLASS="prompt">$</SYSTEMITEM> <USERINPUT> apt-get install <REPLACEABLE>package-names</REPLACEABLE></USERINPUT>

          </PROGRAMLISTING>

          </PROGRAMLISTING>

          <para>

          <para>

            These are the packages you will need for this:

            These are the packages you will need for this:

          </para>

          </para>

          <ITEMIZEDLIST>

          <ITEMIZEDLIST>

            <LISTITEM>libgda2-1</LISTITEM>

          <LISTITEM><para>libgda2-1</para></LISTITEM>

            <LISTITEM>libgda2-common</LISTITEM>

            <LISTITEM><para>libgda2-common</para></LISTITEM>

            <LISTITEM>libgda2-dev</LISTITEM>

            <LISTITEM><para>libgda2-dev</para></LISTITEM>

            <LISTITEM>libgda2-doc</LISTITEM>

            <LISTITEM><para>libgda2-doc</para></LISTITEM>

            <LISTITEM>libgda2-dbg</LISTITEM>

            <LISTITEM><para>libgda2-dbg</para></LISTITEM>

          </ITEMIZEDLIST>

          </ITEMIZEDLIST>

          <para>

          <para>

            You can obtain information about any packages with:

            You can obtain information about any packages with:

          </para>

          </para>

          <PROGRAMLISTING>

          <PROGRAMLISTING>

            <SYSTEMITEM CLASS="prompt">$</SYSTEMITEM> <USERINPUT> apt-cache show <EMPHASIS>package-names</EMPHASIS></USERINPUT>

            <SYSTEMITEM CLASS="prompt">$</SYSTEMITEM> <USERINPUT> apt-cache show <replaceable>package-names</replaceable></USERINPUT>

          </PROGRAMLISTING>

          </PROGRAMLISTING>

          <para>

          <para>

            If you cannot find this packages, you must include in

            If you cannot find this packages, you must include in

Lines 637-644	Link Here

              <LINK LINKEND="installation-provider">providers specific information</LINK>.

              <LINK LINKEND="installation-provider">providers specific information</LINK>.

            </para>

            </para>

            <para>

            <para>

              There was a little bug<footnote>It can be fixed, but it

              There was a little bug<footnote><para>It can be fixed, but it

              is better not to run the risk of it.</footnote>, and it

              is better not to run the risk of it.</para></footnote>, and it

	      is that <LINK

	      is that <LINK

	      LINKEND="gda-config-save-data-source">gda_config_save_data_source()</LINK>

	      LINKEND="gda-config-save-data-source">gda_config_save_data_source()</LINK>

              does not create the configuration directory <filename

              does not create the configuration directory <filename

Lines 1141-1147	Link Here

        <para>

        <para>

          The command type we most commonly use is <LINK

          The command type we most commonly use is <LINK

          LINKEND="GdaCommandType">GDA_COMMAND_TYPE_SQL</LINK> because we will only

          LINKEND="GdaCommandType">GDA_COMMAND_TYPE_SQL</LINK> because we will only

          focus on &SQL; queries<footnote>There are other command types, as &XML; and so on.

          focus on &SQL; queries<footnote><para>There are other command types, as &XML; and so on.</para>

          </footnote>

          </footnote>

        </para>

        </para>

        <PROGRAMLISTINGCO>

        <PROGRAMLISTINGCO>

Lines 1244-1256	Link Here

          LINKEND="data-model">data models</LINK>). You have two ways to do this:

          LINKEND="data-model">data models</LINK>). You have two ways to do this:

        </para>

        </para>

        <ITEMIZEDLIST>

        <ITEMIZEDLIST>

          <LISTITEM>

          <LISTITEM><para>

            <LINK LINKEND="gda-connection-execute-single-command">

            <LINK LINKEND="gda-connection-execute-single-command">

              gda_data_model_execute_single_command()</LINK>

              gda_data_model_execute_single_command()</LINK></para>

          </LISTITEM>

          </LISTITEM>

          <LISTITEM>

          <LISTITEM><para>

            <LINK LINKEND="gda-connection-execute-command">

            <LINK LINKEND="gda-connection-execute-command">

              gda_data_model_execute_command()</LINK>

              gda_data_model_execute_command()</LINK></para>

          </LISTITEM>

          </LISTITEM>

        </ITEMIZEDLIST>

        </ITEMIZEDLIST>

        <para>

        <para>

Lines 1340-1368	Link Here

        Let's see the functions we need:

        Let's see the functions we need:

      </para>

      </para>

      <ITEMIZEDLIST>

      <ITEMIZEDLIST>

        <LISTITEM>

        <LISTITEM><para>

          <LINK LINKEND="gda-data-model-get-n-rows">gda_data_model_get_n_rows()</LINK>

          <LINK LINKEND="gda-data-model-get-n-rows">gda_data_model_get_n_rows()</LINK></para>

        </LISTITEM>

        </LISTITEM>

        <LISTITEM>

        <LISTITEM><para>

          <LINK LINKEND="gda-data-model-get-n-columns">gda_data_model_get_n_columns()</LINK>

          <LINK LINKEND="gda-data-model-get-n-columns">gda_data_model_get_n_columns()</LINK></para>

        </LISTITEM>

        </LISTITEM>

        <LISTITEM>

        <LISTITEM><para>

          <LINK LINKEND="gda-data-model-describe-column">gda_data_model_describe_column()</LINK>

          <LINK LINKEND="gda-data-model-describe-column">gda_data_model_describe_column()</LINK></para>

        </LISTITEM>

        </LISTITEM>

        <LISTITEM>

        <LISTITEM><para>

          <LINK LINKEND="gda-data-model-get-column-title">gda_data_model_get_column_title()</LINK>

          <LINK LINKEND="gda-data-model-get-column-title">gda_data_model_get_column_title()</LINK></para>

        </LISTITEM>

        </LISTITEM>

        <LISTITEM>

        <LISTITEM><para>

          <LINK LINKEND="gda-data-model-get-column-position">gda_data_model_get_column_position()</LINK>

          <LINK LINKEND="gda-data-model-get-column-position">gda_data_model_get_column_position()</LINK></para>

        </LISTITEM>

        </LISTITEM>

        <LISTITEM>

        <LISTITEM><para>

          <LINK LINKEND="gda-data-model-get-row">gda_data_model_get_row()</LINK>

          <LINK LINKEND="gda-data-model-get-row">gda_data_model_get_row()</LINK></para>

        </LISTITEM>

        </LISTITEM>

        <LISTITEM>

        <LISTITEM><para>

          <LINK LINKEND="gda-data-model-get-value-at">gda_data_model_get_value_at()</LINK>

          <LINK LINKEND="gda-data-model-get-value-at">gda_data_model_get_value_at()</LINK></para>

        </LISTITEM>

        </LISTITEM>

        <LISTITEM>

        <LISTITEM><para>

          <LINK LINKEND="gda-row-get-value">gda_row_get_value()</LINK>

          <LINK LINKEND="gda-row-get-value">gda_row_get_value()</LINK></para>

        </LISTITEM>

        </LISTITEM>

      </ITEMIZEDLIST>

      </ITEMIZEDLIST>

      <para>

      <para>

Lines 1514-1520	Link Here

        </para>

        </para>

      </sect2>

      </sect2>

    </sect1>

    </sect1>

    <sect1 ID="gdavalue">

    <sect1 ID="manage-gdavalue">

      <title>Managing values</title>

      <title>Managing values</title>

      <para>

      <para>

        Values returned by functions of managing data are <LINK

        Values returned by functions of managing data are <LINK

Lines 1524-1543	Link Here

        of them:

        of them:

      </para>

      </para>

      <ITEMIZEDLIST>

      <ITEMIZEDLIST>

        <LISTITEM>

        <LISTITEM><para>

          <LINK LINKEND="gda-value-free">gda_value_free()</LINK>

          <LINK LINKEND="gda-value-free">gda_value_free()</LINK></para>

        </LISTITEM>

        </LISTITEM>

        <LISTITEM>

        <LISTITEM><para>

          <LINK LINKEND="gda-value-is-null">gda_value_is_null()</LINK>

          <LINK LINKEND="gda-value-is-null">gda_value_is_null()</LINK></para>

        </LISTITEM>

        </LISTITEM>

        <LISTITEM>

        <LISTITEM><para>

          <LINK LINKEND="gda-value-copy">gda_value_copy()</LINK>

          <LINK LINKEND="gda-value-copy">gda_value_copy()</LINK></para>

        </LISTITEM>

        </LISTITEM>

        <LISTITEM>

        <LISTITEM><para>

          <LINK LINKEND="gda-value-compare">gda_value_compare()</LINK>

          <LINK LINKEND="gda-value-compare">gda_value_compare()</LINK></para>

        </LISTITEM>

        </LISTITEM>

        <LISTITEM>

        <LISTITEM><para>

          <LINK LINKEND="gda-value-stringify">gda_value_stringify()</LINK>

          <LINK LINKEND="gda-value-stringify">gda_value_stringify()</LINK></para>

        </LISTITEM>

        </LISTITEM>

      </ITEMIZEDLIST>

      </ITEMIZEDLIST>

      <para>

      <para>

Lines 1637-1656	Link Here

        classes, and they are:

        classes, and they are:

      </para>

      </para>

      <ITEMIZEDLIST>

      <ITEMIZEDLIST>

        <LISTITEM>

        <LISTITEM><para>

          <LINK LINKEND="gda-transaction-new">gda_transaction_new ()</LINK>

          <LINK LINKEND="gda-transaction-new">gda_transaction_new ()</LINK></para>

        </LISTITEM>

        </LISTITEM>

        <LISTITEM>

        <LISTITEM><para>

          <LINK LINKEND="gda-connection-begin-transaction">gda_connection_begin_transaction ()</LINK>

          <LINK LINKEND="gda-connection-begin-transaction">gda_connection_begin_transaction ()</LINK></para>

        </LISTITEM>

        </LISTITEM>

        <LISTITEM>

        <LISTITEM><para>

          <LINK LINKEND="gda-connection-commit-transaction">gda_connection_commit_transaction ()</LINK>

          <LINK LINKEND="gda-connection-commit-transaction">gda_connection_commit_transaction ()</LINK></para>

        </LISTITEM>

        </LISTITEM>

        <LISTITEM>

        <LISTITEM><para>

          <LINK LINKEND="gda-connection-rollback-transaction">gda_connection_rollback_transaction ()</LINK>

          <LINK LINKEND="gda-connection-rollback-transaction">gda_connection_rollback_transaction ()</LINK></para>

        </LISTITEM>

        </LISTITEM>

        <LISTITEM>

        <LISTITEM><para>

          <LINK LINKEND="gda-command-set-transaction">gda_command_set_transaction ()</LINK>

          <LINK LINKEND="gda-command-set-transaction">gda_command_set_transaction ()</LINK></para>

        </LISTITEM>

        </LISTITEM>

      </ITEMIZEDLIST>

      </ITEMIZEDLIST>

      <para>

      <para>

Lines 1809-1825	Link Here

      Here you see the functions to manage errors:

      Here you see the functions to manage errors:

    </para>

    </para>

    <ITEMIZEDLIST>

    <ITEMIZEDLIST>

      <LISTITEM>

      <LISTITEM><para>

        <LINK LINKEND="gda-error-get-description">gda_error_get_description()</LINK>

        <LINK LINKEND="gda-error-get-description">gda_error_get_description()</LINK></para>

      </LISTITEM>

      </LISTITEM>

      <LISTITEM>

      <LISTITEM><para>

        <LINK LINKEND="gda-error-get-number">gda_error_get_number()</LINK>

        <LINK LINKEND="gda-error-get-number">gda_error_get_number()</LINK></para>

      </LISTITEM>

      </LISTITEM>

      <LISTITEM>

      <LISTITEM><para>

        <LINK LINKEND="gda-error-get-source">gda_error_get_source()</LINK>

        <LINK LINKEND="gda-error-get-source">gda_error_get_source()</LINK></para>

      </LISTITEM>

      </LISTITEM>

      <LISTITEM>

      <LISTITEM><para>

        <LINK LINKEND="gda-error-get-sqlstate">gda_error_get_sqlstate()</LINK>

        <LINK LINKEND="gda-error-get-sqlstate">gda_error_get_sqlstate()</LINK></para>

      </LISTITEM>

      </LISTITEM>

    </ITEMIZEDLIST>

    </ITEMIZEDLIST>

    <para>

    <para>

Lines 1920-1928	Link Here

        <para>

        <para>

          There is no problem about calling several times to this

          There is no problem about calling several times to this

          function because if you save an existing data source, it

          function because if you save an existing data source, it

          is replaced, so it could be advisable<footnote>But you must think

          is replaced, so it could be advisable<footnote><para>But you must think

          of security if you distribute the source code because people would see

          of security if you distribute the source code because people would see

          the passwords of your databases.</footnote> to save the data source

          the passwords of your databases.</para></footnote> to save the data source

          each time you want to create the connection.

          each time you want to create the connection.

        </para>

        </para>

      </sect2>

      </sect2>

Lines 1971-1979	Link Here

          A normal query is a query that return data. This is made as a

          A normal query is a query that return data. This is made as a

          <LINK LINKEND="libgda-GdaDataModel">data model</LINK>, analogous

          <LINK LINKEND="libgda-GdaDataModel">data model</LINK>, analogous

          to <EMPHASIS>GdaRecordset</EMPHASIS> in the old

          to <EMPHASIS>GdaRecordset</EMPHASIS> in the old

          version<footnote>Now you have a <LINK

          version<footnote><para>Now you have a <LINK

          LINKEND="libgda-provider-recordset">GdaRecordset</LINK> class,

          LINKEND="libgda-provider-recordset">GdaRecordset</LINK> class,

          but it is not recommended.</footnote>.

          but it is not recommended.</para></footnote>.

        </para>

        </para>

        <para>

        <para>

          As you can see in the following example, the function we use to

          As you can see in the following example, the function we use to

Lines 1987-1997	Link Here

        </para>

        </para>

        <para>

        <para>

          As in the case of <LINK

          As in the case of <LINK

          INKEND="gda-connection-execute-non-query">non queries</LINK>, you

          LINKEND="gda-connection-execute-non-query">non queries</LINK>, you

          must not use several semicolon-separated sentences, because you

          must not use several semicolon-separated sentences, because you

          have a special function to do this<footnote><LINK

          have a special function to do this<footnote><para><LINK

          LINKEND="gda-connection-execute-command">gda_connection_execute_command

          LINKEND="gda-connection-execute-command">gda_connection_execute_command

          ()</LINK></footnote>, but it is not recommended.

          ()</LINK></para></footnote>, but it is not recommended.

        </para>

        </para>

      </sect2>

      </sect2>

    </sect1>

    </sect1>

Lines 2037-2042	Link Here

          changes using &SQL;, so we consider data models not to be

          changes using &SQL;, so we consider data models not to be

          modifiable.

          modifiable.

        </para>

        </para>

      </sect2>

      <sect2>

      <sect2>

        <title>Accessing directly to columns</title>

        <title>Accessing directly to columns</title>

        <para>

        <para>

Lines 2080-2086	Link Here

      The following sections describe the API available for &GDA; applications.

      The following sections describe the API available for &GDA; applications.

    </para>

    </para>

    &libgda-init;

    &libgda-init;

    &libgda-batch;

    &libgda-blob;

    &libgda-blob;

    &libgda-client;

    &libgda-client;

    &libgda-command;

    &libgda-command;

Lines 2268-2274	Link Here

		<entry>Tables</entry>

		<entry>Tables</entry>

		<entry><parameter>GDA_CONNECTION_SCHEMA_TABLES</parameter></entry>

		<entry><parameter>GDA_CONNECTION_SCHEMA_TABLES</parameter></entry>

		<entry>"name" (name of table, optional)</entry>

		<entry>"name" (name of table, optional)</entry>

		<entry>name, owner, comments, SQL definition

		<entry>name, owner, comments, SQL definition</entry>

	      </row>

	      </row>

	      <row>

	      <row>

		<entry>Tables' parents</entry>

		<entry>Tables' parents</entry>

Lines 2355-2361	Link Here

	  <para>describe_column</para>

	  <para>describe_column</para>

	  <para>

	  <para>

	    Returns information about a given column, in the form of

	    Returns information about a given column, in the form of

	    a <xref linkend="GdaFieldAttributes">GdaFieldAttributes</xref>.

	    a <link linkend="GdaFieldAttributes">GdaFieldAttributes</link>.

	  </para>

	  </para>

	</listitem>

	</listitem>

	<listitem>

	<listitem>

Lines 2363-2372	Link Here

	  <para>

	  <para>

	    Retrieves a row from the data model. This function is very important

	    Retrieves a row from the data model. This function is very important

	    for the implementation of editable data models. What this function

	    for the implementation of editable data models. What this function

	    returns is a <xref linkend"GdaRow">GdaRow</xref>, which providers

	    returns is a <link linkend="GdaRow">GdaRow</link>, which providers

	    should uniquely identify (via <xref linkend="gda-row-set-id">gda_row_set_id</xref>).

	    should uniquely identify (via <link linkend="gda-row-set-id">gda_row_set_id</link>).

	    This is needed so that later on, client applications can use the same

	    This is needed so that later on, client applications can use the same

	    <xref linkend="GdaRow">GdaRow</xref> returned by this method in

	    <link linkend="GdaRow">GdaRow</link> returned by this method in

	    the <function>update_row</function> and <function>remove_row</function>

	    the <function>update_row</function> and <function>remove_row</function>

	    methods.

	    methods.

	  </para>

	  </para>

Lines 2387-2395	Link Here

	  </para>

	  </para>

	  <para>

	  <para>

	    Before a data model can be edited, client applications must call the

	    Before a data model can be edited, client applications must call the

	    <xref linkend="gda-data-model-begin-edit">gda_data_model_begin_edit</xref>

	    <link linkend="gda-data-model-begin-edit">gda_data_model_begin_edit</link>

	    function, which emits the "begin_edit" signal on the

	    function, which emits the "begin_edit" signal on the

	    <xref linkend="GdaDataModel">GdaDataModel</xref> class. So, providers

	    <link linkend="GdaDataModel">GdaDataModel</link> class. So, providers

	    should connect to this signal to be informed when the data model

	    should connect to this signal to be informed when the data model

	    starts being editing. In the callback connected to that signal,

	    starts being editing. In the callback connected to that signal,

	    it should start a transaction, for instance.

	    it should start a transaction, for instance.

Lines 2430-2436	Link Here

	</listitem>

	</listitem>

      </itemizedlist>

      </itemizedlist>

    </sect1>

    </sect1>

    &libgda-server-provider;

    <sect1 id="libgda-server-provider-details">

      <title>Details</title>

      &libgda-server-provider;

    </sect1>

  </chapter>

  </chapter>

  <chapter id="libgda-xql">

  <chapter id="libgda-xql">

Attachment #29775: libgda-1.0.4 gtk_doc patch for bug #48611