path: root/vendor/voclient/libvotable/Notes

VOTPARSE -- VOTable parser API.  This interface allows a VOTable to read
read or created from a number of calling languages.  XML parsing is done
using a SAX parser on input, when creating new VOTables the API is used
to populate the VOTable structure before writing the final output.

We attempt to implement all aspects of the VOTable v1.2 specification and
remain compatible with earlier versions to the extent possible.



  Public Interface:
  -----------------

             vot = vot_openVOTABLE  (str|fname)
	          vot_closeVOTABLE  (vot)

             res = vot_getRESOURCE  (vot|res)
                tab = vot_getTABLE  (res)
              field = vot_getFIELD  (tab)

                data = vot_getDATA  (tab)

          tdata = vot_getTABLEDATA  (data)		// data elements
                    tr = vot_getTR  (tdata)
                    td = vot_getTD  (tr)
               bin = vot_getBINARY  (data)
                fits = vot_getFITS  (data)

              group = vot_getGROUP  (vot|res|tab|group)
          fldref = vot_getFIELDRef  (group)
          parref = vot_getPARAMRef  (group)


	 desc = vot_getDESCRIPTION  (handle)
	      param = vot_getPARAM  (handle)
	        info = vot_getINFO  (handle)
            stream = vot_getSTREAM  (bin|fits)

               val = vot_getVALUES  (field|param|info)
                  min = vot_getMIN  (val)
                  max = vot_getMAX  (val)
               opt = vot_getOPTION  (val)

                link = vot_getLINK  (res|info|param|field|table)

	       sys = vot_getCOOSYS  (vot)		// backwards compat.


              handle = vot_newNode  (parent, type)
                    vot_attachNode  (parent, handle)
                    vot_deleteNode  (handle)

    Output Routines:

		  vot_writeVOTable  (vot, fd)
		     vot_writeHTML  (vot, fd)
	   vot_writeDelimitedTable  (vot, fd, delim)			 w


    Convenience Functions:

	    str = vot_getTableCell  (tdata, row, col)

	          n = vot_getNRows  (tdata)
	          n = vot_getNCols  (tdata)

            type = vot_getDATAType  (data)

                 str = vot_getAttr  (handle, attr)
                stat = vot_setAttr  (handle, attr, value)

                str = vot_getValue  (handle)
                str = vot_setValue  (handle, value)

               len = vot_getLength  (handle)
             len = vot_getNumberOf  (handle, type)

           handle = vot_findByAttr  (parent, type, attr, value)
        handle[] = vot_findInGroup  (group, TY_FIELD|TY_PARAM)


     Low-level Interface (Private?):

              handle = vot_getNext  (handle)
           handle = vot_getSibling  (handle)
             handle = vot_getChild  (handle)
       handle = vot_getChildOfType  (handle, type)
            handle = vot_getParent  (handle)

                type = vot_valueOf  (handle)


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

Data Structures
---------------


#define TY_VOTABLE       1
#define TY_RESOURCE      2
#define TY_FIELD         3
#define TY_PARAM         4
#define TY_INFO          5
#define TY_ROW           6
#define TY_DATA          7
#define TY_VALUES        8
#define TY_STREAM        9
#define TY_LINK         10
#define TY_FIELDREF     11
#define TY_PARAMREF     12
#define TY_OPTION       13
#define TY_MIN          14
#define TY_MAX          15
#define TY_FITS         16
#define TY_TABLE        17
#define TY_GROUP        18
#define TY_COOSYS       19


#define	MAX_ATTRS	11
#define	SZ_ATTR_NAME	16
#define SZ_ATTR_VALUE	64


typedef unsigned int 	handle_t;


typedef struct {
    char    name[SZ_ATTR_NAME];		/* attribute name	*/
    char    value[SZ_ATTR_VALUE];	/* attribute value	*/

} Attr, *AttrP;


typedef struct {
    char    type;			/* node type		*/

    void    *next;			/* sibling node		*/
    void    *child;			/* child nodes		*/
    void    *child_last;		/* last child node	*/
    void    *parent;			/* parent node		*/

    char    *data;			/* value string		*/

    Attr    attr[MAX_ATTRS];		/* attribute array	*/
    int	    nattrs;			/* number of attributes	*/

}  Node, *NodeP;


    - 	Need to keep track of last child so we can easily append new tags
    - 	The 'data' string is any text in the xml element, e.g. given

		<TD>yada yada yada</TD>

      	the 'data' string is then 'yada yada yada'
    - 	structs should be calloc'd to initialize to NULL



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

