FTCL Parameter Files

Format

Keyword/value pairs

A 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 datatypes are:
	char[N] - character string of length N 
			(N = length of longest char string to appear 
		       	in table +1, must be explicitly specified)
     	float - 4-byte floating-point
     	double - 8-byte floating-point
     	short - 2-byte integers		(signed short assumed)
     	int - 4-byte integers		(signed int assumed)
	enum - enumerated types         (as in the C language)

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

For example:

	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}

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

The idReport files have an attribute defined in the typedef struct as:

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

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 number 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.

For example, if one wants to keep track of when one is starting or ending a series of runs in a table, you can define an enum such as the following at the top of the table:

# Entry written at start or end of run
typedef enum {
        START,
        END
} RUNMARK;

	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 FTCL file:

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

An enum definition in a param file with multiple tables is shown here idReport

The IDL Yanny parameter format also supports multi-dimensional arrays. For example, an array of strings could be defined with

     char NAME[2][20];

     {Eat "more bananas"}

     char NAME[2][0];

Reading and Writing

ftcl> set chains [param2Chain $fileName keys]

Say we have a TCLX keyed list stored in the variable "keys", and two chains with the handles "h1" and "h2" that we wish to write to an FTCL parameter file named "$outFileName""

ftcl> chain2Param $outFile "h1 h2" keys

For reading and writing IDL Yanny parameter files, one can use the routines YANNY_WRITE, YANNY_READ, YANNY_PAR. The format allows one to loss-lessly switch between IDL structures, FITS binary tables and IDL Yanny parameter files.

One can also read FTCL parameter files with these same IDL routines, except that the case-sensitivity to element names is lost. The two structures in an sdReport file can be read with:

     IDL> yanny_read, 'sdReport-52059.par', a, hdr=hdr

     IDL> help, *a[0], /structure
     IDL> help, *a[1], /structure

     IDL> print, (*a[0]).mjd

     IDL> print, yanny_par(hdr, 'equinox')

Caveats

1. If the last character in a string is a quoted double quote, it is chopped off by param2Chain.
2. Quoting characters, i.e. '\' (backslash characters), in strings are not removed in param2Chain when quoting a double quote.