Tables Under Dervish: C API

Procedures for creating, accessing, and manipulating Dervish Tables are provided:

  • shTblColCreate
  • shTblFldAdd
  • shTblFldLoc
  • shTblFldHeapAlloc
  • shTblFldHeapFree
  • shTblTBLFLDlink
  • shTblTBLFLDclr
  • shTblTBLFLDsetWithAscii
  • shTblTBLFLDsetWithDouble
  • shTblTBLFLDsetWithInt
  • shTblcolNew
  • shTblcolDel
  • shTblfldNew
  • shTblfldDel
  • Users should be careful to understand the differences in nomencalture between Dervish and FITS.

    shTblColCreate

    _______________________________________________________________________________ NAME shTblColCreate - Create a skeleton TBLCOL Table SYNOPSIS (C Syntax) #include "shCTbl.h" RET_CODE shTblColCreate ( int rowCnt, /* IN: Number of rows in Table */ int fldCnt, /* IN: Number of fields in Table */ int tblFldPres, /* IN: Boolean: TBLFLD too? */ TBLCOL **tblCol /* OUT: Pointer to Table descriptor */ ) RETURN VALUES SH_SUCCESS Success. The skeleton TBLCOL Table was created. SH_INVARG Failure. The row or field count was less than zero (0) or the tblCol argument was not passed. SH_MALLOC_ERR Failure. Space for the TBLCOL or its associated struc- tures could not be allocated. _______________________________________________________________________________ DESCRIPTION

    A skeleton of a Table with the specified number of rows and fields is created. All necessary data structures are allocated and filled appropriately. Zero (0) rows (rowCnt) is valid, indicating an empty Table with fields (no data within it). It's also possible to have zero (0) fields (fldCnt), where shTblFldAdd can be used to add fields later. The TBLCOL structure heads the CHAINS of ARRAYs

    For each ARRAY (one per field), the following fields are also initialized:

    Additionally, each field (ARRAY) can have a TBLFLD allocated (if the tblFldPres argument is set to be non-zero). The TBLFLD is initialized to indicate it contains no additional information.

    The Table can then be filled with additional per-field information and data.

    shTblFldAdd

    _______________________________________________________________________________ NAME shTblFldAdd - Add a field to a TBLCOL Table (at the end) SYNOPSIS (C Syntax) #include "shCArray.h" #include "shCTbl.h" RET_CODE shTblFldAdd ( TBLCOL *tblCol, /* INOUT: Table descriptor */ int tblFldPres, /* IN: Boolean: TBLFLD too? */ ARRAY **array, /* OUT: ARRAY field descriptor */ TBLFLD **tblFld, /* OUT: TBLFLD field descriptor */ int *tblFldIdx /* OUT: Field index (0-indexed) */ ) RETURN VALUES SH_SUCCESS Success. The field was added at the end of the extant fields. SH_INVARG Failure. The TBLCOL Table is not valid. SH_MALLOC_ERR Failure. Space for the field or its associated struc- tures could not be allocated. _______________________________________________________________________________ DESCRIPTION

    Add a new field to an existing Table. The added field will be the last field in the Table. shTblFldAdd initializes the ARRAY allocated for this filed in the same manner as shTblColCreate:

    Space for data within the field is not allocated.

    Additionally, the field (ARRAY) can have a TBLFLD allocated (if the tblFldPres argument is set to be non-zero). The TBLFLD is initialized to indicate it contains no additional information.

    The field can then be filled with additional per-field information and data.

    array, tblFld, and tblFldIdx are optional arguments. If a null address is passed, no value is returned.

    shTblFldLoc

    _______________________________________________________________________________ NAME shTblFldLoc - Locate a field in a TBLCOL Table SYNOPSIS (C Syntax) #include "shCArray.h" #include "shCTbl.h" RET_CODE shTblFldLoc ( TBLCOL *tblCol, /* IN: Table descriptor */ int tblFldWanted, /* IN: Field index (0-indexed) */ char *tblFldName, /* IN: Field name */ int tblFldNamePos, /* IN: Field name pos (0-indexed)*/ SHCASESENSITIVITY tblFldNameCase, /* IN: Case sensitive cmp? */ ARRAY **array, /* OUT: ARRAY field descriptor */ TBLFLD **tblFld, /* OUT: TBLFLD field descriptor */ int *tblFldIdx /* OUT: Field index (0-indexed) */ ) RETURN VALUES SH_SUCCESS Success. The field was located. SH_MISARG Failure. Neither the field position, tblFldWanted, or field name, tblFldName, was passed. SH_CONFLICT_ARG Failure. Both tblFldWanted and tblFldName were passed. No field was search for. SH_NOEXIST Failure. The specified field does not exist. _______________________________________________________________________________ DESCRIPTION

    Locate a Table field. Either the field position (0-indexed) or the field name can be specified as the search criteria. Field names are contained in TBLFLD's TTYPE member (which is only valid if shTypeTTYPE is set in TBLFLD's Tpres member).

    tblFldWanted and tblFldName must be passed in a manner which leaves no ambiguity as to which search criteria will be used. To search for a field by position, tblFldWanted should specify the position (0-indexed) and tblFldName must be a zero pointer (not just a pointer to an empty string).

    To search for a field by name, tblFldName should point to a character string and tblFldWanted should be set to a negative number. The tblFldNamePos'th field (0-indexed) whose valid TTYPE matches tblFldName will be returned. Therefore, if more than one field has the same TTYPE name, each can be located with this search criteria. If a field does not have a TTYPE name associated with it (either the field does not have a TBLFLD associated with it, or the TTYPE member is not used), it is considered a mismatch (even if the tblFldName is an empty string). The case sensitivity of the string comparisions is controlled by tblFldNameCase (either SH_CASE_SENSITIVE or SH_CASE_INSENSITIVE).

    If the field is located, the ARRAY address and field position are returned. If the field has a TBLFLD associated with it, that address is also returned.

    array, tblFld, and tblFldIdx are optional arguments. If a null address is passed, no value is returned.

    shTblFldHeapAlloc

    _______________________________________________________________________________ NAME shTblFldHeapAlloc - Allocate heap area for a Table field SYNOPSIS (C Syntax) #include "shCTbl.h" RET_CODE *shTblFldHeapAlloc ( ARRAY *array, /* INOUT: Array to alloc space for */ char *schemaName /* IN: Object schema name */ long int extraCnt, /* IN: Additional objs to alloc */ unsigned char **extra /* OUT: Where extra space starts */ ) RETURN VALUES SH_SUCCESS Success. Space for the heap data area was allocated. SH_NOT_SUPPORTED Failure. The object schema name is unknown. The ARRAY is not 1-dimensional or the data is indirect (nStar is non-zero). No heap space was allocated. SH_INVOBJ Failure. The ARRAY info member does not point to a TBLFLD and/or the ARRAY does not contain heap descrip- tors (TBLHEAPDSC object schemas). SH_ALREXIST Failure. Heap space is already allocated for the TBLFLD. SH_MALLOC_ERR Failure. Space could not be allocated for the heap. _______________________________________________________________________________ DESCRIPTION

    Space for the heap space to be associated with an ARRAY's TBLFLD is allocated. The amount of space required is based on the TBLHEAPDSC heap descriptors in the ARRAY data area and the object schema type that the heap area will contain.

    The ARRAY must describe heap data, that is, it's data type (data.schemaType) must be TBLHEAPDSC. The number of ARRAY dimensions (dimCnt) must be 1 and the amount of data indirection must be zero (0). The heap descriptors (TBLHEAPDSC) in the ARRAY data area must be filled prior to calling shTblFldHeapAlloc:

    The object schema which will fill the heap must be a known type. If the heap data is to be written to a FITS Binary Table, other restrictions apply. Additionally, a schemaName of `UNKNOWN' is permitted. In that case, all operations are performed as if the heap data type were unsigned bytes.

    Some peculiar behaviour to be aware of:

    The space allocated is based not only on the object schema count from the heap descriptors, but also on the alignment space needed between data elements. Space is allocated such that each element is aligned `naturally' for the platform on which Dervish is running.

    After the space is allocated, any heap descriptors that contributed to the heap space needs have their pointers filled to the appropriate areas in the heap.

    extra is an optional argument. If a null address is passed, no value is returned.

    shTblFldHeapFree

    _______________________________________________________________________________ NAME shTblFldHeapFree - Free heap data area for a Table field SYNOPSIS (C Syntax) #include "shCTbl.h" RET_CODE *shTblFldHeapFree ( ARRAY *array /* INOUT: Array to deallocate from */ ) RETURN VALUES SH_SUCCESS Success. Space from the ARRAY data area was freed. SH_INVOBJ Failure. The ARRAY does not have an associated TBLFLD. _______________________________________________________________________________ DESCRIPTION

    The heap space used by the TBLFLD associated with the passed ARRAY is freed. For safety, this heap area should have been allocated by shTblFldHeapAlloc.

    Any memory pointed to by the heap data (some object schemas may do this) is not freed. The user must insure that it is not lost inadvertently (memory leaks) by the freeing of the TBLFLD heap area. Also, any heap descriptors (TBLHEAPDSC) in the ARRAY data area pointing to the TBLFLD heap are not invalidated. Again, the user must insure that these pointers are handled appropriately so heap accesses through dangling pointers are not made.

    shTblTBLFLDlink

    _______________________________________________________________________________ NAME shTblTBLFLDlink - Allocate and link a TBLFLD to a field SYNOPSIS (C Syntax) #include "shCTbl.h" RET_CODE *shTblTBLFLDlink ( ARRAY *array, /* INOUT: Array to link TBLFLD to */ TBLFLD **tblFld /* OUT: Resulting TBLFLD */ ) RETURN VALUES SH_SUCCESS Success. The TBLFLD was allocated (or already exists) and linked to the field (ARRAY). SH_ALREXIST Failure. The field (ARRAY) already has a different informative structure (not a TBLFLD) hung off of it. SH_MALLOC_ERR Failure. Space could not be allocated for the TBLFLD. SH_INVOBJ Failure. The ARRAY object is not valid. _______________________________________________________________________________ DESCRIPTION

    If the field description, provided through the ARRAY structure, does not have a TBLFLD structure associated with it, one is allocated and linked off the ARRAY. The TBLFLD is properly initialized to contain no additional information. If a TBLFLD structure already exists, shTblTBLFLDlink returns successfully, without reinitializing the TBLFLD. But, if the ARRAY has a different information structure hung off of it (through its info member), shTblTBLFLDlink fails.

    tblFld is an optional argument. If a null address is passed, no value is returned.

    shTblTBLFLDclr

    _______________________________________________________________________________ NAME shTblTBLFLDclr - Clear a TBLFLD member SYNOPSIS (C Syntax) #include "shCTbl.h" RET_CODE *shTblTBLFLDclr ( ARRAY *array, /* INOUT: Array to link TBLFLD to */ TBLFLD_KEYWORDS tblKeyFld, /* IN: TBLFLD member to clear */ TBLFLD **tblFld /* OUT: Resulting TBLFLD */ ) RETURN VALUES SH_SUCCESS Success. The TBLFLD member was cleared. SH_INVARG Failure. The TBLFLD member indicator is invalid (does not exist or its value cannot be cleared). SH_ALREXIST Failure. The field (ARRAY) has a different informative structure (not a TBLFLD) hung off of itself. SH_MALLOC_ERR Failure. Space for hte TBLFLD could not be allocated. SH_INVOBJ Failure. The ARRAY object is not valid. _______________________________________________________________________________ DESCRIPTION

    Clear the specified TBLFLD member. This makes the TBLFLD not present (by clearing tblKeyFld in the TBLFLD's Tpres member). Any previous value is destroyed (character strings are set to null strings and numeric values are set to zero). tblKeyFld can specify the following TBLFLD members:

  • SH_TBL_TTYPE
  • SH_TBL_TUNIT
  • SH_TBL_TNULLSTR
  • SH_TBL_TNULLINT
  • SH_TBL_TDISP
  • SH_TBL_TSCAL
  • SH_TBL_TZERO
  • If the field, respresented by the ARRAY structure (array parameter), does not have an associated TBLFLD, a TBLFLD is allocated first.

    tblFld is an optional argument. If a null address is passed, no value is returned.

    shTblTBLFLDsetWithAscii, shTblTBLFLDsetWithDouble, shTblTBLFLDsetWithInt

    _______________________________________________________________________________ NAME shTblTBLFLDsetWithAscii - Set TBLFLD member value with character string shTblTBLFLDsetWithDouble - Set TBLFLD member value with a double shTblTBLFLDsetWithInt - Set TBLFLD member value with a signed integer SYNOPSIS (C Syntax) #include "shCTbl.h" RET_CODE *shTblTBLFLDsetWithAscii ( ARRAY *array, /* INOUT: Array to link TBLFLD to */ TBLFLD_KEYWORDS tblKeyFld, /* IN: TBLFLD member to clear */ char *tblKeyVal, /* IN: TBLFLD member value */ TBLFLD **tblFld /* OUT: Resulting TBLFLD */ ) RET_CODE *shTblTBLFLDsetWithDouble ( ARRAY *array, /* INOUT: Array to link TBLFLD to */ TBLFLD_KEYWORDS tblKeyFld, /* IN: TBLFLD member to clear */ double tblKeyVal, /* IN: TBLFLD member value */ TBLFLD **tblFld /* OUT: Resulting TBLFLD */ ) RET_CODE *shTblTBLFLDsetWithInt ( ARRAY *array, /* INOUT: Array to link TBLFLD to */ TBLFLD_KEYWORDS tblKeyFld, /* IN: TBLFLD member to clear */ int tblKeyVal, /* IN: TBLFLD member value */ TBLFLD **tblFld /* OUT: Resulting TBLFLD */ ) RETURN VALUES SH_SUCCESS Success. The TBLFLD member was cleared. SH_TRUNC Success. The ASCII character string was too long and therefore truncated. SH_INVARG Failure. The TBLFLD member indicator is invalid (does not exist or does not accept ASCII/double/signed inte- ger value). SH_ALREXIST Failure. The field (ARRAY) has a different informative structure (not a TBLFLD) hung off of itself. SH_MALLOC_ERR Failure. Space for hte TBLFLD could not be allocated. SH_INVOBJ Failure. The ARRAY object is not valid. _______________________________________________________________________________ DESCRIPTION

    Set the specified TBLFLD member. This makes the TBLFLD present (by setting tblKeyFld in the TBLFLD's Tpres member). Any previous value is destroyed.

    shTblTBLFLDsetWithAscii can set these TBLFLD members (through tblKeyFld):

  • SH_TBL_TTYPE
  • SH_TBL_TUNIT
  • SH_TBL_TNULLSTR
  • SH_TBL_TDISP
  • shTblTBLFLDsetWithDouble can set these TBLFLD members (through tblKeyFld):

  • SH_TBL_TSCAL
  • SH_TBL_TZERO
  • shTblTBLFLDsetWithInt can set these TBLFLD members (through tblKeyFld):

  • SH_TBL_TNULLINT
  • If the field, respresented by the ARRAY structure (array parameter), does not have an associated TBLFLD, a TBLFLD is allocated first.

    tblFld is an optional argument. If a null address is passed, no value is returned.

    shTblcolNew

    _______________________________________________________________________________ NAME shTblcolNew - Construct an instance of a TBLCOL object schema SYNOPSIS (C Syntax) #include "shCTbl.h" TBLCOL *shTblcolNew ( void ) RETURN VALUES TBLCOL * Success. The address of the TBLCOL object. 0 Failure. The constructor function failed. _______________________________________________________________________________ DESCRIPTION

    shTblcolNew is the constructor function for a TBLCOL object schema. It allocates space for a TBLCOL object and intializes its fields for any empty Table.

    This is the constructor function used by the handle mechanism, such as the Tcl command handleNewFromType.

    shTblcolDel

    _______________________________________________________________________________ NAME shTblcolDel - Destroy an instance of a TBLCOL object schema SYNOPSIS (C Syntax) #include "shCTbl.h" void shTblcolDel ( TBLCOL *tblCol, /* IN: Table descriptor */ ) RETURN VALUES none _______________________________________________________________________________ DESCRIPTION

    shTblcolDel is the destructor function for a TBLCOL object schema. It deallocates space for a TBLCOL object, along with any data structures (objects) that the TBLCOL owns, including heap storage. Heap storage not owned by the TBLCOL's TBLFLDs should be freed prior to deleting the Table, otherwise, that memory may become "lost" (a memory leak).

    This is the destructor function used by the handle mechanism, such as the Tcl command handleDelFromType (handleDel only frees the handle memory and does not call shTblcolDel to free the memory used by the Table).

    shTblfldNew

    _______________________________________________________________________________ NAME shTblfldNew - Construct an instance of a TBLFLD object schema SYNOPSIS (C Syntax) #include "shCTbl.h" TBLFLD *shTblfldNew ( void ) RETURN VALUES TBLFLD * Success. The address of the TBLFLD object. 0 Failure. The constructor function failed. _______________________________________________________________________________ DESCRIPTION

    shTblfldNew is the constructor function for a TBLFLD object schema. It allocates space for a TBLFLD object and intializes its fields for any empty Table field.

    This is the constructor function used by the handle mechanism, such as the Tcl command handleNewFromType.

    shTblfldDel

    _______________________________________________________________________________ NAME shTblfldDel - Destroy an instance of a TBLFLD object schema SYNOPSIS (C Syntax) #include "shCTbl.h" void shTblfldDel ( TBLFLD *tblFld, /* IN: Table field descriptor */ ) RETURN VALUES none _______________________________________________________________________________ DESCRIPTION

    shTblfldDel is the destructor function for a TBLFLD object schema. It deallocates space for a TBLFLD object, along with any data structures (objects) that the TBLFLD owns, such as heap storage. Heap storage not owned by the TBLFLD should be freed prior to deleting the field, otherwise, that memory may become "lost" (a memory leak).

    This is the destructor function used by the handle mechanism, such as the Tcl command handleDelFromType (handleDel only frees the handle memory and does not call shTblfldDel to free the memory used by the TBLFLD).