<!--
* 
*
*  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_xml">
  <refmeta>
    <refentrytitle>XML Command</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>XML</refname>
    <refpurpose>Process XML documents.</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>XML</command>
      <arg choice='plain'><option>ADD</option></arg>
      <arg choice='plain'><replaceable>xml_document_name</replaceable></arg>
      <arg choice='plain'><option>NODE</option></arg>
      <arg choice='plain'><replaceable>node_ref</replaceable></arg>
      <arg choice='opt'>
        <arg choice='plain'><option>VALUE</option></arg>
        <arg choice='plain'><replaceable>data_ref</replaceable></arg>
      </arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>XML</command>
      <arg choice='plain'><option>CDATA</option></arg>
      <arg choice='plain'><replaceable>xml_document_name</replaceable></arg>
      <arg choice='plain'><option>VALUE</option></arg>
      <arg choice='plain'><replaceable>cdata_ref</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>XML</command>
      <arg choice='plain'><option>COMMENT</option></arg>
      <arg choice='plain'><replaceable>xml_document_name</replaceable></arg>
      <arg choice='plain'><option>VALUE</option></arg>
      <arg choice='plain'><replaceable>comment_ref</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>XML</command>
      <arg choice='plain'><option>COUNT</option></arg>
      <arg choice='plain'><replaceable>xml_document_name</replaceable></arg>
      <arg choice='plain'><option>NODE</option></arg>
      <arg choice='plain'><replaceable>node_ref</replaceable></arg>
      <arg choice='plain'><option>RETURNING</option></arg>
      <arg choice='plain'><replaceable>ret_ref</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>XML</command>
      <arg choice='plain'><option>LOAD</option></arg>
      <arg choice='plain'><replaceable>xml_document_name</replaceable></arg>
      <arg choice='plain'><option>FROM</option></arg>
      <arg choice='plain'>
        <group choice='req'>
          <arg choice='plain'>
            <arg choice='plain'><option>FILE</option></arg>
            <arg choice='plain'><replaceable>ext_file_name</replaceable></arg>
          </arg>
          <arg choice='plain'>
            <arg choice='plain'><option>XML</option></arg>
            <arg choice='plain'><replaceable>xml_document_name</replaceable></arg>
          </arg>
        </group>
      </arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>XML</command>
      <arg choice='plain'><option>MERGE</option></arg>
      <arg choice='plain'><replaceable>xml_document_name</replaceable></arg>
      <arg choice='plain'><option>SOURCE</option></arg>
      <arg choice='plain'><replaceable>source_xml_document</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>XML</command>
      <arg choice='plain'><option>MODIFY</option></arg>
      <arg choice='plain'><replaceable>xml_document_name</replaceable></arg>
      <arg choice='plain'><option>NODE</option></arg>
      <arg choice='plain'><replaceable>node_ref</replaceable></arg>
      <arg choice='plain'><option>VALUE</option></arg>
      <arg choice='plain'><replaceable>data_ref</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>XML</command>
      <arg choice='plain'><option>NODEPTR</option></arg>
      <arg choice='plain'><replaceable>xml_document_name</replaceable></arg>
      <arg choice='plain'><option>NODE</option></arg>
      <arg choice='plain'>
        <group choice='req'>
          <arg choice='plain'><replaceable>node_ref</replaceable></arg>
          <arg choice='plain'><option>CHILD</option></arg>
          <arg choice='plain'><option>PARENT</option></arg>
        </group>
      </arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>XML</command>
      <arg choice='plain'><option>READ</option></arg>
      <arg choice='plain'><replaceable>xml_document_name</replaceable></arg>
      <arg choice='plain'><option>NODE</option></arg>
      <arg choice='plain'><replaceable>node_ref</replaceable></arg>
      <arg choice='plain'><option>RETURNING</option></arg>
      <arg choice='plain'><replaceable>ret_ref</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>XML</command>
      <arg choice='plain'><option>REMOVE</option></arg>
      <arg choice='plain'><replaceable>xml_document_name</replaceable></arg>
      <arg choice='plain'><option>NODE</option></arg>
      <arg choice='plain'><replaceable>node_ref</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>XML</command>
      <arg choice='plain'><option>SAVE</option></arg>
      <arg choice='plain'><replaceable>xml_document_name</replaceable></arg>
      <arg choice='plain'><option>TO</option></arg>
      <arg choice='plain'><option>FILE</option></arg>
      <arg choice='plain'><replaceable>ext_file_name</replaceable></arg>
      <arg choice='opt'>
        <arg choice='plain'><option>MODE</option></arg>
        <arg choice='plain'><option>FORMAT</option></arg>
      </arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>XML</command>
      <arg choice='plain'><option>TRANSFORM</option></arg>
      <arg choice='plain'><option>SOURCE</option></arg>
      <group choice='req'>
        <arg choice='plain'><option>FILE</option></arg>
        <arg choice='plain'><option>TEXT</option></arg>
        <arg choice='plain'><option>XML</option></arg>
      </group>
      <arg choice='plain'><replaceable>source_ref</replaceable></arg>
      <arg choice='plain'><option>XSL</option></arg>
      <group choice='req'>
        <arg choice='plain'><option>FILE</option></arg>
        <arg choice='plain'><option>TEXT</option></arg>
        <arg choice='plain'><option>XML</option></arg>
      </group>
      <arg choice='plain'><replaceable>xsl_ref</replaceable></arg>
      <arg choice='plain'><option>OUTPUT</option></arg>
      <group choice='req'>
        <arg choice='plain'><option>FILE</option></arg>
        <arg choice='plain'><option>TEXT</option></arg>
        <arg choice='plain'><option>XML</option></arg>
      </group>
      <arg choice='plain'><replaceable>dest_ref</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>XML</command>
      <arg choice='plain'><option>VALIDATE</option></arg>
      <arg choice='plain'><replaceable>xml_document_name</replaceable></arg>
      <group choice='req'>
        <arg choice='plain'><option>DTD</option></arg>
        <arg choice='plain'><option>XMLSCHEMA</option></arg>
      </group>
      <group choice='req'>
        <arg choice='plain'><option>FILE</option></arg>
        <arg choice='plain'><option>TEXT</option></arg>
        <arg choice='plain'><option>XML</option></arg>
      </group>
      <arg choice='plain'><replaceable>validate_ref</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1 id="cmd_xml_introduction">
    <title>Introduction</title>
    <para>
      The <link linkend="cmd_xml">XML</link> command processes XML documents. Status of the executed 
      command can be retrieved using built-in function XMLSTATUS().
    </para>
  </refsect1>
  <refsect1 id="cmd_xml_arguments">
    <title>Arguments</title>
    <variablelist>
      <varlistentry>
	<term><replaceable>xml_document_name</replaceable></term>
	<listitem>
	  <simpara>
            Name of a XML document in memory.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><replaceable>source_xml_document</replaceable></term>
	<listitem>
	  <simpara>
            An XML document.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><replaceable>node_ref</replaceable></term>
	<listitem>
	  <simpara>
            Any data reference as well as hard coded strings containing an 
            element name or attribute name.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><replaceable>nodepath_ref</replaceable></term>
	<listitem>
	  <simpara>
            Any data reference as well as hard coded string containing a path 
            and an element or attribute. If the path is omitted, then the path 
            will be the current path where the node pointer is pointing to.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><replaceable>cdata_ref</replaceable></term>
	<listitem>
	  <simpara>
            Any data reference as well as a hard coded string. This section 
            will be placed withing CDATA tags, so the contents does not have 
            to be valid XML.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><replaceable>comment_ref</replaceable></term>
	<listitem>
	  <simpara>
            Any data reference as well as a hard coded string. This section will 
            be placed withing comment tags.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><replaceable>data_ref</replaceable></term>
	<listitem>
	  <simpara>
            Any data reference as well as a hard coded string or numeric value.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><replaceable>ret_ref</replaceable></term>
	<listitem>
	  <simpara>
            Any data reference that can have a value assigned to it.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><replaceable>dest_ref</replaceable></term>
	<listitem>
	  <simpara>
            Any data reference which can hold text data.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><replaceable>ext_file_name</replaceable></term>
	<listitem>
	  <simpara>
            Path and name of an external file.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><replaceable>line_no</replaceable></term>
	<listitem>
	  <simpara>
            Line number in the buffer.
	  </simpara>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id="cmd_xml_example">
    <title>Example</title>
<programlisting>
. . .
. . .
XML LOAD x1 FROM FILE "/tmp/importdata.xml" 
. . .
. . .
</programlisting>
  </refsect1>

  <refsect1 id="cmd_xml_related">
    <title>Related Commands</title>
    <para>
      <link linkend="cmd_clear">CLEAR</link>
    </para>
  </refsect1>

</refentry>

