Description of ASCII Parameter Files

Most simple ASCII data files used in the SDSS are formatted as "ASCII parameter files". Examples of this are the endpoints of survey stripes (with stripe number, eta, minimum lambda, and maximum lambda) and the list of stripe segments in SDSS data (listing run, rerun, camcol, field0, nFields, etc - see this tsChunk.par example). This file format is described here.

Format ASCII parameter files contain two elements, keyword/value pairs and tables.

Keyword/value pairs

A line in the file line may contain a keyword/value pair. The first token is the keyword. The remainder of the line, up to a comment-delimiting '#' sign, is the value of the keyword. In the following example, the value '51256' is assigned to the keyword 'MJD', and the value 'u g r i z' is assigned to the keyword 'filters':

mjd	51256		# MJD day number of observations
filters u g r i z

Tables

Tables of data are given by first defining a C-like structure which defines the table format. Then, any lines in the file whose first token is the name of the structure are considered to contain the data for a single entry in the table. The tokens in each line are in the same order as in the structure. Arrays are contained within '{ }' and array elements are whitespaced-separated. Lines may be continued using a backslash (\) as the last character. For example, a simple weather table containing four different temperatures stored as an array along with a single pressure, humidity, and time stamp might look like:

typedef struct {
   double mjd;
   double humidity;
   double pressure;
   double temperature[4];
} WEATHER;

WEATHER 52191.300 0.23 75.21 {10.4 10.7 10.6 10.7}
WEATHER 52191.310 0.24 75.26 {10.3 10.6 10.5 10.7}
WEATHER 52191.320 0.23 75.28 {10.2 10.6 10.4 10.5}
WEATHER 52191.330 0.23 75.30 {10.2 10.5 10.3 10.3}

The name of the structure (WEATHER in the above example) must be in ALL CAPS in the structure definition, but is case-insensitive in the table entries.

Standard (allowed) datatypes are:

One dimensional fixed length arrays of the above types are supported.

typedef struct {
	float mag[5];
	char b[5][20];
	double c;
	int flags[2];
} MYSTRUCT;

mystruct {17.5 17.546 17.4 16.1 16.0} {the rain in "spain is" wet} 1.24345567 {123123 1231213}
mystruct {17.5 17.446 17.4 16.1 16.0} {the snow in chile "is dry"} 7.24345567 {123123 0}

As mentioned, a backslash (\) may be used as a line continuation character for long table or header entries.

Note on charater string length in tables:

    char      program[20];    # Identifying name for CCD program.

The length of the string is defined in square brackets after the variable name. The actual length (20 in this case) is defined by the data model for the structure or file you are writing. No 'program' string in the table section of the corresponding ASCII param file in this example then should exceed 19 characters (1 extra for the C termination).

Enums

You may also use an enum to define an enumerated data type. These are similar to C-language enums, in that one lists a comma-separated list of identifying tags in a multi-line typedef statement which are internally stored as ints, 0, 1, 2, 3, etc, but which are referenced by the tag for mnemonic convenience or documentation purposes. The tags should start with a letter, and be alphanumeric, like a variable-name in C. Underscores are permitted in the tag name, i.e. START_RUN, END_RUN. By convention enum values (i.e. START,END) are all-caps and newlines separate the comma-separated entries in the typedef definition of the enum.

For example, to track the starting or ending a series of runs in a table, an enum such as the following can be defined at the top of the param file:

# Entry written at start or end of run

typedef enum {
        START,
        END
} RUNMARK;

#and a structure and table with the attribute defined using this enum looks like this:

typedef struct {
	int run;	      # Run number
	RUNMARK   mark;       # Entry written at start or end of run.
	double mjd;	      # time of START or END of run
} NEWSTRUCT;

NEWSTRUCT 712 START 51876.1
NEWSTRUCT 712 END 51876.123

NEWSTRUCT 722 START 51878.1
NEWSTRUCT 722 END 51879.123

For this example, each table entry has either START or END for its RUNMARK field value. The enum definition needs to appear in the file before a typedef that uses that enumerated type.

Multiple Tables/Structures in a single ASCII file

A given file may contain any number of keyword/value lines and any number of tables.

Reading and Writing: