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.
_______________________________________________________________________________
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:
-
array->dimCnt
is set
to one (1).
-
array->dim[0]
is set
to the number of rows (tblCol->rowCnt
).
-
array->nStar
is set
to zero (0) to indicate that the ARRAY data area will
contain the data (rather than pointers to it).
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.
_______________________________________________________________________________
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:
-
array->dimCnt
is set
to one (1).
-
array->dim[0]
is set
to the number of rows (tblCol->rowCnt
).
-
array->nStar
is set
to zero (0) to indicate that the ARRAY data area will
contain the data (rather than pointers to it).
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.
_______________________________________________________________________________
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.
_______________________________________________________________________________
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:
- If the heap pointer (TBLHEAPDSC
ptr
member)
is non-zero, the heap descriptor is ignored (as it already points to
existing data outside the TBLFLD heap area).
- If the heap count (TBLHEAPDSC
cnt
member)
is zero or negative, the heap descriptor is ignored.
- All remaining heap descriptors are counted towards the space needed
for the heap area.
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:
- If the ARRAY's TBLFLD heap area already has
space allocated to it, this operation is aborted.
- If the ARRAY does not have a TBLFLD
associated with it (and it does not have any other optional information
associated with it through its
info
member), a
TBLFLD is associated with the ARRAY.
- If the object schema is not a recognized type (the primitive data
types defined in
shCAlign.h, then
- The size of the object schema is used as the best guess for
the address increment. This should be a perfectly valid
assumption, since sizeof is supposed to (according to
the ANSI C standard) return the size of the object plus any
padding before and after the object.
- The worst case (largest) alignment factor is used.
- The data area is zeroed out.
- Character strings (object schema type of STR) are
allocated as an array of characters, rather than pointers to
strings. Still, the STR data type is used to
distinguish
character strings from byte arrays.
The counts in the heap descriptors must already reflect
the additional
character expected for guaranteed null-termination.
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.
_______________________________________________________________________________
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.
_______________________________________________________________________________
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.
_______________________________________________________________________________
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.
_______________________________________________________________________________
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.
_______________________________________________________________________________
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.
_______________________________________________________________________________
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).
_______________________________________________________________________________
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.
_______________________________________________________________________________
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).