<!--
* 
*
*  ProLinga-Data
*
*  Copyright (C) 2002-2008 Xobas Software.
*  All rights reserved.
*  
*  This file is part of ProLinga-Data.
*
*  ProLinga-Data is free software: you can redistribute it and/or modify
*  it under the terms of the GNU General Public License as published by
*  the Free Software Foundation, either version 3 of the License, or
*  (at your option) any later version.
*
*  ProLinga-Data is distributed in the hope that it will be useful,
*  but WITHOUT ANY WARRANTY; without even the implied warranty of
*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
*  GNU General Public License for more details.
*
*  You should have received a copy of the GNU General Public License
*  along with ProLinga-Data.  If not, see <http://www.gnu.org/licenses/>.
*
*  More information is available at the following addresses:
*
*  Website     : http://www.prolinga.org
*
*  Email       : prolinga-list@prolinga.org
*
*
-->

<refentry id="prolinga-data-data">
  <refmeta>
    <refentrytitle>Data</refentrytitle>
    <manvolnum>3</manvolnum>
  <refmiscinfo>ProLinga-Data Library</refmiscinfo>
</refmeta>

<refnamediv>
  <refname>Data</refname>
  <refpurpose>Class used to manage Data connections and process Data Commands.</refpurpose>
</refnamediv>

<refsynopsisdiv>
  <title>Synopsis</title>

  <synopsis>
#include &lt;prolinga/Data.hpp&gt;

class <anchor id="class_PlData"/>PlData
{
        public:
                <link linkend="PlData">PlData</link>();
                ~<link linkend="PlData">PlData</link>();
                <link linkend="void">void</link>         <link linkend="PlData__dataOpen">dataOpen</link>           (const <link linkend="char">char</link> *configFileName,
                                                 <link linkend="int">int</link> argc,
                                                 <link linkend="char">char **</link>argv);
                <link linkend="void">void</link>         <link linkend="PlData__dataClose">dataClose</link>          (<link linkend="void">void</link>);
                <link linkend="xmlDocPtr">xmlDocPtr</link>    <link linkend="PlData__executeCommand">executeCommand</link>     (const <link linkend="xmlDocPtr">xmlDocPtr</link> dataRequest);
                ...
};
typedef <link linkend="class_PlData">PlData</link> *PlDataPtr;

  </synopsis>
</refsynopsisdiv>

<refsect1>
  <title>Description</title>
    <para>
    This class is used to connect to a Data environment and executes a Data Command.
    </para>
</refsect1>

<refsect1>
  <title>Details</title>
    <refsect2>
      <title><anchor id="PlData__dataOpen"/>PlData::dataOpen ()</title>
        <indexterm>
          <primary>PlData::dataOpen</primary>
        </indexterm>
        <programlisting><link linkend="void">void</link>       PlData::dataOpen           (const <link linkend="char">char</link> *configFileName, 
                                       <link linkend="int">int</link> argc,
                                       <link linkend="char">char **</link>argv);
</programlisting>
        <para>
        This function is called to initialize a connection to the Data environment.
        </para>

        <para>Function <link linkend="PlData__dataClose">PlData::dataClose</link> 
        must be called when access to the Data is no longer needed in order to close all handles
        and to free memory.</para>
        <para>
        </para>
        <variablelist role="params">
          <varlistentry>
            <term><parameter>configFileName</parameter>&nbsp;:</term>
            <listitem>
              <simpara> the name or the Data configuration file. If the argument is set to
              NULL, the Data default configuration file (etc/prolingadatcfg.xml) will be used.</simpara>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><parameter>argc</parameter>&nbsp;:</term>
            <listitem>
              <simpara> argument passed on to libgda environment, usually argc from main().
              It is unclear from the libgda documentation where it is used for.</simpara>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><parameter>argv</parameter>&nbsp;:</term>
            <listitem>
              <simpara> argument passed on to libgda environment, usually argv from main().
              It is unclear from the libgda documentation where it is used for.</simpara>
            </listitem>
          </varlistentry>
        </variablelist>
    </refsect2>

    <refsect2>
      <para/>
      <title><anchor id="PlData__dataClose"/>PlData::dataClose ()</title>
        <indexterm>
          <primary>PlData::dataClose</primary>
        </indexterm>
        <programlisting><link linkend="void">void</link>       PlData::dataClose           (<link linkend="void">void</link>);
</programlisting>
        <para>
        This function is called to close a connection to the Data environment.
        All handles and allocated memory will be freed.</para>
        
        <para>
        </para>
        <variablelist role="params">
        </variablelist>
    </refsect2>

    <refsect2>
      <para/>
      <title><anchor id="PlData__executeCommand"/>PlData::executeCommand ()</title>
        <indexterm>
          <primary>PlData::executeCommand</primary>
        </indexterm>
        <programlisting><link linkend="xmlDocPtr">xmlDocPtr</link>       PlData::executeCommand      (const <link linkend="xmlDocPtr">xmlDocPtr</link> dataRequest);
</programlisting>
        <para>
        This function presents a Data Command to the Data processing engine. 
        The command gets processed and a result
        returned. The returned XML document needs to be freed manually when it
        is no longer needed.
        </para>

        <para>
        </para>
        <variablelist role="params">
          <varlistentry>
            <term><emphasis>Returns</emphasis>&nbsp;:</term>
            <listitem>
              <simpara> the Data Command response as a libxml2 XML document.</simpara>
            </listitem>
          </varlistentry>
        </variablelist>
    </refsect2>

  </refsect1>
</refentry>