Notes:
------

  -	The 'handle' is an opaque reference to the node that is meant to
	be language-neutral.  In reality it is just the pointer to the Node
	struct cast as an integer.  Note that on 64-bit platforms, bindings 
	will require the handle to be typed as a 'long'value. 

  -     The vot_openVOTable() is used both for reading and writing VOTables.
	The read, the argument may a string which is a filename to be read or
	a literal string assumed to be the VOTable document itself.  If
	passed a NULL pointer, a new document structure will be created and
	we assume we'll write it out later.

  -	The various vot_get<Tag>() functions in reality only return the single
	handle of the specified type, or a NULL if not found.  This node 
	is required to be a child of the argument (parent) node.  

	    vot_getFIELD (handle_t parent)
	    {
	        Node *ip = (handle_t) NULL;:
	        Node *p = (Node *) parent;
	        Node *c = p->child;
	        int ptype = p->type;

		if (ptype != TY_TABLE)		// check for valid parent
		    fprintf (stderr, "Invalid node for FIELDs\n");

	        for (ip=c; ip; ip = ip->next)
		    if (ip->type == TY_FIELD)
		        break;

	        return ((handle_t) ip);
	    }


  -	A call to vot_getNext() returns the next sibling of the same type as 
	the arg.  In contrast, vot_getSibling() returns the next sibling node
	regardless of type.
	    
	    vot_getNext (handle_t tag)
	    {
	        Node *ip:
	        Node *np = (Node *) tag;
	        int type = p->type;

	        for (ip=np->next; ip; ip = ip->next)
		    if (ip->type == np->type)
		        return ((handle_t) ip);

	        return ((handle_t) NULL);
	    }

	    vot_getSibling (handle_t tag)
	    {
	        Node *np = (Node *) tag;

	        return ((handle_t) np->next);
	    }

  -	vot_newNode() creates an empty node structure, other calls are used
	to populate the attributes, values, or child nodes.   OTOH, methods
 	like vot_attachNode() / vot_deleteNode() use handles that can refer
	to sub-trees.  This makes it easy to refer to e.g. an entire RESOURCE
	and then attach it to a new document or delete entirely.  The 
	methods that care of adusting the child/next pointers.

	vot_newNode  (handle_t parent, int type)
	{
	    Node *np = (Node *) calloc (1, sizeof (Node));
	    np->type = type;
	    return ((handle_t) np);;
	}
                    
	vot_attachNode  (handle_t parent, handle_t node)
	{
	    Node *p = (Node *) parent, 
		 *n = (Node *) node,
		 *last = p->child_last;

	    if (p->child)
	        last->next = n;			// append existing children
	    else
		p->child = n;			// make an only child
	    p->child_last = n			// update parent
	}
                    
	vot_deleteNode  (handle_t node)
	{
	    Node *n = (Node *) node,
		 *p = n->parent,
		 *last = p->child_last,
		 *prev = (Node *) NULL;

	    if (p->child == n) {		// node is first child
	        p->child = n->next;

	    } else {
	        // Find the previous sibling node
		for (prev=p->child; prev->next != n; prev=prev->next)
		    ;

		prev->next = n->next;
		if (p->child_last == n)		//update parent
		    p->child_last = prev;
	    }

	    vot_freeNode (n);			// free the node sub-tree
	}

	
	The vot_freeNode() method would need to walk the tree in a
	depth-first manner to free the Node strucutres.  The vot_closeVOTable()
	then is simply a call to this on the root node



  -	Fortran bindings should use the subroutine model to avoid having to
	declare numerous functions. E.g.

	The C method

              field = vot_getFIELD  (tab)

	is used in Fortran as

		call getFIELD (tab, field)

	Implementation of the wrapper is then simply

	    void getFIELD (handle_t parent, handle_t *field)
	    {
                 *field = vot_getFIELD (parent);
	    }


	Methods that pass strings need to take into account the hidden length
	parameter used in fortran.  E.g.

	The C method
                valueStr = vot_getAttr (handle, attr)

	is used in Fortran as

		call getAttr (handle, attr, valueStr)

	However, the implementation is
		
	    void getAttr (handle_t parent, char *a, char *v, int alen, int vlen)
	    {
                 *v = vot_getAttr (parent, a);
	    }

	The 'alen' and 'vlen' args are added by the Fortran compiler to pass
	in the length of the string.  In some cases we may also want to pass
	in the max length of a result string so we don't overflow a buffer,
	or else return the length of the string we found.  Since Fortran is
	call-by-address in either of these cases the length becomes a pointer
	declaration.



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


PseudoCode:
-----------


