Promotic

FileCsvWrite - method of the Pm object

Description:
Parameterized writing of the data into the CSV file.
Syntax:
Boolean FileCsvWrite(String sFile, String sFields, String sParams, Array aValues)
Parameters:
sFile(String) File to write. Regardless of whether this parameter is set or not, it is possible to open the window for file selection by setting the fileselect parameter.
If a full path is not entered, then it is completed relative to the application folder.
It is recommended to use the PROMOTIC path syntax - see PROMOTIC path to files and folders.
sFields(String) Specifies how the columns from the source data array will be saved in the output CSV file. For example "filecols:0,1,2,3;appnames:name,value,unit,note;".
filecols - Specifies how the columns from the source data array will be saved in the output CSV file. If filecols:all; is set (default), then all columns will be saved observing the column sequence.
A list of number indexes. There is a subsequentialy defined (sequence) index for each column of the source data array to be used for the output CSV file. Each column of the source data array can be saved into arbitrary column of the output CSV file or even omited (index value -1). It means that the list must contain as many items as is the number of columns of the source value array. The number of columns in the output CSV file is defined by the maximal index value (+1) in the list. Empty columns may appear when mapping the source array columns sequence into the output CSV file.
For example, filecols:0,9; means that 2 columns of the source data array will be mapped into 10 (9+1) columns in the output CSV file, where columns with indexes from 1 to 8 will be empty.
For example, filecols:0,2,-1,1; means that 4 columns of the source data array will be mapped into 3 (2+1) columns in the output CSV file, where the column with sequence index 2 of the source data array will not be saved at all.
appnames - A list of column names of the source data array. The defined column names and order must correspond with the source data array. It means that the list must contain as many items as is the number of columns of the output value array. The columns in the source CSV file may differ from the output value array, if the filecols column filter is used. The column names are necessary for creating the header in the CSV file.
sParams(String) Specifies the way of saving the data into the file. For example: "fileselect:yes;colnameheader:yes;delimiter:comma;"
"fileselect:xxx;" (optional)
yes - by calling the method the window for selection a file is opened independently on setting the sFile parameter.
no (default)
"colnameheader:xxx;" (optional)
yes - in the first row of the file there are no data but names of individual columns.
no (default) - already in the first row of the file the data are saved.
"swap:xxx;" (optional)
yes (default) - columns from the file are saved as rows in the resulting matrix (in the data(i,j) cell there is the value of the i-th column and j-th row of the file).
no - rows from the file are saved as rows in the resulting matrix (in the data(i,j) cell there is the value of the i-th row and j-th column of the file).
"delimiter:xxx;" (optional) - (only for CSV) The separator of values in the CSV file. The allowed values are:
semicolon (default) - the separator is a semicolon.
comma - the separator is a comma.
space - the separator is a space.
tab - the separator is a tab.
number - i.e. the separator is defined as a number of the ASCII character (in decimal), for example "delimiter:124;" means the "|" separator (vertical line).
"date.fmt:xxx;" (optional) - Date/time format. The allowed values are:
system (default) - the date/time format is set by Windows OS settings (e.g. 22.11.2010 16:30:15).
pm - PROMOTIC date/time format with 1 second precision (e.g. 2010.11.22 16:30:15).
pmmili - PROMOTIC date/time format - precision 10 ms (e.g. 2010.11.22 16:30:15.250).
real - data type of date/time format Date as a real number (e.g. 41392.123456789).
"real.dsep:xxx;" (optional) - (only for CSV) The format of decimal separator for real numbers. The allowed values are:
system (default) - the decimal separator is defined by Windows OS settings (e.g. 3,14).
dot - the decimal separator is a period (independently on Windows OS setting) (e.g. 3.14).
comma - the decimal separator is a comma (independently on Windows OS setting) (e.g. 3,14).
"lastcolsep:xxx;" (optional)
yes - When writing, the separator is added after the last value on the row, when reading, the empty value at the end of each row is ignored. From the CSV file standard point of view, this is not correct.
no (default) - The separators are present only between values on the same row, not at the end. From the CSV file standard point of view, this is correct.
charset:sss; (optional) - The option specifies the charset. See: Unicode character coding description.
charset:ansi; (default) - The text content will be stored in ANSI code page which is active in Windows OS at the moment (e.g. windows-1250).
charset:utf-8; - The text content will be stored in Unicode UTF-8 encoding (independent on Windows OS active code page).
charset:utf-16; - The text content will be stored in Unicode UTF-16 encoding (independent on Windows OS active code page).
bom:nnn; (optional) - Option specifies whether a BOM tag (3 bytes) is placed to the beginning of the text file that allows the identification of Unicode charset.
bom:1; (default) - A BOM tag is placed to the beginning of the new file that allows identification of the Unicode charset.
bom:0; - The BOM tag for Unicode charset identification is not added to the beginning of the file. This option is suitable for HTML or XML files, where the BOM is not added.
aValues(Array) Source data array (2-dimensional array) that will be saved into the output CSV file.
Return value:
true - on success
false - on error
Note:
For reading data from the CSV file the FileCsvRead method can be used.

This method is not functional in Web panels.
See also:
Example1:
The method displays the window for file selection (the default file is data.csv stored in the application folder). The data from the source array aValues are saved into the selected file. All columns are saved, the values in the file are separated by semicolon and the file does not include the column names in the first row.
JavaScriptVBScriptSelect and copy to clipboard

var bResult = Pm.FileCsvWrite("#app:data.csv", "", "fileselect:yes;", aValues);
Example2:
The method saves data from the source array aValues into the data.csv file in the application folder. The values in the file are separated by semicolon and the file contains the column names in the first row. The source data array has 4 columns (name, value, unit, note).
a) Saving all columns from the source data array with definition of column names and data types.
JavaScriptVBScriptSelect and copy to clipboard

var bResult = Pm.FileCsvWrite("#app:data.csv", "filecols:all;appnames:name,value,unit,note;", "colnameheader:yes;", aValues);
or
JavaScriptVBScriptSelect and copy to clipboard

var bResult = Pm.FileCsvWrite("#app:data.csv", "filecols:0,1,2,3;appnames:name,value,unit,note;", "colnameheader:yes;", aValues);
b) Saving only 3 columns (without the "unit" column) from the source data array with mixed sequence in the output CSV file (name,note,value), with definition of the column names and data types. Because the source data array is identical, the list of column names remains the same.
JavaScriptVBScriptSelect and copy to clipboard

var bResult = Pm.FileCsvWrite("#app:data.csv", "filecols:0,2,-1,1;appnames:name,value,unit,note;", "colnameheader:yes;", aValues);

History:
Pm9.00.25: New options charset:sss; and bom:nnn; enabling Unicode CSV files.
Pm8.02.13:
- Input value matrix aValues was locked by method calling and then it was not possible to call for example ReDim over the array.
- If the "fileselect:yes;" was set and the file selection window was not confirmed, then the method was written into the file anyway.
Pm8.02.00: Created
PROMOTIC 9.0.27 SCADA system documentation MICROSYS, spol. s r.o.

Send page remarkContact responsible person
Navigation:
 
- Pm
 
- Abs
- Cos
- E
- Exp
- FileCsvWrite
 
 
- LN2
- PI
- Pow
- Sin
- Tan
© MICROSYS, spol. s r.o.