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

  <refnamediv>
    <refname>CALL</refname>
    <refpurpose>Execute a specified logic block.</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <arg choice='opt'><option>LET</option> <replaceable>ret_value</replaceable> <option>=</option> </arg>
      <command> CALL</command>
      <arg choice='plain'><replaceable>logic_name</replaceable></arg>
      <arg rep='repeat' choice='opt'><replaceable>logic_argument</replaceable></arg>
      <arg choice='opt'><option>RETURNING</option> <replaceable>ret_value</replaceable>
         <arg rep='repeat' choice='opt'><replaceable>ret_value</replaceable>
         </arg>
      </arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1 id="cmd_call_introduction">
    <title>Introduction</title>
    <para>
      The <link linkend="cmd_call">CALL</link> command executes a specified 
      logic block. Arguments can be passed and return values can be retrieved.
    </para>
  </refsect1>

  <refsect1 id="cmd_call_arguments">
    <title>Arguments</title>
    <variablelist>
      <varlistentry>
	<term><replaceable>ret_value</replaceable></term>
	<listitem>
	  <simpara>
            Value returned by the <link linkend="cmd_return">RETURN</link> 
            command of the called logic. If more than 1 value is returned, 
            the keyword RETURNING must be used to assign data references 
            to the returned values. When only 1 value is returned, the 
            keyword RETURNING is optional. The returned value can in that 
            situation also be retrieved as a resultant of the logic in 
            combination with the <link linkend="cmd_let">LET</link> command. 
            If no values are returned, the keyword RETURNING must be omitted.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><replaceable>logic_name</replaceable></term>
	<listitem>
	  <simpara>
            Contains the name of the logic block. This can either be a string 
            or a data reference.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><replaceable>logic_argument</replaceable></term>
	<listitem>
	  <simpara>
            Value which can be passed into a logic block. The command 
            <link linkend="cmd_parameter">PARAMETER</link> within that logic 
            block will assign the values to local variables.
	  </simpara>
	</listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1 id="cmd_call_example">
    <title>Example</title>
<programlisting>
. . .
. . .
CALL GetOrderCustomer L-CustomerNumber L-Date RETURNING L-Status L-Totals
. . .
. . .
LET L-Totals = CALL GetOrder L-OrderNumber
. . .
. . .
</programlisting>
  </refsect1>

  <refsect1 id="cmd_call_related">
    <title>Related Commands</title>
    <para>
      <link linkend="cmd_parameter">PARAMETER</link>
      <link linkend="cmd_return">RETURN</link>
    </para>
  </refsect1>

</refentry>