1) Read a VOTable, processing each RESOURCE in the file.  Note we don't
   handle *nested* RESOURCEs here.


    vot = vot_openVOTable (fname)

    // loop over RESOURCES
    res = vot_getRESOURCE (vot, i);
    printf ("Table has toplevel %d RESOURCE elements\n", 
	vot_getLength (res));

    while ( res ) { 

	tab = vot_getTABLE (res)

	// Print column info
	for (field=vot_getFIELD(tab); field; field=vot_getNext(field)) {
	    strcpy (col[i].name, vot_getAttr (field, "name") 
	    strcpy (col[i].ucd,  vot_getAttr (field, "ucd") 
	}

	//  Get the data element
	data = vot_getDATA (tab)

	switch (vot_getDataType (data))
	case TY_TABLEDATA:
	    //  Get data stored as a TABLEDATA xml block
            tdata = vot_getTABLEDATA (data) 

	    if (use_direct) {
	        // Get the table data cells by direct index
		tr = vot_getTR(tdata)
		nrows = vot_getLength (tr)
		ncols = vot_getLength (vot_getTD(tr))
	        for (l=0; l < nrows ; l++) {
	            for (m=0; m < ncols; m++) {
	    	        str = vot_getTableCell (tdata, l, m)

	    } else {
	        // Get the table data cells by looping over rows/cols
	        for (tr=vot_getTR (tdata); tr; tr=vot_getNext(tr))
	            for (td=vot_getTD(tr); td; td=vot_getNext(td))
			str = vot_getValue (td);
	    }
	    break

	case TY_BINARY:
	    // Get data stored as inline binary.  If the encoding of
	    // the stream is base64 read the sequence of bytes and decode.
            bin = vot_getBINARY (data) 
	    stream = vot_getSTREAM (bin)
	    if (strcmp ("base64", vot_getAttr(stream, "encoding") == 0)
	        str = vot_getValue (stream)
	    break

	case TY_FITS:
	    // Read FITS data.  Assumes a particular extension of an 
	    // MEF is available for download at the given href.
            fits = vot_getFITS (data) 
	    extnum = vot_getAttr (fits, "extnum")	// get extension no.

	    stream = vot_getSTREAM (fits)
	    href = vot_getAttr (stream, "href")

	    ....download the FITS file ....

	    break
	default:	
	    error (0, "Invalid table DATA type.")
	}

	res = vot_getNext(res)				// get next resource
    }

    vot_closeVOTable (vot)




2)  Print all the PARAM elements in a table with a single RESOURCE

    a)  Use the low-level interface dealing with document structure

        res = vot_getRESOURCE (vot)
        for (p = vot_getChild (res); p; p = vot_getSibling (p)) {
	    if (vot_typeOf (p) == TY_PARAM)
	        printf ("PARAM  name=%s  value=%s\n", 
	            vot_getAttr(p, "name"), vot_getAttr(p, "value"))
        }

    b)  Use the common hi-level interface

        res = vot_getRESOURCE (vot)
        for (p = vot_getPARAM (res); p; p = vot_getNext (p)) {
	    printf ("PARAM  name=%s  value=%s\n", 
	        vot_getAttr(p, "name"), vot_getAttr(p, "value"))
        }




3)  Check a VOTable to see if it is an error return

    a)  SCS-only (Preferred) Method - INFO as a child of VOTABLE

        vot = vot_openVOTable (fname)
	if ((info = vot_getINFO (vot)) {
	    if (strcsecmp (vot_getAttr (info, "name"), "error") == 0)
		return ((errMsg = vot_getAttr (info, "value")))
 	} else
	    return ("file is okay")


    b)  Alternate Method - PARAM as a child of RESOURCE "allowed" for SCS,
	required for other DAL services.  For SCS, the name/id are different,
	later DAL services use 'QUERY_STATUS'.

        vot = vot_openVOTable (fname)
	res = vot_getRESOURCE (vot)
	param = vot_getPARAM (res)
	info = vot_getINFO (res)

	if (strcasecmp(vot_getAttr (param, "name"), "error") == 0) {
	    // SCS alternate method where PARAM defines value the error string
	    return (vot_getAttr (param, "value"))
	    
	} else if (strcasecmp(vot_getAttr(info,"name"),"QUERY_STATUS") == 0) {
	    // All-other DAL methods where and INFO of the RESOURCE defines
	    // a QUERY_STATUS of the result.
	    if ( ((val = vot_getAttr (info, "value")), "OK") == 0)
		return (NULL);				// no error
	    else
		return (vot_getValue (info))		// return error message
	}


	NOTES:  We should make this an interface convenience.  A real
	    error will be a minimal VOTable error return we can parse, but
	    DAL2 services like TAP may experience overflow where we don't see
	    an error result until a max-records/timeout is reached and the
	    error INFO is at the end of the output.  In this last case the
	    error INFO isn't seen until after table data.  To be real, we
	    need to then search all INFO children of the RESOURCE rather than
	    just the first one shown in the above.



