Differences

This shows you the differences between two versions of the page.

--- transformations:exporttext [2019/01/10 11:35] – dmitry
+++ transformations:exporttext [2021/07/19 02:08] (current) – [Examples] craigt
@@ Line 1: / Line 1: @@
-===== Export into delimited text file =====
+{{ transformations:ExportDelimitedTextAction.png}}
+======EXPORT INTO DELIMITED TEXT FILE======
+Category: Export / File\\
-This transformation exports table into a delimited text file. The file name can use either full or relative path. It can also be specified using a [[:parameters|parameter]].
+\\
+=====Description=====
+This action exports a table into a delimited text file. The file name can use either a full or relative path.
-By default, when the file name has no extension, the action automatically appends extension ".txt" to the file name.
+\\
+=====Use cases=====
+Create a plain-text, unformatted data file (such as CSV file) to exchange data with a wide variety of applications and services.\\
-===Options===
+\\
+=====Action settings=====
+^ Setting  ^ Description  ^
+|File<sup>*</sup>|Enter a fully-qualified file name for the output file (includes relative or absolute path).  |
+|Separator|Select the delimiting character used to define columns in the exported file.  Options:  //Comma//, //Semicolon//, //Tab//, //Pipe//,\\ //Tilde//, //Space//, //Custom// (and select from the editor window), or //No separator//. |
+|Decimal|Select the character used within numeric values to define decimal places.  Options:  //Point// or //Comma//.|
+|Export mode|Select whether this action will create a new file, or append to an existing file.  See the table below for details.|
+|File already exists|When selecting to "Create new file" in the option above, choose whether to overwrite the existing file, rename the\\ existing file, or halt the action's execution.  See the "File already exists options" table below for details.|
+<sup>*</sup> Setting can be specified using a [[:parameters|parameter]].\\
+\\
+====Export mode options====
+^Option ^Description ^
+|Create new file|Create a new file or overwrite an existing file with the same name.  See the "File already exists options" table\\ below for additional details.|
+|Append to file (or create)|Append the dataset to an existing file (the header row will not be appended) or create a new file if it does not\\ already exist.  See the "Remarks" section below for additional details.|
+\\
+====File already exists options====
+^Option ^Description ^
+|Overwrite|The new file replaces the original file.|
+|Rename|The original file will be renamed with "backup" and a serial number appended to the file name.  The new file will\\ possess the name specified in the //File// setting.|
+|Halt project execution|The project will stop processing and this action will display a warning symbol.|
+\\
+\\
+=====Advanced options=====
+^ Setting  ^ Description  ^
+|Encoding|Select the encoding format to use for the exported file. If you're not sure what to choose, try UTF-8 as it's\\ the most common Unicode encoding.|
+|Don't write BOM|When checked, the byte order mark is not written to the output file.  See [[https://en.wikipedia.org/wiki/Byte_order_mark|Wikipedia - Byte order mark]] for details. |
+|Wrap in quotes|Select which values are wrapped in quotation marks in the export file.  See the table below for details.|
+|Don't write column headers|Column headings are not written into the exported file.|
+|Preserve formatting| Export number values (including dates) using the currently selected column format. |
+\\
+====Wrap in quotes options====
+^Option ^Description ^
+|Auto|Only values that contain the chosen separator or a line break, or numeric values data-typed as text, will be wrapped in double-quotes.  Other value types will not be.|
+|Everything|All values will be wrapped in double-quotes.|
+|Nothing|No values will be wrapped in double quotes, even if they contain spaces, separators, or line breaks.  //Use this option with care//.|
-==Export modes==
+\\
-  * Create new file - create new file or overwrite existing file with the same name
+=====Remarks=====
-  * Append to file - append dataset to existing file (the row with headers will not be appended). Note that the operation doesn't change order of columns in appended dataset, even if columns in the existing file are in different order. If the file doesn't exist it will be created automatically (the row with headers will be inserted first).
+By default, when the file name has no extension, the action automatically appends the extension ".csv" to it.
-==Wrap in quotes==
+The "Append to file" operation doesn't change the order of the columns in the appended dataset, even if columns in the existing file are in a different order. If the file doesn't exist, it will be created automatically (the row with headers will be inserted first, in this case).\\
-  * Auto - only values that contain a space, the chosen separator, or a line break will be wrapped in double quotes. The rest won't.
-  * Everything - all values will be wrapped in double quotes.
+Use caution when selecting "Nothing" for the //Wrap in quotes// Advanced option.  Values containing the selected delimiter, line breaks, or numbers that should be considered text may be incorrectly parsed by applications or systems accessing the file.\\
-  * Nothing - no values will be wrapped in double quotes, even if they contain spaces, separators or line breaks. Use with care.
+\\
+=====Examples=====
+**Source table:**
+^RecID ^FName ^LName ^Address ^City ^RegionState ^Zip ^
+|  1001|Meghan  |Monroe  |P.O. Box 748, 8176 Lectus Rd.  |Gary  |IN  |52188  |
+|  1002|Demetria  |Chang  |5913 Elit Rd.  |Jefferson City  |MO  |79008  |
+|  1003|Karyn  |Meyer  |153-2405 Arcu Road  |Lexington  |KY  |46663  |
+|  1004|Steel  |Wynn  |634-8310 Ante Avenue  |Essex  |VT  |86255  |
+|  1005|Mohammad  |Gillespie  |890-4447 Orci. Ave  |St. Petersburg  |FL  |65929  |
+|  1006|Lance  |Christian  |Ap #999-2401 Cubilia Rd.  |Jackson  |MS  |36778  |
+\\
+**Action parameters:**
+> Separator is "Comma"
+> Wrap in quotes is "Auto"
+\\
+**Result data:**
+<code>
+RecID,FName,LName,Address,City,RegionState,Zip
+,Meghan,Monroe,"P.O. Box 748, 8176 Lectus Rd.",Gary,IN,"52188"
+,Demetria,Chang,5913 Elit Rd.,Jefferson City,MO,"79008"
+,Karyn,Meyer,153-2405 Arcu Road,Lexington,KY,"46663"
+,Steel,Wynn,634-8310 Ante Avenue,Essex,VT,"86255"
+,Mohammad,Gillespie,890-4447 Orci. Ave,St. Petersburg,FL,"65929"
+,Lance,Christian,Ap #999-2401 Cubilia Rd.,Jackson,MS,"36778"
+</code>
+The first record's Address is enclosed in quotes since it contains a comma, which is the designated delimiter.\\
+All Zip values are quoted as they are numeric values that have been re-typed as text.\\
+\\
+====Community examples====
+  * [[https://community.easymorph.com/t//1629/2|In case, no file to load]] ([[https://community.easymorph.com/uploads/short-url/4OREDaUn1vdfwxKOGmMoLXAl7CB.morph|Project]]; Module: //Main//; Group: //Tab 1//; Table: //Create it, if it doesn't//; Action position: //3//)
+  * [[https://community.easymorph.com/t//1876/2|How to report validation failures?]] ([[https://community.easymorph.com/uploads/short-url/x8xqV8QqQbnnI467dxWdhLbXnFr.morph|Project]]; Module: //Main//; Group: //Tab 1//; Table: //Process invalid rows//; Action position: //2//)
+  * [[https://community.easymorph.com/t//2660/7|Conditional execution]] ([[https://community.easymorph.com/uploads/short-url/qSgHAXCrkqD6AtLLp5ZOlOv1vIG.morph|Project]]; Module: //Main//; Group: //Group 2//; Table: //Table2//; Action position: //3//)
+\\
+=====See also=====
+  * [[transformations:exportplaintext|Export plain text]]
+  * [[transformations:importtext|Import delimited text file]]
-==Don't write column headers==
-Don't write into the file a row with column headers.
-==Preserve formatting==
-Export number values (including dates) using the currently selected column format.