
CGATS file I/O library, V2.01 README file
-----------------------------------------

Package contents:
-----------------
cgatslib.zip   ZIP archive of the following files
Readme.txt     This file.
License.txt    Important! - Permissions for use of this package.
cgats.c        CGATS Library source code.
cgatsstd.c     I/O and malloc source code.
cgats.h        CGATS Library include file. Note machine dependent defines.
pars.c         Parser source code.
parsstd.c      I/O and malloc source code.
pars.h         Parser include file. Note machine dependent defines.
Jampfile       JAM style "makefile" see <http://www.perforce.com/jam/jam.html>
Makefile       Makefile. Modify this to include one of the following rule sets.
Makefile.WNT   Makefile defines for Microsoft C++ on Windows NT
Makefile.IBMNT Makefile defines for IBM C++ on Windows NT
Makefile.UNIX  Makefile defines for generic UNIX system
Makefile.OSX   Makefile defines for Apple MAC OSX

Changes:
--------

Changes since V2.00

	Removed all exit()s from code - now return error values
	from all functions.

	Added abstract objects for File I/O and memory allocation
	to improve system compatibility.

	Separated the implimentations of the abstract I/O and
	memory objects that ise stdio and malloc into separate
	files so that a library can be compiled without reference
	to these system calls.


---------------------------------------------------------------
                DOCUMENTATION

	This library has been implemented from the CGATS.5 Data Exchange Format
	specification, in Annex J, of the ANSI CGATS.5-1993 standard.
	See <http://www.npes.org/standards/description.htm>
	
    This module attempts to make reading CGATS.5 and IT8.7 files
    easy and convenient. Since the standard is a less than clear
    on some points it is hard to know how much compatibility is
    to be expected.

    The module supports non-standard keywords and fields automatically.
    It does not support reading of comments.
    It supports reading and writing multiple tables within one file.
	Abreviated tables may be written.
	Non-standard fields written by this module will be recognized
	correcty when read by this module (data types are written
	unambiguously - reals all have a decimal point, no non-quoted strings
	are written that could be interpreted as a real or integer), but
	there is no certainty that non-standard fields written by other
	software will be recognized corectly (e.g. - how to you tell
	whether 1234 is an integer, real, or non-quoted string ?)

    To creat a file each element needs to be built up in turn:

    Create an empty cgats structure:
        new_cgats().

    A non-standard memory allocator can be specified for use
    by the cgats object by passing an object that inherits
    from the cgatsAlloc class defined in parse.h, to the
    new_cgats_al(cgatsAlloc *al) constructor.


    Use the module methods to:


	Add a user defined file identifier to augment the standard identifiers:
        add_other(cgats *p, char *osym)
	This can be used to read or write table that are compatible with CGATS.5
	syntax but have different file identifiers.
	Use a zero length string (ie. just "") for wildcard.
	Normaly returns 0, returns -ve if there was a system error,
	& sets p->errc & p->err appropriately.


    create an empty table entry:
        add_table(cgats *p, table_type tt, int oi)
    tt is the table type: it8_7_1, it8_7_2, it8_7_3, it8_7_4, cgats_5, cgats_X,
	tt_other or tt_none.
	cgat_X represents any "CGATS.XXX" table type.
	If tt_other is used for creating a file, then oi must be set to the index of the
	user defined table identifiers set by calls to p->add_other();
	The table type read can be identified by looking at the index
	p->t[table_number].tt, which will be set to the table type.
	If the type is cgats_X type, the type actually found will be in p->cgats_type.
	If tt == tt_other, then the "other index" value is p->t[table_numberx].oi.
	For a wildcard tt_other, the actual type found will be at p->others[oi].

    Tables are added in turn, and are indexed from 0 in other functions.
	Returns 0 normally.
	It returns -2 if there was a system error, & sets p->errc & p->err appropriately.


	Suppress the writing of the file identifier string, standard keyword definitions
	and/or field definitions for a second or subsequent table:
		set_table_flags(cgats *p, int table, int sup_id, int sup_kwords, int sup_fields);
	This only makes sense if the subsequent table has the same identifier type, keywords
	and field definitions as the preceding table. Returns 0 normally.
	It returns -1 if there was an error, & sets p->errc & p->err appropriately.


    Add keywords and their values:
        int add_kword(cgats *p, int table, char *ksym, char *kdata, char *kcom);
	The return value is the index of the new keyword, or -1, errc & err on error.
    Any non-standard keywords will automatically be declared in the file.
	The comment is optional and NULL should be passed if no comment is to be used
	after the keyword/value pair.

    Standard keywords are:
        ORIGINATOR          System, organization or individual that created data
        DESCRIPTOR          Purpose or contents of the data file
        CREATED             Date of creation of the file
        MANUFACTURER        Manufacturer of physical target
        PROD_DATE           Year and month of physical target production yyyy:mm
        SERIAL              Unique physical target serial number
        MATERIAL            Material physical target was produced on
        INSTRUMENTATION     Manufacturer and model number of measuring instrument
        MEASUREMENT_SOURCE  Illumination used for spectral measurements
        PRINT_CONDITIONS    Characteristics of printed sheet being reported

    Standard keywords will be created automatically if necessary for a legal file format.

    The following kewords are supplied automatically by the module,
    and cannot be used for other things:    
        NUMBER_OF_FIELDS
        BEGIN_DATA_FORMAT
        END_DATA_FORMAT
        NUMBER_OF_SETS
        BEGIN_DATA
        END_DATA
        KEYWORD


    Add fields:
        int add_field(cgats *p, int table, char *fsym, data_type ftype);

	The return value is the index of the new field, or return
	-1, errc & err on error, -2, errc & err on system error.

    ftype defines the data type from: r_t, i_t, cs_t, nqcs_t.
        r_t is the real (double) type,
        i_t is the integer (int) type,
        cs_t is the character string (char*) type,
        nqcs_t is the same as cs_t except that it will be non-quoted if possible.
    Note that the type must agree with the standard type if the field is
    from the set default data format identifiers:
    
        SAMPLE_ID    nqcs_t   Identifies sample which data represents
        STRING       cs_t     Identifies label, or other non-machine readable value.
        CMYK_C       r_t      Cyan percentage of CMYK
        CMYK_M       r_t      Magenta percentage of CMYK
        CMYK_Y       r_t      Yellow percentage of CMYK
        CMYK_K       r_t      Black percentage of CMYK
        D_RED        r_t      Red filter reflection density
        D_GREEN      r_t      Green filter reflection density
        D_BLUE       r_t      Blue filter reflection density
        D_VIS        r_t      Visual filter reflection density
        RGB_R        r_t      Red component of RGB data
        RGB_G        r_t      Green component of RGB data
        RGB_B        r_t      Blue component of RGB data
        SPECTRAL_NM  r_t      Wavelength of measurement in nanometers
        SPECTRAL_PCT r_t      Precentage reflectance/transmittance
        XYZ_X        r_t      X component of tristimulus data
        XYZ_Y        r_t      Y component of tristimulus data
        XYZ_Z        r_t      Z component of tristimulus data
        XYY_X        r_t      x component of chromaticity data
        XYY_Y        r_t      y component of chromaticity data
        XYY_CAPY     r_t      Y component of chromaticity data
        LAB_L        r_t      L* component of Lab data
        LAB_A        r_t      a* component of Lab data
        LAB_B        r_t      b* component of Lab data
        LAB_C        r_t      C*ab component of Lab data
        LAB_H        r_t      hab component of Lab data
        LAB_DE       r_t      CIA delta E
        STDEV_X      r_t      Standard deviation of X (tristimulous data)
        STDEV_Y      r_t      Standard deviation of Y (tristimulous data)
        STDEV_Z      r_t      Standard deviation of Z (tristimulous data)
        STDEV_L      r_t      Standard deviation of L*
        STDEV_A      r_t      Standard deviation of a*
        STDEV_B      r_t      Standard deviation of b*
        STDEV_DE     r_t      Standard deviation of CIE delta E

    Add a set of data:
        add_set(cgats *p, int table, ...)
    The data should be supplied as a varargs list in the appropropriate
    data format [char*, double or int].
	Returns 0 normally, -1 errc & err if parameter error,
	-2 errc & err if system error.

    Add a set of data from union array:
		add_setarr(cgats *p, int table, cgats_set_elem *args);
    The data should be supplied as an array of cgats_set_elem unions.
	Returns 0 normally, -1 errc & err if parameter error,
	-2 errc & err if system error.

    Write the data out to a file.
        write_name(cgats *p, char *fname);
    The method will return non-zero on an error, with an error
    description in the err location of the structure.


    A non-standard destination of data can be read by passing an
    object that inherits from the cgatsFile class defined in
    parse.h to the write(cgats *p, cgatsFile *fp) method.

    To read in a data file, the cgats structure should be created
    as usual. The read method can then be called to read in the file:
        read_name(cgats *p, char *fname)
    Returns 0 normally, and -ve on an error, with an error
    description in the err location of the structure,
	and errc set with the return code.

    A non-standard source of data can be read by passing an
    object that inherits from the cgatsFile class defined in
    parse.h to the read(cgats *p, cgatsFile *fp) method.

	The reader will deal automaticaly with carry over of keywords
	and/or field definitions from one table to another, making each
	table appear independent once read.

	The data is accessed by refering to the following read-only
	structure entries:

    The number of tables will be in p->ntables
    
    The number of keywords will be in p->t[table_number].nkwords
    The number of fields will be in p->t[table_number].nfields
    The number of sets will be in p->t[table_number].nsets

	Tables, keywords, fields and sets index from 0.

    The keywords will be in
        p->t[table_number].ksym[keyword_index]

    The keywords character string value be in
        p->t[table_number].kdata[keyword_index]

    The field format identifiers of each field will be in
        p->t[table_number].fsym[field_index]

    The data type of each field will be in
        p->t[table_number].ftype[field_index]

    A void pointer to the data of each field of each set will be in
        p->t[table_number].fdata[set_index][field_index]
	Cast the void pointet according to its type to retrieve the data.
	Alternatively the
	p->get_setarr(struct _cgats *p, int table, int set_index, cgats_set_elem *ary)
	method can be used to fill in a suitable sized cgats_set_elem array with
	the value of all the fields at a particular index. Any character string
	type will be a pointer to the data in p->t[table_number].fdata[set_index][field_index]. 

    To find the index to a particular keyword, use:
        find_kword(cgats *p, int table, char *ksym)
    -1 will be returned if no match is found.
    -2 will be returned, p->errc & p->err will be set if table is out of range.

    To find the index to a particular field, use:
        find_field(cgats *p, int table, char *fsym);
    -1 will be returned if no match is found.
    -2 will be returned, p->errc & p->err will be set if table is out of range.

	Rather than checking the error return codes from every method,
    the first error is "sticky", and recorded in the object.
	This can be checked after a series of operations by calling
	the error(cgats *p, char **mes) method, which will return the
	error code, and (optionaly) the error message.

    Once operations are finished, the object can be deleted by calling
    the delete method:
        del(cgats *p)

Graeme Gill.

---------------------------------------------------------------
