<doc>
  <legacy_id>2477</legacy_id>
  <name>try</name>
  <type>control structure</type>
  <syntax>
    <example>try  <i>statementList</i>catch <i>errorVariable</i><i>  errorStatementsList</i>[finally  <i>cleanupStatementsList</i>]end try</example>
  </syntax>
  <library></library>
  <objects>
  </objects>
  <synonyms>
  </synonyms>
  <classification>
    <category>Writing LiveCode</category>
  </classification>
  <references>
    <control_st tag="throw">throw Control Structure</control_st>
    <keyword tag="finally">finally Keyword</keyword>
    <keyword tag="end try">end try Keyword</keyword>
  </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="execute">Executes</glossary> a list of <glossary tag="statement">statements</glossary>, sending any <glossary tag="error">errors</glossary> to the <control_st tag="try">try</control_st> <glossary tag="control structure">structure</glossary> to be handled.</summary>
  <examples>
  </examples>
  <description>
    <p>Use the <b>try</b> <glossary tag="control structure">control structure</glossary> to execute a series of <glossary tag="statement">statements</glossary> and handle any <href tag="../dictionary/error_message.xml">error messages</href> in the <keyword tag="catch">catch</keyword> section, instead of letting LiveCode display the error window.</p><p/><p><b>Form:</b></p><p>The <b>try</b> <glossary tag="control structure">control structure</glossary> begins with the word<code> try </code>on a single line, followed by a list of LiveCode <glossary tag="statement">statements</glossary>.</p><p/><p>The <b>catch</b> section begins with the <keyword tag="catch">catch</keyword> <glossary tag="keyword">keyword</glossary>, followed by a <glossary tag="parameter">parameter</glossary> name. If any <glossary tag="error">errors</glossary> occur during <glossary tag="execute">execution</glossary> of the <i>statementList</i>, the <href tag="../dictionary/error_message.xml">error message</href> is placed in the <i>errorVariable</i> <glossary tag="parameter">parameter</glossary>, and the <i>errorStatementsList</i> is <glossary tag="execute">executed</glossary>. <glossary tag="statement">statements</glossary> in the <i>errorStatementsList</i> can refer to the <function tag="value">value</function> of the <i>errorReport</i>.</p><p/><p>The <b>catch</b> section may be followed by an optional <keyword tag="finally">finally</keyword> section. The <i>cleanupStatementsList</i> is <glossary tag="execute">executed</glossary> normally, even if LiveCode encountered an <control_st tag="exit">exit</control_st> or <control_st tag="pass">pass</control_st> statement in the <i>statementList</i>.</p><p/><p>The <b>try</b> <glossary tag="control structure">structure</glossary> ends with an <keyword tag="end try">end try</keyword> <glossary tag="statement">statement</glossary>.</p><p/><p><b>Parameters:</b></p><p>The <i>statementList</i>, <i>errorStatementsList</i>, and <i>cleanupStatementsList</i> each consist of one or more valid <glossary tag="LiveCode">LiveCode</glossary> <glossary tag="statement">statements</glossary>.</p><p/><p>The <i>errorVariable</i> is a valid <glossary tag="variable">variable</glossary> name.</p><p/><p><b>Comments:</b></p><p>Each of the statements in the <i>statementList</i> is <glossary tag="execute">executed</glossary> normally, just as though the <i>statementList</i> were not in a <b>try</b> <glossary tag="control structure">structure</glossary>, except that any <glossary tag="error">errors</glossary> that would normally display an error window instead trigger the <keyword tag="catch">catch</keyword> section. This happens even if the <glossary tag="error">error</glossary> is in another <glossary tag="handler">handler</glossary> that's <glossary tag="call">called</glossary> from within the <b>try</b> <glossary tag="control structure">structure</glossary>.</p><p/><p>The statements in the <b>catch</b> section are <glossary tag="execute">executed</glossary> only if an <glossary tag="error">error</glossary> occurs. Only <glossary tag="error">errors</glossary> that would normally display the error window are handled by the <keyword tag="catch">catch</keyword> section. If the <glossary tag="error">error</glossary> would not normally display the error window--for example, errors when opening a <keyword tag="file">file</keyword> with the <command tag="open file">open file</command> <glossary tag="command">command</glossary>--it doesn't <glossary tag="trigger">trigger</glossary> the <keyword tag="catch">catch</keyword> section.</p><p/><p>The statements in the <b>finally</b> section are <glossary tag="execute">executed</glossary> whether or not there is an <glossary tag="error">error</glossary>. Since the <keyword tag="finally">finally</keyword> section is always <glossary tag="execute">executed</glossary> even if the <i>statementList</i> contains an <control_st tag="exit">exit</control_st> or <control_st tag="pass">pass</control_st> <glossary tag="statement">statement</glossary>, it can be used for final cleanup actions such as deleting <glossary tag="variable">variables</glossary>. The <keyword tag="finally">finally</keyword> section is an optional part of the <b>try</b> <glossary tag="control structure">structure</glossary>.</p><p/><p><code/><b>Note:</b><code/> The <b>try</b> <glossary tag="control structure">control structure</glossary> is implemented internally as a <glossary tag="command">command</glossary> and appears in the <function tag="commandNames">commandNames</function>.</p>
  </description>
</doc>