intf

This Source-Navigator, an IDE for C/C++/Fortran/Java/Tcl/PHP/Python and a host of other languages.

objects in process memory remain there, and proto objects without
allocated memory will have process storage created.
.sp
.PP
sdsP = sds_protoize(sdsH);
.sp
.IP
Moves a dataset to the prototype state so that the dataset stucture may be
changed. Attempts to obtain object addresses from sdsP or sdsH are now
invalid. It cannot be assumed that objects whose addresses were found from
the generating sdsH before protisation (yuk) will remain in these locations
after further dataset manipulation. 
.sp
.PP
sdsH = sds_duplicate(sdsH, storeH);
.sp
.IP
Duplicates the dataset sdsH to new storage.
.sp
.PP
sdsH = sds_deep_duplicate(sdsH, storeH);
.sp
.IP
Duplicates the dataset sdsH to new storage, including all 'disjoint'
objects.
.sp
.PP
int call_succeeded = sds_discard_all(sdsH);
.sp
.IP
Discard all system descriptive information about a dataset.
.sp
.PP
int call_succeeded = sds_destroy_all(sdsH);
.sp
.IP
Discard all system descriptive information about a dataset and the
objects in it, having first free'd any Sds-system allocated memory
in the objects.
.sp
.PP
.ce 1
.I Creation of type_descriptor:
.sp
.PP
typeH = sds_make_th(struct typelist *tl);
.sp
.ce 1
.I Creation of storage_descriptor:
.sp
.PP
storeH = sds_make_sh(struct storeage *st);
.sp
.IP
.ce 1
.I Calls to an object:
.sp
.PP
objectH = sds_new_object(th,int number,char *names[]);
.br
int call_succeeded =
   sds_oh_instantiations(objectH, storeH[], char *instatiation_names[]);
.br
int call_succeeded =
   sds_oh_struct_storage(objectH, storeH[], char *name = NULL);
.sp
.PP
oh = sds_copy(storeH, objectI, pointer = NULL);
.sp
.IP
Having open'd the dataset, you may now *copy* some or all of
the objects (including architecture conversion if necessary).
Space will be allocated unless 'pointer' has a non-null value, in
which case data will be loaded starting at the pointer position:
caveat programmer.
.sp
.PP
objectH = sds_ohfromindex(sdsH, objectI);
objectH = sds_ohfromname(sdsH, name);
.sp    
.IP
Find the appropriate object handle from the index or name of an object
within a dataset.
.sp
.PP
objectH = sds_ohlikename(sdsH, part_name,int occurrence);
.sp
.IP
Find the occurence'th instance of an object within a dataset whose name
contains 'part_name' as a substring.
.sp
.PP
void *ohptr = sds_ohptr(objectH);
.sp
.IP
Find the pointer to the data acessed through objectH.
.br
Note: this call will give an
.I SDS_FATAL
error if the objectH was found by querying a proto-dataset: default
behaviour is to print out the error stack and stop.
.sp
.PP
char *ohname = sds_ohname(objectH);
.sp
.IP
Find the name of the data acessed through objectH.
.sp
.PP
int multiplicity = sds_ohmult(objectH);
.sp
.IP
Find the multiplicity of the data acessed through objectH - ie how many of
each element - the array size.
.sp
.PP
int sizeof = sds_ohsizeof(objectH);
.sp
.IP
Find the size in bytes of one element of an object.
The size could be undetermined; sds_error is then set to
SDS_SIZE_UNDETERMINED and the error level set to SDS_WARNING;
the size returned is 0.
.sp
.PP
int sizeof = sds_thsizeof(th);
.sp
.IP
Find the size in bytes of the data structure accessed by the type_handle. 
The size could be undetermined; sds_error is then set to
SDS_SIZE_UNDETERMINED and the error level set to SDS_WARNING;
the size returned is 0.
.sp
.PP
int call_succeeded = sds_ohtstamp(int tstamp);
.sp
.IP
Sets the time stamp of an object.
.sp
.PP
int tstamp = sds_get_ohtstamp(objectH);
.sp
.IP
Returns the time stamp of an object.
.sp
.PP
int call_succeeded = sds_discard(objectH);
.sp
.IP
Discard all system descriptive information about an object.
.sp
.PP
int call_succeeded = sds_destroy(objectH);
.sp
.IP
Free any Sds-system allocated memory in the object, then sds_discard()
all system information.
.sp
.PP
.ce 1
.I Object analysis:
.sp
.PP
int descriptor_handle = sds_desc_handle(objectH);
.sp
.IP
Get a handle to refer to subsequent analysis calls on an object.
.sp
.PP
There are two main types of object analysis: linear and hierarchical.
In each case repeated calls to the analysis routines return information
about the analysed objects. In linear analysis,  a sequence of statements
about the primitive elements that make up the object is made - eg 10
floats, 23 int, 120 char, 10 floats, 23 int, 120 char......
This is effected by sequential calls to
.sp
int level = sds_linear(descH, struct level_description **ld.sp);
.sp
In hierarchical elements, a series of index numbers refering to an array
of descriptor structures is returned from
.sp
int level = sds_hierarch(descH, struct level_description **ld);
.sp
each of which give:
.IP
The start address of the field
.br
Its name
.br
Its type_code
.br
The number of elements in the array (or 1).
.br
Its size in bytes.
.sp
.IP
When no more fields remain for analysis, 0 is returned and the warning SDS_DONE_ANALYSIS is set.
.sp
.PP
int call_succeeded = sds_close_dh(descH);
.sp
.IP
Clean up all system stuff created for an analysis. Use of descH before it
is reallocated with sds_desc_handle() will cause an error; however
sds_close_dh() is called automatically when an analysis sequence is run
completion. Re-closing an already closed descH has no effect.
.sp
.PP
int level = sds_find_level(descH, field_name, struct level_description **ld);
.sp
.IP
Makes calls to sds_hierarch() until a match is made to the field named
field_name.
.sp
.ce 1
.I Creation of record_handle:
.sp
recordH = sds_begin_record(char *name);
.sp
sds_record_entry(recordH, handle, int number, void *ptr, char *name);
.sp
sds_begin_sub_record(rh, name)
.sp
sds_end_sub_record(rh)
.sp
sds_end_and_declare(recordH, sdsH);
.sp
sds_destroy_record_def(recordH, int destroy_object);
.sp
sds_print_record_def(recordH);

