2.3 Structure of SDDS ASCII Data Pages

Since the user may wish to create SDDS data sets without using the SDDS function library, a more detailed description of the structure of ASCII data pages is provided. Comment lines (beginning with an exclamation point) may be placed anywhere within a data page. Since they essentially do not exist as far as the SDDS routines are concern, I omit mention of them in what follows.

The first SDDS data page begins immediately following the data command and the optional additional header lines, the number of which is specified by the additional_header_lines parameter of the data command.

If parameters have been defined, then the next Np - Nfp lines each contains the value of a single parameter, where Np is the total number of parameters and Nfp is the number of parameters for which the fixed_value field was specified. These will be assigned to the parameters in the order that the parameter commands occur in the header. Multi-token string parameters need not be enclosed in quotation marks.

If arrays have been defined, then the data for these arrays comes next. There must be at least one ASCII line for each array. This line must contain a list of whitespace-separated integer values giving the size of the array in each dimension. The number of values must be that given by the dimensions field of the array definition. If the number of elements in the array (given by the product of these integers) is nonzero, then additional ASCII lines are read until the required number of elements has been scanned. It is an error for a blank line or end-of-file to appear before the required elements have been scanned.

If tabular-data columns have been defined, the data for these elements follows. If the no_row_counts parameter of the data command is zero, the first line of this section is expected to contain an integer giving the number of rows in the upcoming data page. If no_row_counts is non-zero, no such line is expected. The remainder of the tabular data section has various forms depending on the parameters of the data command, as discussed above. The default format is that each line contains the whitespace-separated values for a single row of the tabular data.

For column and array data, string data containing whitespace characters must be enclosed in double-quotes. For column, array, and parameter data, nonprintable character data should be “escaped” using C-style octal sequences.

More than one data page may appear in the data set. Subsequent data pages have the same structure as just described. If no_row_counts=1 is given in the data command, then a blank line is taken to end each data set. An invalid line (e.g., too few rows or invalid data) is treated as an error, and the rest of the file is ignored.