Low Level I/O Routines

All i/o routines described above are built on top of a set of low level routines. In Miriad, a ``data set'' is a collection of named items. Each item is an unstructured, byte addressable collection of data. It is up to the higher level software to impose some structure to the data items, and to provide a better interface for the high level programmer. The higher level routines should be adequate for most programmers. Though direct use of the following low level routines is discouraged, there are some instances where they may be needed.

      subroutine hopen(tno,dataname,status,iostat)
      subroutine hclose(tno,iostat)
      subroutine haccess(tno,item,itemname,status,iostat)
      subroutine hdaccess(item,iostat)
      subroutine hdelete(tno,itemname,iostat)
      integer function hsize(item)

      subroutine hreada(item,buffer,iostat)
      subroutine hreadb(item,buffer,offset,length,iostat)
      subroutine hreadj(item,buffer,offset,length,iostat)
      subroutine hreadi(item,buffer,offset,length,iostat)
      subroutine hreadr(item,buffer,offset,length,iostat)
      subroutine hreadd(item,buffer,offset,length,iostat)

      subroutine hwritea(item,buffer,iostat)
      subroutine hwriteb(item,buffer,offset,length,iostat)
      subroutine hwritej(item,buffer,offset,length,iostat)
      subroutine hwritei(item,buffer,offset,length,iostat)
      subroutine hwriter(item,buffer,offset,length,iostat)
      subroutine hwrited(item,buffer,offset,length,iostat)

Only two operations can be performed on a data set as a whole, namely to open and to close it. The routines to perform these are hopen and hclose. Here tno is a handle passed back by hopen, dataname is a string giving the name of the data set, and status is either 'old' (when accessing an old data set) or 'new' (when creating a data set). Iostat is a error indicator, being zero if the operation was successful. Because of buffering performed by the i/o routines, it is very important to close a data set when it is no longer needed.

Before any item can be read or written, it must be ``opened'' with the haccess routine. The inputs to this are: tno (the handle passed back by hopen); itemname, a string giving the item name; status, a string which can be 'read', 'write' 'append' or 'scratch' (if an item is opened with status='scratch', an item is created, but then destroyed when the item is closed). The outputs from haccess are firstly a handle, item, which is used to perform i/o on the item, and secondly a status return, iostat. All items should be closed down, with hdaccess, before the data set as a whole is closed.

The hdelete subroutine deletes an item. The integer function hsize returns the size of an item in bytes.

There are a group of i/o routines provided to read and write items. Because items are stored in a machine independent format, there are separate i/o routines for each data type. Each i/o routine performs the conversion between the external (disk) format and the hosts internal format. For example, the hreadr routine reads real numbers. On disk, Miriad reals are stored as IEEE floating point numbers. Internally, however, reals are stored in the hosts machines ``real number format''. The hreadr routine performs the conversion. The read/write routines know nothing about the type of the data it is accessing. The caller must know this, and call the appropriate read/write routine.

All read/write routines take the handle item (passed back by haccess) as their first argument, and pass back an i/o status as the last argument. The second argument is a buffer, which can be either a character string (hreada, hwritea, hreadb, hwriteb), an integer array (hreadj, hwritej, hreadi, hwritei), real (hreadr, hwriter) or double precision (hreadd, hwrited). Hreada and hwritea read/write a text file, performing i/o on a line at a time. Text files are stored using a line-feed character to delimit the end of a line (i.e. the normal UNIX convention, or the VMS Stream_LF convention). The routines hreadb and hwriteb perform i/o on bytes, no conversion being performed - these routines should rarely be needed). The routines hreadj and hwritej assume the integers are externally stored as 16 bit quantities, whereas hreadi and hwritei assume the integers are externally stored as 32 bit quantities. Internally, integers are always stored in the hosts standard integer format (int in C, and an INTEGER in FORTRAN. Real and double precision values are externally stored in IEEE 32 bit and 64 bit floating point format. All read/write routines (except hreada and hwritea) take (as inputs) a byte offset and byte length as their third and fourth arguments. Both offset and length must be a multiple of the size of the data type being accessed (e.g. they must be a multiple of 4 for reals, or 8 for double precision numbers). Apart from this alignment restriction, data items can be read in a random fashion.

All I/O routines pass back an i/o status indicator. A value of zero indicates success, -1 indicates end-of-file, and any other values indicate some other error (that is system dependent).