<!--
* 
*
*  ProLinga-Run
*
*  Copyright (C) 2002-2008 Xobas Software.
*  All rights reserved.
*  
*  This file is part of ProLinga-Run.
*
*  ProLinga-Run 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-Run 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-Run.  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-run-run">
  <refmeta>
    <refentrytitle>Run</refentrytitle>
    <manvolnum>3</manvolnum>
  <refmiscinfo>ProLinga-Run Library</refmiscinfo>
</refmeta>

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

<refsynopsisdiv>
  <title>Synopsis</title>

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

class <anchor id="class_PlRun"/>PlRun
{
        public:
                <link linkend="PlRun">PlRun</link>();
                ~<link linkend="PlRun">PlRun</link>();
                <link linkend="void">void</link>         <link linkend="PlRun__runOpen">runOpen</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="PlRun__runClose">runClose</link>          (<link linkend="void">void</link>);
                <link linkend="xmlDocPtr">xmlDocPtr</link>    <link linkend="PlRun__executeCommand">executeCommand</link>    (const <link linkend="xmlDocPtr">xmlDocPtr</link> runRequest);
                ...
};
typedef <link linkend="class_PlRun">PlRun</link> *PlRunPtr;

  </synopsis>
</refsynopsisdiv>

<refsect1>
  <title>Description</title>
    <para>
    This class is used to connect to a Run environment and to execute a Web Command.
    </para>
</refsect1>

<refsect1>
  <title>Details</title>
    <refsect2>
      <title><anchor id="PlRun__runOpen"/>PlRun::runOpen ()</title>
        <indexterm>
          <primary>PlRun::runOpen</primary>
        </indexterm>
        <programlisting><link linkend="void">void</link>       PlRun::runOpen           (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 Run environment.
        </para>

        <para>Function <link linkend="PlRun__runClose">PlRun::runClose</link> 
        must be called when access to the Run environment 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 Run configuration file. If the argument is set to
              NULL, the Run default configuration file (etc/prolingaruncfg.xml) will be used.</simpara>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><parameter>argc</parameter>&nbsp;:</term>
            <listitem>
              <simpara> argument passed on to libglade environment, usually argc from main().
              It is unclear from the libglade documentation where it is used for.</simpara>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><parameter>argv</parameter>&nbsp;:</term>
            <listitem>
              <simpara> argument passed on to libglade environment, usually argv from main().
              It is unclear from the libglade documentation where it is used for.</simpara>
            </listitem>
          </varlistentry>
        </variablelist>
    </refsect2>

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

    <refsect2>
      <title><anchor id="PlRun__executeCommand"/>PlRun::executeCommand ()</title>
        <indexterm>
          <primary>PlRun::executeCommand</primary>
        </indexterm>
        <programlisting><link linkend="xmlDocPtr">xmlDocPtr</link>       PlRun::executeCommand      (const <link linkend="xmlDocPtr">xmlDocPtr</link> runRequest);
</programlisting>
        <para>
        This function presents a Web Command to the Run 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 Run Command response as a libxml2 XML document.</simpara>
            </listitem>
          </varlistentry>
        </variablelist>
    </refsect2>

  </refsect1>
</refentry>

