<doc>
  <legacy_id>1339</legacy_id>
  <name>local</name>
  <type>command</type>
  <syntax>
    <example>local <i>variablesList</i></example>
  </syntax>
  <library></library>
  <objects>
  </objects>
  <synonyms>
  </synonyms>
  <classification>
  </classification>
  <references>
    <command tag="constant">constant Command</command>
    <command tag="delete variable">delete variable Command</command>
    <property tag="explicitVariables">explicitVariables Property</property>
    <command tag="global">global Command</command>
    <function tag="localNames">localNames Function</function>
    <function tag="variableNames">variableNames Function</function>
    <command tag="do">do Command</command>
    <property tag="preserveVariables">preserveVariables Property</property>
  </references>
  <history>
    <introduced version="1.0">Added.</introduced>
  </history>
  <platforms>
    <mac/>
    <windows/>
    <linux/>
    <ios/>
    <android/>
  </platforms>
  <classes>
    <desktop/>
    <server/>
    <web/>
    <mobile/>
  </classes>
  <security>
  </security>
  <summary><glossary tag="declare">Declares</glossary> one or more <glossary tag="local variable">local variables</glossary> and assigns initial <glossary tag="value">values</glossary> to them.</summary>
  <examples>
    <example>local currentStatus <i>-- creates one local variable</i></example>
    <example>local thisThing,thatThing,theOtherThing <i>-- creates three variables</i></example>
    <example>local A=1,B=2,C=3 <i>-- creates variables with initial values</i></example>
    <example>-- To make a numbered list of variables:</p><p>repeat with x=1 to 20</p><p>  do "local tVar_" &amp; x &amp; "; put empty into tVar_" &amp; x</p><p>end repeat</example>
  </examples>
  <description>
    <p>Use the <b>local</b> <glossary tag="command">command</glossary> to define a <glossary tag="local variable">local variable</glossary> for a <glossary tag="handler">handler</glossary>, or to define a <glossary tag="script local variable">script local variable</glossary> that is shared between all the <glossary tag="handler">handlers</glossary> in a <property tag="script">script</property>.</p><p/><p><b>Parameters:</b></p><p>The <i>variablesList</i> consists of one or more <i>name</i>=<i>value</i> pairs, separated by commas:</p><p>        * The <i>name</i> is any <keyword tag="string">string</keyword>.</p><p>        * The <i>value</i> is any <glossary tag="literal string">literal string</glossary>.</p><p>The <i>value</i> is optional; you can specify just the <glossary tag="variable">variable</glossary> name. In this case, the specified <glossary tag="local variable">local variables</glossary> contain empty when created.</p><p/><p><b>Comments:</b></p><p>The <b>local</b> <glossary tag="declare">declaration</glossary> is optional. You can use a <glossary tag="local variable">local variable</glossary> without <glossary tag="declare">declaring</glossary> it first in the <glossary tag="handler">handler</glossary>. In this case, the <glossary tag="local variable">local variable</glossary> can be used only within that <glossary tag="handler">handler</glossary>.</p><p/><p>The <b>local</b> <glossary tag="command">command</glossary> can appear anywhere in a <glossary tag="handler">handler</glossary>. However, <glossary tag="variable">variable</glossary> <glossary tag="declare">declarations</glossary> are usually placed at the beginning of a <glossary tag="handler">handler</glossary>. This makes them easier to find and as local variables are created at the point in the script where they are declared it will ensure the variable isn't used before the declaration.</p><p/><p>You can also use the <b>local</b> <glossary tag="command">command</glossary> to create a <glossary tag="script local variable">script local variable</glossary>. <glossary tag="script local variable">Script local variables</glossary> can be used by any <glossary tag="handler">handler</glossary> in that <property tag="script">script</property>, without needing to be <glossary tag="declare">declared</glossary> in the <glossary tag="handler">handler</glossary> itself, and their <glossary tag="value">values</glossary> are maintained from <glossary tag="handler">handler</glossary> to <glossary tag="handler">handler</glossary>. You create a <glossary tag="script local variable">script local variable</glossary> by using the <b>local</b> <glossary tag="command">command</glossary> in a <property tag="script">script</property>, outside any <glossary tag="handler">handlers</glossary> in the <property tag="script">script</property>. (The difference between a <glossary tag="script local variable">script local variable</glossary> and a <glossary tag="global">global variable</glossary> is that a <glossary tag="script local variable">script local variable</glossary> can only be used in the <glossary tag="handler">handlers</glossary> of one <property tag="script">script</property>, while a <glossary tag="global">global variable</glossary> can be used in any <glossary tag="handler">handler</glossary> or <property tag="script">script</property> with a <command tag="global">global</command> <glossary tag="declare">declaration</glossary> for that <glossary tag="variable">variable</glossary>.)</p><p/><p>The value of a local variable is retained only while the handler is running. When the handler exits, the value of the local variable is lost.</p><p/><p>The value of a script local variable is retained between handlers, but is lost when you quit the application, when you close the stack (unless its <b>destroyStack</b> <glossary tag="property">property</glossary> is false). If <b>variable preservation</b> is turned on, script locals retain their values when the <property tag="script">script</property> is re-compiled, unless there is an error in the script. With <b>variable preservation turned</b> off, script locals lose their values when the script is recompiled.</p>
  </description>
</doc>