Autodoc Module

The autodoc module contains functions for reading from and writing to autodoc type files, with named sections and key-value pairs within sections. There is a Fortran wrapper for every function listed here, with the same calling conventions. The only exception is that indices are numbered from 1 instead of 0.

The basic unit of organization in the autodoc file is the section, which starts with a line of the form:
[SectionType = name]
There can be many sections of the same type, i.e., having the same key name for the section, named typeName in the functions below. Each of these would typically have a different value for the name entry, although this is not strictly necessary as no uniqueness is enforced and sections are not looked up by name. All of the sections of the same type are held in an array, referred to as a collection, and they are accessed by their array index. Thus, functions for setting or getting values from a section all refer to the section by its typeName and its index sectInd.

Inside of a section, the autodoc contains a set lines with key-value pairs, of the form:
key = value
In general, the values are stored as strings, but functions below can be used for storing or retrieving the values from strings consisting of 1 to 3 floats or integers. Sections of the same type do not need to have the same set of key-value pairs defined.

Every autodoc structure is initialized with a section for global data stored at the start of the file, before any actual sections are defined. These data are accessed by calls with a typeName of "PreData" and a sectInd of 0.

Header to include: autodoc.h


int AdocRead(const char *filename)
int AdocOpenImageMetadata(const char *filename, int addMdoc, int *montage, int *numSect, int *sectType)
int AdocNew()
int AdocSetCurrent(int index)
void AdocClear(int index)
void AdocDone()
int AdocWrite(const char *filename)
int AdocAppendSection(const char *filename)
int AdocAddSection(const char *typeName, const char *name)
int AdocSetKeyValue(const char *typeName, int sectInd, const char *key, const char *value)
int AdocSetInteger(const char *typeName, int sectInd, const char *key, int ival)
int AdocSetTwoIntegers(const char *typeName, int sectInd, const char *key, int ival1, int ival2)
int AdocSetThreeIntegers(const char *typeName, int sectInd, const char *key, int ival1, int ival2, int ival3)
int AdocSetFloat(const char *typeName, int sectInd, const char *key, float val)
int AdocSetTwoFloats(const char *typeName, int sectInd, const char *key, float val1, float val2)
int AdocSetThreeFloats(const char *typeName, int sectInd, const char *key, float val1, float val2, float val3)
int AdocDeleteKeyValue(const char *typeName, int sectInd, const char *key)
int AdocGetSectionName(const char *typeName, int sectInd, char **string)
int AdocGetNumberOfSections(const char *typeName)
int AdocGetNumberOfKeys(const char *typeName, int sectInd)
int AdocGetString(const char *typeName, int sectInd, const char *key, char **string)
int AdocGetInteger(const char *typeName, int sectInd, const char *key, int *val1)
int AdocGetFloat(const char *typeName, int sectInd, const char *key, float *val1)
int AdocGetTwoIntegers(const char *typeName, int sectInd, const char *key, int *val1, int *val2)
int AdocGetTwoFloats(const char *typeName, int sectInd, const char *key, float *val1, float *val2)
int AdocGetThreeIntegers(const char *typeName, int sectInd, const char *key, int *val1, int *val2, int *val3)
int AdocGetThreeFloats(const char *typeName, int sectInd, const char *key, float *val1, float *val2, float *val3)
int AdocGetIntegerArray(const char *typeName, int sectInd, const char *key, int *array, int *numToGet, int arraySize)
int AdocGetFloatArray(const char *typeName, int sectInd, const char *key, float *array, int *numToGet, int arraySize)

int AdocRead(const char *filename)

Reads an autodoc from the file specified by filename, and returns the index of the new autodoc (numbered from zero) or -1 for an error.

int AdocOpenImageMetadata(const char *filename, int addMdoc, int *montage, int *numSect, int *sectType)

Try to read an image metadata file and determine its properties.  It will look for and try to read the file with name filename if addMdoc is 0, otherwise it will append '.mdoc' to filename.  Returns a non-zero in montage if the file indicates a montage; the number of sections in numSect, and 1 for a metadata autodoc or 2 for an image series autodoc in sectType.  The return value is the index of the autodoc, or -1 for an error opening or reading the file, -2 if the file does not exist, or -3 if it is neither type of metadata file.

int AdocNew()

Creates a new autodoc in the internal array, makes it the current one, and returns its index or -1 for an error.

int AdocSetCurrent(int index)

Makes the autodoc at index be the current autodoc.  The index is numbered from zero.  Returns -1 for an index out of bounds.

void AdocClear(int index)

Deletes all data from the autodoc at index and marks it as unused.

void AdocDone()

Deletes all autodocs and returns the module to its initial state.

int AdocWrite(const char *filename)

