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

  <refnamediv>
    <refname>THREAD</refname>
    <refpurpose>Start or stop 4GL logic in a thread.</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>THREAD</command>
      <arg choice='plain'><option>START</option></arg>
      <arg choice='plain'><replaceable>thread_name</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>THREAD</command>
      <arg choice='plain'><option>STOP</option></arg>
      <arg choice='plain'><replaceable>thread_name</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1 id="cmd_thread_introduction">
    <title>Introduction</title>
    <para>
      The <link linkend="cmd_thread">THREAD</link> command is used to either
      execute logic into a new thread or stop a running thread. ProLinga-4GL
      is an event driven environment. All responses to events should be quick.
      For processes that require a long(er) time to execute, they can be
      started in a separate thread. Similar like a background process, however
      the logic executed in a thread can contact the main foreground thread
      to update screen widgets for instance.
    </para>

    <para>
      At this stage threads can not be nested (yet).
    </para>

  </refsect1>
  <refsect1 id="cmd_thread_arguments">
    <title>Arguments</title>
    <variablelist>
      <varlistentry>
	<term><replaceable>thread_name</replaceable></term>
	<listitem>
	  <simpara>
            Any data reference as well as hard coded string holding the name 
            of a thread.
	  </simpara>
	</listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1 id="cmd_thread_example">
    <title>Example</title>
<programlisting><![CDATA[
. . .
. . .
COMMENT *** Start a thread from the main thread (foreground)
THREAD START printOrders
IF THREADSTATUS <> 0
	ERROR "Order print batch could not be started." SEVERITY Error
ENDIF
. . .
. . .
THREAD STOP printOrders
IF THREADSTATUS <> 0
	ERROR "Order print batch could not be stopped or has already finished." SEVERITY Error
ENDIF
. . .
. . .
]]></programlisting>

    <para>Logic executed in a thread can check with the built-in function THREADEXIT()
    if a THREAD STOP command has been issued.</para>

<programlisting><![CDATA[
. . .
. . .
FOREVER
	IF THREADEXIT() = TRUE() THEN BREAK
	COMMENT *** Process logic in thread
	. . .
	. . .
ENDFOR
. . .
. . .

]]></programlisting>
  </refsect1>

  <refsect1 id="cmd_thread_related">
    <title>Related Commands</title>
    <para>
      None.
    </para>
  </refsect1>

</refentry>

