<doc>
	<legacy_id>2080</legacy_id>
	<name>put</name>
	<type>command</type>

	<syntax>
		<example>put <i>value</i> [{before | into | after} <i>container</i>]</example>
		<example>put <i>value</i> into URL <i>destinationURL</i></example>
	</syntax>

	<synonyms>
	</synonyms>

	<summary>Places a <function tag="value">value</function> into a <glossary tag="container">container</glossary>.</summary>

	<examples>
<example>put &quot;ABC&quot;</example>
<example>put 3 + 12 into myVariable</example>
<example><p>put return  someGlobalVar after field &quot;Accumulations&quot;</p></example>
<example>put tData into URL &quot;ftp://ftp.myftpserver.com&quot;</example>
<example>put homegrownMP3Data into URL &quot;binfile:My file.MP3&quot;</example>
	</examples>

	<history>
		<introduced version="1.0">Added.</introduced>
		<deprecated version=""></deprecated>
		<removed version=""></removed>
		<changed version="4.6.1">Added Support for iOS.</changed>
	</history>

	<objects>
	</objects>

	<platforms>
		<mac/>
		<windows/>
		<linux/>
		<ios/>
		<android/>
	</platforms>

	<classes>
		<desktop/>
		<server/>
		<web/>
		<mobile/>
	</classes>

	<security>
		<disk/>
	</security>


	<classification>
		<category>Values  Properties</category>
		<category>Text and Data Processing</category>
	</classification>

	<references>
		<command tag="libURLDownloadToFile">libURLDownloadToFile Command</command>
		<command tag="libURLftpUpload">libURLftpUpload Command</command>
		<keyword tag="after">after Keyword</keyword>
		<keyword tag="before">before Keyword</keyword>
		<keyword tag="message box">message box Keyword</keyword>
		<message tag="urlProgress">urlProgress Message</message>
	</references>

	<description>
	<overview>Use the <b>put</b> <glossary tag="command">command</glossary> to set the value of a <glossary tag="variable">variable</glossary>, put text into a <keyword tag="field">field</keyword>, put data into a <keyword tag="file">file</keyword>, display text in the <keyword tag="message box">message box</keyword>, or upload a file to a server.</overview>

		<parameters>
  <parameter>
    <name>value</name>
    <description>Is any expression that evaluates to a string.</description>
  </parameter>
  <parameter>
    <name>container</name>
    <description>Specifies the kind of container into which a value is to be placed. The container is one of the following:</description>
    <options title="">
      <option>
        <item>field</item>
        <description/>
      </option>
      <option>
        <item>button</item>
        <description/>
      </option>
      <option>
        <item>image</item>
        <description/>
      </option>
      <option>
        <item>URL</item>
        <description/>
      </option>
      <option>
        <item>variable</item>
        <description/>
      </option>
      <option>
        <item>message box</item>
        <description/>
      </option>
    </options>
  </parameter>		</parameters>

	<value></value>
	<comments>If you use the put into form, the <i>value</i> replaces anything that was previously in the <i>container</i>.<p>The put before and put after forms place the <i>value</i> before or after the current contents of the <i>container</i>.</p><p>If you do not specify a <i>container</i>, the <command tag="put">put</command> <glossary tag="command">command</glossary> puts the value into the <keyword tag="message box">message box</keyword>.</p><p></p><p>If you put a <i>value</i> into a nonexistent <i>container</i>, LiveCode assumes it is a <glossary tag="variable">variable</glossary> name, and initializes the <glossary tag="container">container</glossary> as a <glossary tag="local variable">local variable</glossary>. This is the most common way to create a local <glossary tag="variable">variable</glossary>. You can also explicitly <glossary tag="declare">declare</glossary> <glossary tag="local variable">local variables</glossary> with the <command tag="local">local</command> command. If the <property tag="explicitVariables">explicitVariables</property> <glossary tag="property">property</glossary> is set to true, you must <glossary tag="declare">declare</glossary> <glossary tag="local variable">local variables</glossary> before using them, and using the <b>put</b> <glossary tag="command">command</glossary> with a nonexistent variable causes an <glossary tag="error">error</glossary> instead of creating the <glossary tag="variable">variable</glossary>.</p><p></p><p>The action of the put...into URL form varies depending on the type of URL:</p><p></p><p>* When used with a <b>file</b> or <keyword tag="binfile">binfile</keyword> <keyword tag="URL">URL</keyword>, places the <i>value</i> in the specified <keyword tag="file">file</keyword>. If the <keyword tag="file">file</keyword> does not exist, the <command tag="put">put</command> <glossary tag="command">command</glossary> creates it. Use the <keyword tag="file">file</keyword> <keyword tag="URL">URL</keyword> type for text data and the <keyword tag="binfile">binfile</keyword> <keyword tag="URL">URL</keyword> type for <glossary tag="binary data">binary data</glossary>.</p><p></p><p></p><important>If writing to a url container fails, an error is returned in the result. For example:</important><p></p><p><b>local</b> tResult</p><p><b>put</b> tData into url (file:  tFilePath)</p><p><b>put</b> the result into  tResult</p><p><b>if</b> tResult is not empty <b>then</b></p><p>  # Handle error here</p><p><b>else</b></p><p>  # Continue execution</p><p><b>end if</b></p><p></p><p>* When used with a <b>resfile</b> <keyword tag="URL">URL</keyword>, sets the <glossary tag="resource fork">resource fork</glossary> of the specified <keyword tag="file">file</keyword> to the <i>value</i>. Because <glossary tag="resource fork">resource forks</glossary> have a specific format, in general you should use <b>put</b> with a <keyword tag="resfile">resfile</keyword> <keyword tag="URL">URL</keyword> only when the <i>value</i> is also a <keyword tag="resfile">resfile</keyword> <keyword tag="URL">URL</keyword>. The following example copies the entire <glossary tag="resource fork">resource fork</glossary> of one <keyword tag="file">file</keyword> to another:</p><p></p><p>  put URL resfile:My Source into URL resfile:Destination</p><p></p><p></p><note>Unlike its use with the <keyword tag="file">file</keyword> and <keyword tag="binfile">binfile URL</keyword> types, the <b>put</b> <glossary tag="command">command</glossary>, when used with a <keyword tag="resfile">resfileURL</keyword>, does not create the <keyword tag="file">file</keyword> if it doesn't exist. Instead, an error message is returned in the <function tag="result">result</function>. To create the file, first use a <glossary tag="statement">statement</glossary> like the following:</note><p></p><p>  put empty into URL file:<i>filePath</i></p><p></p><p>Then you can use the <b>put</b> <glossary tag="command">command</glossary> with a <keyword tag="resfile">resfile</keyword> <keyword tag="URL">URL</keyword> type to create the <glossary tag="resource fork">resource fork</glossary>.</p><p></p><p></p><important>The syntax for file urls in LiveCode does not conform to RFC1738. To ensure proper operation on all platforms make sure you use file:path rather than file://path.</important><p></p><p>* When used with an <b>ftp</b> <keyword tag="URL">URL</keyword>, <glossary tag="upload">uploads</glossary> the <i>value</i> to an <keyword tag="ftp">FTP</keyword> <glossary tag="server">server</glossary>. If an error occurs during uploading, the error is placed in the <function tag="result">result</function> <control_st tag="function">function</control_st>. The first <keyword tag="word">word</keyword> returned by the <function tag="result">result</function> <control_st tag="function">function</control_st> is error, followed (where appropriate) by the text of the error message returned by the <keyword tag="ftp">FTP</keyword> <glossary tag="server">server</glossary>, including the <glossary tag="server">server</glossary> response code.</p><p></p><p>* When used with an <b>http</b> <keyword tag="URL">URL</keyword>, uses the <keyword tag="http">HTTP</keyword> PUT method to <glossary tag="upload">upload</glossary> the <i>value</i> to the <glossary tag="server">server</glossary>. However, since most <keyword tag="http">HTTP</keyword> <glossary tag="server">servers</glossary> don't implement the PUT method, you usually will use an <keyword tag="ftp">FTP</keyword> <keyword tag="URL">URL</keyword> instead to <glossary tag="upload">upload</glossary> files to an <keyword tag="http">HTTP</keyword> <glossary tag="server">server</glossary>.</p><p></p><p></p><note><glossary tag="upload">Uploading</glossary> a <keyword tag="URL">URL</keyword> by putting a <function tag="value">value</function> into it is a <glossary tag="blocking">blocking</glossary> operation: that is, the <glossary tag="handler">handler</glossary> pauses until LiveCode is finished <glossary tag="upload">Uploading</glossary> the <function tag="value">value</function>. Since contacting a <glossary tag="server">server</glossary> may take some time due to network lag, <keyword tag="URL">URL</keyword> operations may take long enough to be noticeable to the user. To <glossary tag="upload">upload</glossary> without <glossary tag="blocking">blocking</glossary>, use the <command tag="libURLftpUpload">libURLftpUploadcommand</command> instead.</note><p></p><p></p><note>On windows, it is imperative not to name a file with one of the reserved device names: CON, PRN, AUX, NUL, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8 and LPT9. Also do not use these names followed by an extension, for example, NUL.tx7.</note><p></p><p></p><important>If a <glossary tag="blocking">blocking</glossary> operation involving a <keyword tag="URL">URL</keyword> (using the <command tag="put">put command</command> to <glossary tag="upload">upload</glossary> a <keyword tag="URL">URL</keyword>, the <command tag="post">post command</command>, the <command tag="delete URL">delete URL command</command>, or a <glossary tag="statement">statement</glossary> that gets an <keyword tag="ftp">FTP</keyword> or <keyword tag="http">httpURL</keyword>) is going on, no other <glossary tag="blocking">blocking URL</glossary> operation can start until the previous one is finished. If you attempt to use a <keyword tag="URL">URL</keyword> in an <glossary tag="expression">expression</glossary>, or put data into a <keyword tag="URL">URL</keyword>, while another <glossary tag="blocking">blocking URL</glossary> operation is in progress, the <function tag="result">result</function> is set to Error Previous request not completed.</important><p></p><p></p><note>The iOS engines does not support 'libUrl' but allows you to use put in the background. When specifying URLs for iOS, you must use the appropriate form that confirms to the RFC standards. Ensure that you <function tag="URLEncode">URLEncode</function> any username and password fields appropriately for FTP urls.</note></comments>
	</description>
</doc>