Writes the current autodoc to the file specified by filename.  Returns 1 for failure to back up a previous file, and -1 for other errors

int AdocAppendSection(const char *filename)

Appends the last section in the current autodoc to the file specified by filename.  Returns -1 for errors.

int AdocAddSection(const char *typeName, const char *name)

Adds a section of type specified by typeName and name given by name. Returns the index of the new section in the collection of sections of that type, or -1 for error.

int AdocSetKeyValue(const char *typeName, int sectInd, const char *key, const char *value)

Sets a key-value pair to key and value in the section with index sectInd in the collection of sections of type typeName.  The section must already exist.  Replaces an existing value if any.  value may be NULL.  Returns -1 for error.

int AdocSetInteger(const char *typeName, int sectInd, const char *key, int ival)

Sets the value of key to the integer ival in the section with index sectInd in the collection of sections of type typeName.  The section must already exist.  Replaces an existing value if any. Returns -1 for error.

int AdocSetTwoIntegers(const char *typeName, int sectInd, const char *key, int ival1, int ival2)

Like AdocSetInteger, except that the value is set to the two integers ival1 ival2.

int AdocSetThreeIntegers(const char *typeName, int sectInd, const char *key, int ival1, int ival2, int ival3)

Like AdocSetInteger, except that the value is set to the three integers ival1 ival2 ival3.

int AdocSetFloat(const char *typeName, int sectInd, const char *key, float val)

Sets the value of key to the float val in the section with index sectInd in the collection of sections of type typeName.  The section must already exist.  Replaces an existing value if any. Returns -1 for error.

int AdocSetTwoFloats(const char *typeName, int sectInd, const char *key, float val1, float val2)

Like AdocSetFloat, except that the value is set to the two floats val1 val2.

int AdocSetThreeFloats(const char *typeName, int sectInd, const char *key, float val1, float val2, float val3)

Like AdocSetFloat, except that the value is set to the three floats val1 val2 val3.

int AdocDeleteKeyValue(const char *typeName, int sectInd, const char *key)

Deletes the key-value pair matching key in the section with index sectInd in the collection of sections of type typeName.  Clears out both the key and the value.  Returns -1 for error.

int AdocGetSectionName(const char *typeName, int sectInd, char **string)

Gets the name of the section with index sectInd in the collection of sections of type typeName.  Returns the name in string. Returns -1 for errors.

int AdocGetNumberOfSections(const char *typeName)

Returns the number of sections of type typeName.  Returns -1 for errors, and 0 if there are no sections of the given type.

int AdocGetNumberOfKeys(const char *typeName, int sectInd)

Returns the number of key-value pairs in the section with index sectInd in the collection of sections of type typeName.  Returns -1 for errors.

int AdocGetString(const char *typeName, int sectInd, const char *key, char **string)

Gets the value string matching key in the section with index sectInd in the collection of sections of type typeName.  Returns a copy of the value in string; it should be freed with free.  Returns -1 if the key is null, the section does not exist, or for a memory error; returns 1 if the key does not occur in the given section or if the value is null.

int AdocGetInteger(const char *typeName, int sectInd, const char *key, int *val1)

Like AdocGetString, except that it extracts one integer from the value string and returns its value in val1.

int AdocGetFloat(const char *typeName, int sectInd, const char *key, float *val1)

Like AdocGetInteger except that it returns a float

int AdocGetTwoIntegers(const char *typeName, int sectInd, const char *key, int *val1, int *val2)

Like AdocGetString, except that it extracts two integers from the value string and returns their values in val1 and val2.

int AdocGetTwoFloats(const char *typeName, int sectInd, const char *key, float *val1, float *val2)

Like AdocGetTwoIntegers except that it returns floats

int AdocGetThreeIntegers(const char *typeName, int sectInd, const char *key, int *val1, int *val2, int *val3)

Like AdocGetString, except that it extracts three integers from the value string and returns their values in val1, val2, and val3.

int AdocGetThreeFloats(const char *typeName, int sectInd, const char *key, float *val1, float *val2, float *val3)

Like AdocGetThreeIntegers except that it returns floats

int AdocGetIntegerArray(const char *typeName, int sectInd, const char *key, int *array, int *numToGet, int arraySize)

Like AdocGetString, except that it extracts a set of integers from the value string and returns their values in array, whose size is given in arraySize.  Set numToGet to the number of values to get, or 0 to get all the values; in the latter case numToGet is returned with the number of values retrieved.  Returns -1 for errors in parsing, too few values on the line, or not enough space in the array, as well as for failures in getting the value string.

int AdocGetFloatArray(const char *typeName, int sectInd, const char *key, float *array, int *numToGet, int arraySize)

Like AdocGetIntegerArray except that it returns floats