ArrayToFile

int ArrayToFile (char *fileName, void *array, int dataType, int numberOfElements, int numberOfGroups, int arrayDataOrder, int fileLayout, int colSepStyle, int fieldWidth, int fileType, int fileAction);

Purpose

Saves an array to a file using various formatting options. ArrayToFile creates, opens, writes, and closes the file. You can use FileToArray to read back the file into an array.

Parameters

Input
Name Type Description
fileName string Name of the file to generate.

fileName can be an absolute pathname or a relative filename. If you use a relative filename, ArrayToFile creates the file relative to the current working directory.
array void * Numeric array to be saved to the file.
dataType integer Array element data type.

dataType must be one of the following data types:

character VAL_CHAR
short integer VAL_SHORT_INTEGER
integer VAL_INTEGER
floating point VAL_FLOAT
double precision VAL_DOUBLE
unsigned character VAL_UNSIGNED_CHAR
unsigned short integer VAL_UNSIGNED_SHORT_INTEGER
unsigned integer VAL_UNSIGNED_INTEGER
numberOfElements integer Number of array elements to save.
numberOfGroups integer If you save the array data in ASCII format, you can divide the array data into groups. ArrayToFile can write groups as columns or rows. numberOfGroups specifies the number of groups into which to divide the array data. If you do not want to divide your data into groups, use 1.
arrayDataOrder integer If you divide your array data into groups, arrayDataOrder specifies how the data of different groups is ordered in the array. The choices are as follows:
  • VAL_GROUPS_TOGETHER—Specifies to store the elements of each data group consecutively in the data array.
  • VAL_DATA_MULTIPLEXED—Specifies to store the first elements of all data groups together, followed by the second elements and so on.
fileLayout integer If you save the array data in ASCII format, fileLayout specifies how ArrayToFile arranges the data in the file. The choices are as follows:
  • VAL_GROUPS_AS_COLUMNS
  • VAL_GROUPS_AS_ROWS
If you have only one group, use VAL_GROUPS_AS_COLUMNS to write each array element on a separate line.
colSepStyle integer If you tell ArrayToFile to write multiple values on each line, colSepStyle specifies how to separate the values. The choices are as follows:
  • VAL_CONST_WIDTH—Specifies to use a constant field width for each column. The values are right–justified in each column. If the field width is not long enough for the string representation of a value, a '*' appears as the last character in the column.
  • VAL_SEP_BY_COMMA—Specifies to follow each value, except the last value on the line, with a comma.
  • VAL_SEP_BY_TAB—Specifies to separate values with tabs.
Note  This parameter only applies if the file type is ASCII.
fieldWidth integer If you specify a colSepStyle of VAL_CONST_WIDTH, fieldWidth specifies the width of the columns. If you do not specify a colSepStyle of VAL_CONST_WIDTH, this parameter is ignored.
fileType integer Specifies whether to create the file in ASCII or binary format. The choices are as follows:
  • VAL_ASCII
  • VAL_BINARY
Note  If the file type is ASCII and the data type is float or double, then ArrayToFile uses at most six digits of precision. This is the default precision of the formatting functions in the Formatting and I/O Library.
fileAction integer Specifies the location in the file to begin writing data if the named file already exists. The choices are as follows:
  • VAL_TRUNCATE—Positions the file pointer at the beginning of the file and deletes the prior file contents.
  • VAL_APPEND—All write operations append data to the file.
  • VAL_OPEN_AS_IS—Positions the file pointer at the beginning of the file but does not affect the prior file contents.

Return Value

Name Type Description
status integer Indicates whether the function succeeded or failed.

If the value is –1, –2, or –3, you can use GetFmtIOError to get more information about the type of error that occurred.

Code Description
0 Success.
–1 Error attempting to open file.
–2 Error attempting to close file.
–3 An I/O error occurred.
–4 Invalid dataType parameter.
–5 Invalid numberOfElements parameter.
–6 Invalid numberOfGroups parameter.
–7 Invalid arrayDataOrder parameter.
–8 Invalid fileLayout parameter.
–9 Invalid fileType parameter.
–10 Invalid colSepStyle parameter.
–11 Invalid fieldWidth parameter.
–12 Invalid fileAction parameter.