.ce 1
.I Error handling.
.sp
.I Level 1
.sp
.PP
void sds_stop_if_error(char *comment);
.sp
.IP
Really crude. If there has been an Sds error, it prints out the error stack
and does exit(1); otherwise it is quiet.
.sp
.PP
int level = sds_push_error(int errcode, int errlevel, char *errstring);
.sp
.IP
Push a new error onto the stack. We assume that errstring is zero
terminated, and check to see if it is NULL. Returns the 'level' of
the error in the stack. Filename and line information is added by the
preprocessor from the defines __LINE__ and __FILE__.
.sp
.PP
  int error_code = sds_last_error();
.sp    
.IP
Returns the last sds_error, which is 0 if no problems found.
.sp
.PP
  int error_code = sds_last_warning();
.sp    
.IP
Returns the last sds_error at SDS_WARNING level, which is 0 if no problems found.
.sp
.PP
  void sds_perror(char *comment);
.sp  
.IP
Print out the top level comment, any filled parts of the error stack,
and the last operating system error if there was one.
.sp
.PP
.sp
.I Level 2:
.sp
.PP
void sds_output_proginfo(int truefalse);
.sp
.IP
Default 0 == Do not print out line and file information.
.sp
.PP
void sds_exit_on_fatal(int truefalse);
.sp
.IP
Default 1 == An SDS_FATAL error causes exit(truefalse & 0xff);
.sp
.PP
void sds_output_errors(int level);
.sp
.IP
Default 0 == Do not output errors as they are registered; this is when
you want to wait for a final catastrophe and then use sds_perror(), or
when you may be able to take corrective action; in most programs
sds_output_errors(SDS_FATAL) will be appropriate.
.sp
.PP
sds_clear_errors();
.sp
.IP
Start with a clean slate.
.sp
.PP
int error_code = sds_pop_error(int errlevel, char *errstring);
.sp
.PP
void printoutprog(int i);
.sp
.IP
Print out program info for the i'th entry on the stack 
.sp
.PP
void printout(int i);
.sp
.IP
Print out the i'th entry on the stack 
.sp
.IP
Currently, error levels are:
.sp
SDS_WARNING
.br
SDS_ERROR
.br
SDS_FATAL
.br