Initial commit

1 files changed, 105 insertions, 0 deletions

diff --git a/sys/imio/db/README b/sys/imio/db/README
new file mode 100644
index 00000000..cf7f9c1c
--- /dev/null
+++ b/sys/imio/db/README
@@ -0,0 +1,105 @@
+			Image Header Database Interface
+				dct 16-Apr-85
+
+1. Overview
+
+    This directory contains the first version of the image header database
+interface.  In this implementation the image header is a variable length fixed
+format binary structure.  The first, fixed format, part of the image header
+contains the standard fields in binary and is fixed in size.  This is followed
+by the so called "user area", a string buffer containing a sequence of
+variable length, newline delimited FITS format keyword=value header cards.
+When an image is open a large user area is allocated to permit the addition
+of new parameters without filling up the buffer.  When the header is
+subsequently updated on disk only as much disk space is used as is needed to
+store the actual header.
+
+This format header is upwards compatible with the old image header format,
+hence old images and programs do not have to be modified to use the IMIO
+release supporting database accesss.  In the future image headers will be
+maintained under DBIO, but the routines in the image header database interface
+are not exected to change.  The actual disk format of images will of course
+change when we switch over to the  DBIO headers.
+
+
+
+2. Functions
+
+	get,g - get the value of a field
+	put,p - set the value of a field
+	add,a - add a new field to a database
+	  acc - determine if the named field exists
+
+
+3. Procedures
+
+       value = imget[bcsilrdx] (im, "field")
+		        imgstr (im, "field", outstr, maxch)
+	       imput[bcsilrdx] (im, "field", value)
+		        impstr (im, "field", value)
+       	       imadd[bcsilrdx] (im, "field", def_value)
+		        imastr (im, "field", def_value)
+		        imaddf (im, "field", "datatype")
+	          y/n = imaccf (im, "field")
+
+             list = imofnl[su] (im, template)
+                  nch = imgnfn (im, outstr, maxch)
+                        imcfnl (im)
+
+
+
+4. Description
+
+    New parameters will typically be added to the image header with either
+one of the typed procedures IMADD_ or with the lower level procedure IMADDF.
+The former procedures permit the parameter to be created and the value
+initialized all in one call, while the latter only creates the parameter.
+In addition, the typed IMADD_ procedures may be used to update the values
+of existing parameters (it is not considered an error if the parameter
+already exists).  The principal limitation of the typed procedures is that
+they may only be used to add or set parameters of a standard datatype.
+The IMADDF procedure will permit creation of parameters with more descriptive
+datatypes (domains) when the interface is recut upon DBIO.
+
+The value of any parameter may be fetched with one of the IMGET functions.
+The IMACCF function may be used (like ACCESS for a file) to determine
+whether a parameter exists.
+
+The database interface may be used to access any field of the image header,
+including the following standard fields.  Note that the nomenclature has
+been changed slightly to make it more consistent with FITS.  Additional
+standard fields will be defined in the future.
+
+
+	  keyword     type                 description
+
+	i_naxis		i	number of axes (dimensionality)
+	i_naxis[1-7]	l	length of an axis ("i_naxis1", etc.)
+	i_pixtype	i	pixel datatype (SPP integer code)
+	i_minpixval	r	minimum pixel value
+	i_maxpixval	r	maximum pixel value
+	i_ctime		l	time of image creation
+	i_mtime		l	time of last modify
+	i_limtime	l	time when limits (minmax) were last updated
+	i_title		s	title string
+
+
+The names of the standard fields share an "i_" prefix to reduce the possibility
+of collisions with data dependent keywords, to identify the standard fields in
+sorted listings, to allow use of pattern matching to discriminate between the
+standard fields and user fields, and so on.  For the convenience of the user,
+the "i_" prefix may be omitted provided the resultant name does not match the
+name of a user parameter.  It is however recommended that the full name be
+used in all applications software.
+
+
+5. Restrictions
+
+    The use of FITS format as the internal format for storing fields in this
+version of the interface places restrictions on the size of field names and
+of the string value of string valued parameters.  Field names are currently
+limited to eight characters or less and case is ignored (since FITS requires
+upper case).  The eight character limit does not apply to the standard fields.
+String values are limited to at most 68 characters.  If put string is passed
+a longer string it will be silently truncated.  Trailing whitespace and
+newlines are chopped when a string value is read.