Differences

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

--- transformations:exporttext [2018/05/09 21:02] – dmitry
+++ transformations:exporttext [2021/05/06 22:29] – 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.
-===Options===
+By default, when the file name has no extension, the action automatically appends the extension ".csv" to it.\\
-==Export modes==
+\\
-  * Create new file - create new file or overwrite existing file with the same name
+=====Use cases=====
-  * 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).
+Create a plain-text, unformatted data file for use with a wide variety of applications and services.\\
-==Wrap in quotes==
+\\
-  * Auto - only values that contain a space, the chosen separator, or a line break will be wrapped in double quotes. The rest won't.
+=====Action settings=====
-  * Everything - all values will be wrapped in double quotes.
+^ Setting  ^ Description  ^
-  * Nothing - no values will be wrapped in double quotes, even if they contain spaces, separators or line breaks. Use with care.
+|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//.|
+\\
+=====Remarks=====
+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).\\
+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.\\
+\\
+=====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:**
+<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.\\
+\\
+=====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.