The first line of a data set must be of the form “SDDSn”, where n is the integer SDDS version number. This document describes versions 1 through 4.
The SDDS header consists of a series of namelist-like constructs, called namelist commands. These constructs differ from FORTRAN namelists in that the SDDS routines scan each construct, determine which it is, and use the data appropriately. There are six namelist commands recognized under versions 1 through 4. Each is listed below along with the data type and default values.
For each command, an example of usage is given. Several styles of entering the namelist commands are exhibited. I suggest that the user choose a style that makes it easy to pick out the beginning of each command. Note that while each namelist command may occupy one or more lines, no two commands may occupy portions of the same line.
Any field value containing an ampersand must be enclosed in double quotes, as must string values containing whitespace characters.
Another character with special meaning is the exclamation point, which introduces a comment. An exclamation point anywhere in a line indicates that the remainder of the line is a comment and should be ignored. A literal exclamation point is obtained with the sequence \!, or by enclosing the exclamation point in double quotes.
The commands are briefly described in the following list, and described in detail in the following subsections:
The column, parameter, and array commands have a name field that is used to identify the data being defined. Each type of data has a separate “name-space”, so that one may, for example, use the same name for a column and a parameter in the same file. This is discouraged, however, because it may produce unexpected results with some programs. Names may contain any alphanumeric character, as well as any of the following: @ : # + - % . _ $ & / . The first letter of a name may not be a digit.
This optional command describes the data set in terms of two strings. The first, text, is an informal description that is intended principly for human consumption. The second, contents, is intended to formally specify the type of data stored in a data set. Most frequently, the contents field is used to record the name of the program that created or most recently modified the file.
Example:
Note: In many cases it is best to use a string parameter for descriptive text instead of the description command. The reason is that the Toolkit programs will allow manipulation of a string parameter.
This optional command defines a column that will appear in the tabular data section of each data page. The name field must be supplied, as must the type field. The type must be one of short, ushort, long, ulong, float, double, longdouble, character, or string, indicating the corresponding C data types. The string type refers to a NULL-terminated character string.
The optional symbol field allows specification of a symbol to represent the column; it may contain escape sequences, for example, to produce Greek or mathematical characters. The optional units field allows specification of the units of the column. The optional description field provides for an informal description of the column, that may be used as a plot label, for example. The optional format_string field allows specification of the printf format string to be used to print the data (e.g., for ASCII in SDDS or other formats).
For ASCII data, the optional field_length field specifies the number of characters occupied by the data for the column. If zero, the data is assumed to be bounded by whitespace characters. If negative, the absolute value is taken as the field length, but leading and trailing whitespace characters will be deleted from string data. This feature permits reading fixed-field-length FORTRAN output without modification of the data to include separators.
The order in which successive column commands appear is the order in which the columns are assumed to come in each row of the tabular data.
Example (using sddsplot conventions for Greek and subscript operations):
This optional command defines a parameter that will appear along with the tabular data section of each data page. The name field must be supplied, as must the type field. The type must be one of short, ushort, long, ulong, float, double, longdouble, character, or string, indicating the correponding C data types. The string type refers to a NULL-terminated character string.
The optional symbol field allows specification of a symbol to represent the parameter; it may contain escape sequences, for example, to produce Greek or mathematical characters. The optional units field allows specification of the units of the parameter. The optional description field provides for an informal description of the parameter. The optional format field allows specification of the printf format string to be used to print the data (e.g., for ASCII in SDDS or other formats).
The optional fixed_value field allows specification of a constant value for a given parameter. This value will not change from data page to data page, and is not specified along with non-fixed parameters or tabular data. This feature is for convenience only; the parameter thus defined is treated like any other.
The order in which successive parameter commands appear is the order in which the parameters are assumed to come in the data. For ASCII data, each parameter that does not have a fixed_value will occupy a separate line in the input file ahead of the tabular data.
Example:
This optional command defines an array that will appear along with the tabular data section of each data page. The name field must be supplied, as must the type field. The type must be one of short, ushort, long, ulong, float, double, longdouble, character, or string, indicating the corresponding C data types. The string type refers to a NULL-terminated character string.
The optional symbol field allows specification of a symbol to represent the array; it may contain escape sequences, for example, to produce Greek or mathematical characters. The optional units field allows specification of the units of the array. The optional description field provides for an informal description of the array. The optional format_string field allows specification of the printf format string to be used to print the data (e.g., for ASCII in SDDS or other formats). The optional group_name field allows specification of a string giving the name of the array group to which the array belongs; such strings may be defined by the user to indicate that different arrays are related (e.g., have the same dimensions, or parallel elements). The optional dimensions field gives the number of dimensions in the array.
The order in which successive array commands appear is the order in which the arrays are assumed to come in the data. For ASCII data, each array will occupy at least one line in the input file ahead of the tabular data; data for different arrays may not occupy portions of the same line. This is discussed in more detail below.
Example:
This optional command directs that SDDS header lines be read from the file named by the filename field. These commands may be nested.
Example of a minimal header:
This command is optional unless parameter commands without fixed_value fields, array commands, or column commands have been given.
The mode field is required, and may have one of the values “ascii” or “binary”. If binary mode is specified, the other entries of the command are irrelevant and are ignored. In ASCII mode, these entries are optional.
In ASCII mode, each row of the tabular data occupies lines_per_row rows in the file. If lines_per_row is zero, however, the data is assumed to be in “stream” format, which means that line breaks are irrelevant. Each line is processed until it is consumed, at which point the next line is read and processed.
Normally, each data page includes an integer specifying the number of rows in the tabular data section. This allows for preallocation of arrays for data storage, and obviates the need for an end-of-page indicator. However, if no_row_counts is set to a non-zero value, the number of rows will be determined by looking for the occurence of an empty line. A comment line does not qualify as an empty line in this sense.
If additional_header_lines is set to a non-zero value, it gives the number of non-SDDS data lines that follow the data command. Such lines are treated as comments.
If column_major_order is set to a non-zero value and mode is set to “binary”, it will store the column data in column major order instead of the default row major order which normally results in faster reading and writing of the data file.
SDDS2 adds support for unsigned integer data types: ushort and ulong
SDDS3 adds support for column major ordering of the column data in binary format: column_major_order=1
SDDS4 adds support for the long double data type: longdouble
The SDDS library will automatically use the lowest version number required when writing SDDS files.