Updated March 2021; see History
WRITECD #ch, expr1{, …, exprN}
WRITECD #ch, ary()
"Write Comma Delimited" is a variation of the PRINT statement which is useful for creating industry-standard* comma-delimited (or tab-delimited) files, normally called CSV files for "Comma Separated Values."
Note: Although the default delimiter for WRITECD is the comma, it can be set to anything (see MX_CSVDELIM), making the WRITETD variation superfluous and now deprecated. WRITETD still works, for purposes of historical compatibility, but is no longer recommended.
Syntax and operation for the first variation shown above are identical to the PRINT statement, except that WRITECD performs three additional functions which are useful when more than one variable is being output on a line:
• automatically inserts a comma between each variable being output
• automatically quotes any string variable which itself contains any of the "likely" delimiter characters (comma, tab, semicolon, colon, quote, apostrophe) or the custom delimiter character if applicable
• strips leading and trailing blanks from any string variable unless accompanied by a formatting mask
The maximum size of an individual field needing to be enclosed in quotes is 4092 bytes.
The other syntax variation allows you to output all of the elements in an entire array, without specifying them individually.
This is equivalent to:
WRITECD #ch, ary(1), ary(2), ...
... up to the extent of the array.
Note that:
• Requires compiler edit 941+ and A-Shell version 6.5.1697+.
• The ary() must be of type X. The element size can be fixed or dynamic, and the array itself can be fixed (i.e. MAPped) or created with DIMX. DIMX with AUTO_EXTEND is recommended for maximum flexibility.
• See corresponding INPUT CSV #ch, ary().
Example
WRITECD #1,5.2,"Nov 1, 1998"," abc ","Robert ""Bob"" Scott"
Outputs:
5.2,"Nov 1,1998",abc,"Robert 'Bob' Scott"
Comments
WRITECD will convert any embedded quotes (") within a field into apostrophes ('), to try to be more compatible with other CSV readers.
Also note the procedure for breaking up a single line of CSV output into multiple WRITECD statements:
WRITECD #CH, A, B, C,;
WRITECD #CH, D, E, F
This will output the six variables on one line. Note that that the comma after the C and before the semicolon is required. If you omit it, the D output will immediately follow C with no delimiter. If you omit the semicolon from the first line, then you'll get two lines of output.
* Note that the term "industry standard" is used with a good deal of sarcasm and distaste in this context, since the notion of any such standard is farcical—which is why spreadsheet programs employ elaborate "wizards" to aid in the importing of CSV data, and which despite all kinds of fancy heuristics still have to rely on a complicated user interface for specifying all kinds of options, which if not specified properly, may reduce the results to mush. Readers are hereby advised that if they encounter a CSV file which doesn't read in properly using INPUT CSV, they might need to avail themselves of such a wizard to load the file into a spreadsheet and then re-save it, possibly with a different delimiter. This will hopefully result in a CSV file which has the same ideas about "standard" as does INPUT CSV.
History
2021 February, A-Shell 6.5.1697: Add WRITECD or WRITETD of an Entire Array.
2011 May, A-Shell 5.1.1216: Support new custom CSV delimiter per MX_CSVDELIM, expand the list of quoted characters. WRITETD is now deprecated, and should not be used; it remains a valid operator only to preserve operations by older code.