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
ordinarily 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. C programs should use ADOC_GLOBAL_NAME, which is defined as "PreData";
Fortran programs should call
integer*4 AdocGetStandardNames(globalName, zvalueName)
to fetch this string and also the important string ADOC_ZVALUE_NAME, which is
defined as "ZValue". That function returns -1 if a string does not fit into
the supplied character argument.
Comments on lines starting with # can occur anywhere in an autodoc. They will be preserved when it is read in and generally be written out again in front of the same item.
An autodoc can be written as an XML file, and simple enough XML files can be read in and stored in the autodoc structure. When reading from an XML file, the root element can be anything, although the calling program may insist on a particular element name. When writing, the root element will be <autodoc> unless the autodoc was read from an XML file or the name was set with AdocSetXmlRootElement. Each section is written as a top-level child of the root element in this form: <typeName name="value">, although the global section is written as <PreData> without a name. Key-value pairs within a section are all written as children of the top-level child with the form <key>value</key>. Empty values are allowed and written as <key />. Any XML file that conforms to this structure can be read in; namely, each top-level child must have a name attribute except "PreData", and children of those nodes must be simple key-value pairs with no attributes or children. The latter will simply be lost; see AdocXmlReadStatus.
Header to include: autodoc.h
int AdocRead(const char *filename)
int AdocXmlReadStatus(int *sectNotElem, int *sectNoName, int *childNotElem,
int *childAttribs, int *valueNotText, int *multipleChilds)
int AdocOpenImageMetadata(const char *filename, int addMdoc, int *montage,
int *numSect, int *sectType)
int AdocGetImageMetaInfo(int *montage, int *numSect, int *sectType)
int AdocNew()
int AdocGetCurrentIndex()
int AdocSetCurrent(int index)
void AdocClear(int index)
void AdocDone()
int AdocWrite(const char *filename)
void AdocSetWriteAsXML(int asXML)
int AdocGetWriteAsXML()
int AdocGetXmlRootElement(char **string)
int AdocSetXmlRootElement(const char *element)
int AdocAppendSection(const char *filename)
int AdocPrintToString(char *string, int stringSize, int writeAll)
int AdocOrderWriteByValue(const char *typeName)
int AdocAddSection(const char *typeName, const char *name)
int AdocInsertSection(const char *typeName, int sectInd, const char *name)
int AdocDeleteSection(const char *typeName, int sectInd)
int AdocChangeSectionName(const char *typeName, int sectInd, const char *newName)
int AdocLookupSection(const char *typeName, const char *name)
int AdocLookupByNameValue(const char *typeName, int nameValue)
int AdocFindInsertIndex(const char *typeName, int nameValue)
int AdocTransferSection(const char *typeName, int sectInd, int toAdocInd,
const char *newName, int byValue)
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 AdocSetIntegerArray(const char *typeName, int sectInd, const char *key, int *ivals,
int numVals)
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 AdocSetFloatArray(const char *typeName, int sectInd, const char *key, float *vals,
int numVals)
int AdocSetDouble(const char *typeName, int sectInd, const char *key, double val)
int AdocDeleteKeyValue(const char *typeName, int sectInd, const char *key)
int AdocGetNumCollections()
int AdocGetCollectionName(int collInd, char **string)
int AdocGetSectionName(const char *typeName, int sectInd, char **string)
int AdocGetNumberOfSections(const char *typeName)
int AdocGetNumberOfKeys(const char *typeName, int sectInd)
int AdocGetKeyByIndex(const char *typeName, int sectInd, int keyInd, char **key)
int AdocGetValTypeAndSize(const char *typeName, int sectInd, const char *key,
int *valType, int *numTokens)
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 AdocGetDouble(const char *typeName, int sectInd, const char *key, double *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 AdocWriteInteger(FILE *fp, const char *key, int ival)
int AdocWriteTwoIntegers(FILE *fp, const char *key, int ival1, int ival2)
int AdocWriteThreeIntegers(FILE *fp, const char *key, int ival1, int ival2, int ival3)
int AdocWriteIntegerArray(FILE *fp, const char *key, int *ivals, int numVals)
int AdocWriteFloat(FILE *fp, const char *key, float val)
int AdocWriteTwoFloats(FILE *fp, const char *key, float val1, float val2)
int AdocWriteThreeFloats(FILE *fp, const char *key, float val1, float val2, float val3)
int AdocWriteFloatArray(FILE *fp, const char *key, float *vals, int numVals)
int AdocWriteKeyValue(FILE *fp, const char *key, const char *value)
int AdocWriteSectionStart(FILE *fp, const char *key, const char *value)
Reads an autodoc or autodoc-compatible XML file from the file specified by filename, and returns the index of the new autodoc (numbered from zero) or -1 for an error.
Returns whether the last file read in was an XML file, and information about aspects
that could not be encoded as an autodoc if the last file was an XML file. Each value
is the number of occurrences of the problem:
sectNotElem if a top-level child is not an element,
sectNoName if a top-level child does not have a name attribute,
childNotElem if a child of a top-level child is not an element,
childAttribs if a child has attributes,
valueNotText if a child's value is not text,
multipleChilds if a child of a top-level child has multiple children.
If a top-level child has attributes other than "name", these will become
key-value pairs indistinguishable from the ones coming from child nodes, and there is
no indicator that this occurred. The return value is 0 if file was not XML, 1 if it
was and had no problems, or -1 if it was XML and had some of these problems.
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.
Determines whether the current autodoc is a valid image metadata autodoc and returns a non-zero in montage if the file indicates a montage; the number of sections in numSect; and 1 for a metadata autodoc, 2 for an image series autodoc, or 3 for any other autodoc with sections named ZValue (including the autodoc holding attributes for an HDF file). The return value is -3 if it is not one of these types of autodocs.
Finds an unused autodoc in the internal array if one exists or creates a new one if not, makes it the current one, and returns its index or -1 for an error.
Returns the current autodoc index, or -1 if there is none
Makes the autodoc at index be the current autodoc. The index is numbered from zero. Returns -1 for an index out of bounds.
Deletes all data from the autodoc at index and marks it as unused.
Deletes all autodocs and returns the module to its initial state.
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
Sets the current autodoc to be written as XML if asXML is non-zero.
Returns 1 if current autodoc is to be written as XML, 0 if not, -1 for invalid current autodoc
Returns a copy of the root element name into string if a file was loaded from XML; it should be freed with free if it is non-NULL. Returns -1 for no current autodoc or 1 for memory error.
Sets the root element name to element when writing as an XML file; returns -1 for no current autodoc or 1 for memory error.
Appends the last section in the current autodoc to the file specified by filename; or writes the autodoc completely if it is being written as XML. Returns -1 for errors.
Writes either the entire current autodoc, if writeAll is non-zero, or just the last section otherwise, into string, whose size must be specified by stringSize. Returns -1 for all errors, including not fitting into the string.
Sets the next write so that all sections in the collection with name typeName are output after the global section and in order by the value of their names. Returns 1 for memory error.
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.
Inserts a section with name given by name into the collection of sections of type typeName, at the index sectInd. The collection must exist unless sectInd is 0, and sectInd must be less than or equal to the number of sections in that collection. Returns -1 for error.
Deletes the section at index sectInd from the collection of sections of type typeName. Returns -1 for error.
Changes the name of the section at index sectInd from the collection of sections of type typeName to newName. Returns -1 for error.
Looks up a section of type specified by typeName and name given by name. Returns the index of that section in the collection of sections of that type, -1 if there is none, or -2 for error.
Looks up a section of type specified by typeName whose name converts to the integer value nameValue. Returns the index of that section in the collection of sections of that type, -1 if there is none, or -2 for error. When calling from Fortran, be sure to pass the actual value in the file, as this routine will not adjust the passed value down by 1.
Looks in the collection of sections of type typeName, converts their name strings to integers, and returns the index of the first section whose name is greater than nameValue, the number of sections if there is no such section, or -1 for error (including if a section exists whose name converts to nameValue). This returned index can thus be used in a call to AdocInsertSection to maintain the sections in numeric order by name value.
Transfers all key/value pairs from the section of index sectInd in the collection of type typeName of the current autodoc to a section of the same type in the autodoc with index toAdocInd, with a name newName. If byValue is non-zero, the new name is converted to an integer and the section is inserted so as to maintain sections in order. The collection in the receiving autodoc is created if necessary; the new section may already exist or will be created if necessary; existing values with the same key are overwritten. To transfer the global data, set typeName to ADOC_GLOBAL_NAME, sectInd to 0, and byValue to 0; newName is ignored. Returns -1 if the originating section does not exist, -2 for incorrect index for new autodoc or newName NULL (unless typeName is ADOC_GLOBAL_NAME), -3 for failure to add a new section, or -4 for failure to add a key-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.
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.
Like AdocSetInteger, except that the value is set to the two integers ival1 ival2.
Like AdocSetInteger, except that the value is set to the three integers ival1 ival2 ival3.
Like AdocSetInteger, except that the value is set to the array of numVals integers in ivals.
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.
Like AdocSetFloat, except that the value is set to the two floats val1 val2.
Like AdocSetFloat, except that the value is set to the three floats val1 val2 val3.
Like AdocSetFloat, except that the value is set to the array of numVals floats in vals.
Like AdocSetFloat, except that val is a double
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.
Returns the number of collections of sections, excluding the global data collection, or -1 if there is no current autodoc.
Returns the name of the collection with index collInd into string, which is allocated and should be freed with free. The index is numbered from 0 (1 in Fortran) and excludes the global data collection. Returns -1 for errors.
Gets the name of the section with index sectInd in the collection of sections of type typeName. Returns the name in string, which is allocated and should be freed with free. Returns -1 for errors.
Returns the number of sections of type typeName. Returns -1 for errors, and 0 if there are no sections of the given type.
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.
Gets the key at index keyInd in the section with index sectInd in the collection of sections of type typeName. Returns a copy of the key in key, which should be freed with free, or returns NULL if this key has been deleted. Returns -1 for errors.
Returns information about the value string matching key in the section with index sectInd in the collection of sections of type typeName: the value type (ADOC_ONE_INT, etc) in valType and the number of space-separated tokens in the string in numTokens. 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.
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.
Like AdocGetString, except that it extracts one integer from the value string and returns its value in val1.
Like AdocGetInteger except that it returns a float
Like AdocGetInteger except that it returns a double
Like AdocGetString, except that it extracts two integers from the value string and returns their values in val1 and val2.
Like AdocGetTwoIntegers except that it returns floats
Like AdocGetString, except that it extracts three integers from the value string and returns their values in val1, val2, and val3.
Like AdocGetThreeIntegers except that it returns floats
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.
Like AdocGetIntegerArray except that it returns floats
DIRECT WRITING FUNCTIONS
Like AdocWriteInteger, except that the value is set to the two integers ival1 ival2.
Like AdocWriteInteger, except that the value is set to the three integers ival1 ival2 ival3.
Like AdocWriteInteger, except that the value is set to the array of numVals integers in ivals.
Like AdocWriteInteger, except that the value is set to the float val.
Like AdocWriteInteger, except that the value is set to the two floats val1 val2.
Like AdocWriteInteger, except that the value is set to the thre floats val1 val2 val3.
Like AdocWriteInteger, except that the value is set to the array of numVals floats in vals.
Writes one key-value pair directly to the file in fp from the strings in key and value. Returns 1 for write error.
Writes a section header directly to the file in fp from the strings in key and value. Returns 1 for write error.