<!--
* 
*
*  ProLinga-Doc
*
*  Copyright (C) 2002-2008 Xobas Software.
*  All rights reserved.
*  
*  This file is part of ProLinga-Doc.
*
*  ProLinga-Doc 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-Doc 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-Doc.  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="cmd_sql">
  <refmeta>
    <refentrytitle>SQL Command</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>SQL</refname>
    <refpurpose>Execute an SQL query.</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>SQL</command>
      <arg choice='plain'><option>CONNECT</option></arg>
      <arg choice='plain'><replaceable>data_source_name</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>SQL</command>
      <arg choice='plain'><option>DISCONNECT</option></arg>
      <arg choice='plain'><replaceable>data_source_name</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>SQL</command>
      <arg choice='plain'><option>ACTION</option></arg>
      <arg choice='plain'><replaceable>data_source_name</replaceable></arg>
      <arg choice='plain'><option>COMMAND</option></arg>
      <arg choice='plain'><replaceable>command</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>SQL</command>
      <arg choice='plain'><option>ACTION</option></arg>
      <arg choice='plain'><replaceable>data_source_name</replaceable></arg>
      <arg choice='plain'><option>INSERT</option></arg>
      <arg choice='plain'><replaceable>table_name</replaceable></arg>
      <arg choice='plain'><option>RECORD</option></arg>
      <arg choice='plain'><replaceable>record_name</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>SQL</command>
      <arg choice='plain'><option>ACTION</option></arg>
      <arg choice='plain'><replaceable>data_source_name</replaceable></arg>
      <arg choice='plain'><option>UPDATE</option></arg>
      <arg choice='plain'><replaceable>table_name</replaceable></arg>
      <arg choice='plain'><option>RECORD</option></arg>
      <arg choice='plain'><replaceable>record_name</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>SQL</command>
      <arg choice='plain'><option>QUERY</option></arg>
      <arg choice='plain'><replaceable>data_source_name</replaceable></arg>
      <arg choice='plain'><option>COMMAND</option></arg>
      <arg choice='plain'><replaceable>command</replaceable></arg>
      <arg choice='plain'><option>DATAMODEL</option></arg>
      <arg choice='plain'><replaceable>data_model_name</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>SQL</command>
      <arg choice='plain'><option>QUERY</option></arg>
      <arg choice='plain'><replaceable>data_source_name</replaceable></arg>
      <arg choice='plain'><option>COMMAND</option></arg>
      <arg choice='plain'><replaceable>command</replaceable></arg>
      <arg choice='plain'><option>TO</option></arg>
      <arg choice='plain'><option>TEXT</option></arg>
      <arg choice='plain'><replaceable>text_name</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1 id="cmd_sql_introduction">
    <title>Introduction</title>
    <para>
      The <link linkend="cmd_sql">SQL</link> command executes an SQL query on 
      a relational database. There are three types of queries:
      <orderedlist>
        <listitem>
          <para>CONNECT/DISCONNECT: This SQL statements opens/closes the data 
          source to a data provider.</para>
        </listitem>
        <listitem>
          <para>ACTION: This is non-query type of SQL statement which typically 
          is an UPDATE or an INSERT command, whereby the database will be 
          modified and the returning value will be the number of rows affected. 
          The number of rows affected can be retrieved by calling the built-in 
          function SQLRETURN(). As a shortcut/typing saving measure for inserting 
          or updating a 
          complete record/row variation, subcommands INSERT and UPDATE are 
          available expanding record details.</para>
        </listitem>
        <listitem>
          <para>QUERY: This is typically a SELECT statement, whereby a data 
          model will be returned containing the selected values.</para>
        </listitem>
      </orderedlist>

      All SQL commands will return a status. As soon as something goes wrong 
      the status will have a value other than 0. The status can be retrieved 
      by calling 
      the built-in function SQLSTATUS().
    </para>
  </refsect1>
  <refsect1 id="cmd_sql_arguments">
    <title>Arguments</title>
    <variablelist>
      <varlistentry>
	<term><replaceable>data_source_name</replaceable></term>
	<listitem>
	  <simpara>
            The name of the data source as defined in the development environment.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><replaceable>command</replaceable></term>
	<listitem>
	  <simpara>
            A valid SQL command. The external column names of the database can 
            be referenced directly, or the external column names, as linked to 
            the data dictionary, can be referenced using a reference prefix D-. 
            ie D-datadictionary_name. Likewise, external table names can be 
            referenced using a reference prefix T-.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><replaceable>data_model_name</replaceable></term>
	<listitem>
	  <simpara>
            The name of a valid and existing data model object.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><replaceable>text_name</replaceable></term>
	<listitem>
	  <simpara>
            The name of a valid and existing text object. All the returning rows 
            will be dumped at once to the text object, so it does not need a 
            FOREACH and data model to retrieve all data.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><replaceable>table_name</replaceable></term>
	<listitem>
	  <simpara>
            The name of a valid and existing table object. The external name
            of the table will be used in the data provider.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><replaceable>record_name</replaceable></term>
	<listitem>
	  <simpara>
            The name of a valid and existing record object. All data dictionaries
            in the record will be expanded to meet the requirements of a valid
            sql statement.
	  </simpara>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id="cmd_sql_example">
    <title>Example</title>
<programlisting>
. . .
. . .
SQL ACTION Order COMMAND "update Cust set Name = 'Johnson' where Cust_Id=" L-Cust_Id
. . .
SQL ACTION Order COMMAND "update Cust set " EXPANDUPDATE(Cust) " where Cust_Id=" L-Cust_Id
. . .
SQL ACTION Order COMMAND "insert into " T-Country " values ('61',Australia')"
. . .
SQL ACTION Order COMMAND "insert into " T-Country " values (" EXPANDINSERT(Country) ")"
. . .
SQL QUERY Order COMMAND "select * from Cust" DATAMODEL Cust
. . .
SQL QUERY Order COMMAND "select " D-Cust_Id  " from " T-Cust DATAMODEL Cust
. . . . . .
SQL QUERY Order COMMAND "select * from Cust" TO TEXT AllCust 
. . .
. . .
</programlisting>
  </refsect1>

  <refsect1 id="cmd_sql_related">
    <title>Related Commands</title>
    <para>
      <link linkend="cmd_datamodel">DATAMODEL</link>
      <link linkend="cmd_foreach">FOREACH</link>
      <link linkend="cmd_transaction">TRANSACTION</link>
    </para>
  </refsect1>

</refentry>