4)  Create a new VOTable from computed values

	vot = vot_openVOTable (NULL)			// initialize

	res = vot_newNode (vot, TY_RESOURCE)		// create empty resource
	vot_setAttr (res, "id", "newTable")		// set table name


	desc = vot_newNode (vot, TY_DESCRIPTION)	// set description
	vot_setValue (desc, "This is a test description")

	tab = vot_newNode (res, TY_TABLE)		// create a TABLE
	for (i=0; i < 10; i++) {
	    f = vot_newNode (tab, TY_FIELD)
	    sprintf (colname, "col%d", i)
	    vot_setAttr (f, "name", colname)
	    vot_setAttr (f, "id", colname)
		:		:
	}

	data = vot_newNode (tab, TY_DATA)		// create a DATA
	tdata = vot_newNode (data, TY_TABLEDATA)	// create a TABLEDATA

	for (i=0; i < nrows; i++) {
	    tr = vot_newNode (tdata, TY_TR)		// create a row
	    for (j=0; j < ncols; j++) {
	        td = vot_newNode (tr, TY_TD)		// create a col
	        vot_setValue (td, (char *)data[i,j])
	    }
	}

	info = vot_newNode (tab, TY_INFO)		// create a DATA
	vot_setAttr (info, "id", "STATUS")
	vot_setAttr (info, "value", "OK")


	vot_writeVOTable (vot, stdout)			// write it out



4-A)  Create a new VOTable from computed values (Alternate Method)

	vot = vot_openVOTable (NULL)			// initialize

	res = vot_newRESOURCE (vot)			// create empty resource
	vot_setAttr (res, "id", "newTable")		// set table name

							// set description
	desc = vot_newDESCRIPTION (vot, "This is a test description")

	tab = vot_newTABLE (res)			// create a TABLE
	for (i=0; i < 10; i++) {
	    f = vot_newFIELD (tab)
	    sprintf (colname, "col%d", i)
	    vot_setAttr (f, "name", colname)
	    vot_setAttr (f, "id", colname)
		:		:
	}

	data = vot_newDATA (tab)			// create a DATA
	tdata = vot_newTABLEDATA (data)			// create a TABLEDATA

	for (i=0; i < nrows; i++) {
	    tr = vot_newTR (tdata)			// create a row
	    for (j=0; j < ncols; j++) {
	        td = vot_newTD (tr)			// create a col
	        vot_setValue (td, (char *)data[i,j])
	    }
	}

	info = vot_newINFO (tab)			// create a DATA
	vot_setAttr (info, "id", "STATUS")
	vot_setAttr (info, "value", "OK")


	vot_writeVOTable (vot, stdout)			// write it out


5)  Concatenate the RESOURCEs from two input table to a new output table

	vot1 = vot_openVOTABLE ("file1.xml")		// open input tables
	vot2 = vot_openVOTABLE ("file2.xml")

	res1 = vot_getRESOURCE (vot1)			// get resources
	res2 = vot_getRESOURCE (vot2)

	vot3 = vot_openVOTABLE (NULL)			// open output table

	vot_attachNode (vot3, vot1)			// add resources
	vot_attachNode (vot3, vot2)

	vot_writeVOTable (vot2, stdout)			// write it out

	vot_closeVOTABLE (vot1)				// clean up
	vot_closeVOTABLE (vot2)
	vot_closeVOTABLE (vot3)


6)  Extract all the values in the columns specified by a GROUP

        vot = vot_openVOTable (fname)
	res = vot_getRESOURCE (vot)
	tab = vot_getTABLE (res)

	// Look for the GROUP by name
	for (group=vot_getGROUP(res); group; group=vot_getNext(group))
	    if (strcasecmp (vot_getAttr(group,"name"), "CoolStuff") == 0)
		break;

	// Gather the column numbers for the FIELDs in the GROUP
	for (fref=vot_getFIELDRef(group); fref; fref=vot_getNext(fref)) {
	    // Get the field references
	    ref = vot_getAttr (fref, "ref")

	    // Find the FIELD with the referenced ID attribute, 
	    field = vot_findByAttr (tab, TY_FIELD, "ID", ref)

	    // Convert to a column number to extract
	    fp = vot_getField (tab)			// start FIELD
	    colnum = -1
	    while (fp && fp != field) {
		colnum++;				// 0-indexed list
		fp = vot_getNext (fp)
	    }

	    cols[numInGroup++] = colnum
	}

	//  Print out the data in selected columns
	data = vot_getDATA (tab)
	tdata = vot_getTABLEDATA (data)
	tr = vot_getTR(tdata)
	nrows = vot_getLength (tr)

	for (i=0; i < nrows ; i++) {
	    for (j=0; j < numInGroup; j++)
	    	printf ("%s  ", vot_getTableCell (tdata, i, cols[j])
	    printf ("\n")
	}