casa::StManArrayFile Class Reference

Read/write array in external format for a storage manager. More...

#include <StArrayFile.h>

List of all members.

Public Member Functions
	StManArrayFile (const String &name, ByteIO::OpenOption, uInt version=0, Bool bigEndian=True, uInt bufferSize=65536)
	Construct the object and attach it to the give file.
	~StManArrayFile ()
	Close the possibly opened file.
Bool	flush (Bool fsync)
	Flush and optionally fsync the data.
void	reopenRW ()
	Reopen the file for read/write access.
void	resync ()
	Resync the file (i.e.
Int64	length ()
	Return the current file length (merely a debug tool).
uInt	putShape (const IPosition &shape, Int64 &fileOffset, const Bool *dummy)
	Put the array shape and store its file offset into the offset argument.
uInt	putShape (const IPosition &shape, Int64 &fileOffset, const Char *dummy)
uInt	putShape (const IPosition &shape, Int64 &fileOffset, const uChar *dummy)
uInt	putShape (const IPosition &shape, Int64 &fileOffset, const Short *dummy)
uInt	putShape (const IPosition &shape, Int64 &fileOffset, const uShort *dummy)
uInt	putShape (const IPosition &shape, Int64 &fileOffset, const Int *dummy)
uInt	putShape (const IPosition &shape, Int64 &fileOffset, const uInt *dummy)
uInt	putShape (const IPosition &shape, Int64 &fileOffset, const Int64 *dummy)
uInt	putShape (const IPosition &shape, Int64 &fileOffset, const uInt64 *dummy)
uInt	putShape (const IPosition &shape, Int64 &fileOffset, const Float *dummy)
uInt	putShape (const IPosition &shape, Int64 &fileOffset, const Double *dummy)
uInt	putShape (const IPosition &shape, Int64 &fileOffset, const Complex *dummy)
uInt	putShape (const IPosition &shape, Int64 &fileOffset, const DComplex *dummy)
uInt	putShape (const IPosition &shape, Int64 &fileOffset, const String *dummy)
uInt	getRefCount (Int64 offset)
	Get the reference count.
void	putRefCount (uInt refCount, Int64 offset)
	Put the reference count.
void	put (Int64 fileOffset, uInt arrayOffset, uInt nr, const Bool *)
	Put nr elements at the given file offset and array offset.
void	put (Int64 fileOffset, uInt arrayOffset, uInt nr, const Char *)
void	put (Int64 fileOffset, uInt arrayOffset, uInt nr, const uChar *)
void	put (Int64 fileOffset, uInt arrayOffset, uInt nr, const Short *)
void	put (Int64 fileOffset, uInt arrayOffset, uInt nr, const uShort *)
void	put (Int64 fileOffset, uInt arrayOffset, uInt nr, const Int *)
void	put (Int64 fileOffset, uInt arrayOffset, uInt nr, const uInt *)
void	put (Int64 fileOffset, uInt arrayOffset, uInt nr, const Int64 *)
void	put (Int64 fileOffset, uInt arrayOffset, uInt nr, const uInt64 *)
void	put (Int64 fileOffset, uInt arrayOffset, uInt nr, const Float *)
void	put (Int64 fileOffset, uInt arrayOffset, uInt nr, const Double *)
void	put (Int64 fileOffset, uInt arrayOffset, uInt nr, const Complex *)
void	put (Int64 fileOffset, uInt arrayOffset, uInt nr, const DComplex *)
void	put (Int64 fileOffset, uInt arrayOffset, uInt nr, const String *)
uInt	getShape (Int64 fileOffset, IPosition &shape)
	Get the shape at the given file offset.
void	get (Int64 fileOffset, uInt arrayOffset, uInt nr, Bool *)
	Get nr elements at the given file offset and array offset.
void	get (Int64 fileOffset, uInt arrayOffset, uInt nr, Char *)
void	get (Int64 fileOffset, uInt arrayOffset, uInt nr, uChar *)
void	get (Int64 fileOffset, uInt arrayOffset, uInt nr, Short *)
void	get (Int64 fileOffset, uInt arrayOffset, uInt nr, uShort *)
void	get (Int64 fileOffset, uInt arrayOffset, uInt nr, Int *)
void	get (Int64 fileOffset, uInt arrayOffset, uInt nr, uInt *)
void	get (Int64 fileOffset, uInt arrayOffset, uInt nr, Int64 *)
void	get (Int64 fileOffset, uInt arrayOffset, uInt nr, uInt64 *)
void	get (Int64 fileOffset, uInt arrayOffset, uInt nr, Float *)
void	get (Int64 fileOffset, uInt arrayOffset, uInt nr, Double *)
void	get (Int64 fileOffset, uInt arrayOffset, uInt nr, Complex *)
void	get (Int64 fileOffset, uInt arrayOffset, uInt nr, DComplex *)
void	get (Int64 fileOffset, uInt arrayOffset, uInt nr, String *)
void	copyArrayBool (Int64 to, Int64 from, uInt nr)
	Copy the array with nr elements from one file offset to another.
void	copyArrayChar (Int64 to, Int64 from, uInt nr)
void	copyArrayuChar (Int64 to, Int64 from, uInt nr)
void	copyArrayShort (Int64 to, Int64 from, uInt nr)
void	copyArrayuShort (Int64 to, Int64 from, uInt nr)
void	copyArrayInt (Int64 to, Int64 from, uInt nr)
void	copyArrayuInt (Int64 to, Int64 from, uInt nr)
void	copyArrayInt64 (Int64 to, Int64 from, uInt nr)
void	copyArrayuInt64 (Int64 to, Int64 from, uInt nr)
void	copyArrayFloat (Int64 to, Int64 from, uInt nr)
void	copyArrayDouble (Int64 to, Int64 from, uInt nr)
void	copyArrayComplex (Int64 to, Int64 from, uInt nr)
void	copyArrayDComplex (Int64 to, Int64 from, uInt nr)
void	copyArrayString (Int64 to, Int64 from, uInt nr)
Private Member Functions
uInt	put (const Int &)
	Put a single value at the current file offset.
uInt	put (const uInt &)
uInt	putRes (const IPosition &shape, Int64 &fileOffset, float lenElem)
	Put the array shape at the end of the file and reserve space for nr elements (each lenElem bytes long).
uInt	get (Int &)
	Get a single value at the current file offset.
uInt	get (uInt &)
void	copyData (Int64 to, Int64 from, uInt length)
	Copy data with the given length from one file offset to another.
void	setpos (Int64 offset)
	Position the file on the given offset.
Private Attributes
LargeRegularFileIO *	file_p
TypeIO *	iofil_p
Int64	leng_p
uInt	version_p
Bool	swput_p
Bool	hasPut_p
uInt	sizeBool_p
uInt	sizeChar_p
uInt	sizeuChar_p
uInt	sizeShort_p
uInt	sizeuShort_p
uInt	sizeInt_p
uInt	sizeuInt_p
uInt	sizeInt64_p
uInt	sizeuInt64_p
uInt	sizeFloat_p
uInt	sizeDouble_p

---

Detailed Description

Read/write array in external format for a storage manager.

Intended use:

Internal

Review Status

Reviewed By:

UNKNOWN

Date Reviewed:

before2004/08/25

Prerequisite

• ToLocal
• FromLocal

Etymology

StManArrayFile is a class used by table storage managers to store indirect arrays in a file.

Synopsis

StManArrayFile is for use by the table storage manager, in particular to read/write indirectly stored arrays. Instead of holding the data in memory, they are written directly into a file. It also allows to access a part of an array, which is needed for the table system to access an array section. It does not use a cache of its own, but it is relying on the underlying system routines to cache and buffer adequately.

This class could in principle also be used for other array purposes, for example, to implement a paged array class for really huge arrays.

An StManArrayFile object is connected to one file. It is possible to hold multiple arrays in the file, each with its own shape. An array is stored as its shape followed by the actual data (all in canonical format). An array of strings is written as an array of offsets pointing to the actual strings. When a string gets a new value, the new value is written at the end of the file and the file space with the old value is lost.

Currently only the basic types are supported, but arbitrary types could also be supported by writing/reading an element in the normal way into the AipsIO buffer. It would only require that AipsIO would contain a function to get its buffers and to restart them.

Example

    void writeArray (const Array<Bool>& array)
    {
        // Construct object and update file StArray.dat.
        StManArrayFile arrayFile("StArray.dat, ByteIO::New);
        // Reserve space for an array with the given shape and data type.
        // This writes the shape at the end of the file and reserves
        // space the hold the entire Bool array.
        // It fills in the file offset where the shape is stored
        // and returns the length of the shape in the file.
        Int64 offset;
        uInt shapeLength = arrayFile.putShape (array.shape(), offset, static_cast<Bool*>(0));
        // Now put the actual array.
        // This has to be put at the returned file offset plus the length
        // of the shape in the file.
        Bool deleteIt;
        const Bool* dataPtr = array.getStorage (deleteIt);
        arrayFile.put (offset+shapeLength, 0, array.nelements(), dataPtr);
        array.freeStorage (dataPtr, deleteIt);
    }

Motivation

The AipsIO class was not suitable for indirect table arrays, because it uses memory to hold the data. Furthermore it is not possible to access part of the data in AipsIO.

To Do

• implement long double
• support arbitrary types
• when rewriting a string value, use the current file space if it fits

Definition at line 128 of file StArrayFile.h.

---

Constructor & Destructor Documentation

casa::StManArrayFile::StManArrayFile	(	const String &	name,
		ByteIO::OpenOption	,
		uInt	version = 0,
		Bool	bigEndian = True,
		uInt	bufferSize = 65536
	)

Construct the object and attach it to the give file.

The OpenOption determines how the file is opened (e.g. ByteIO::New for a new file). The buffersize is used to allocate a buffer of a proper size for the underlying filebuf object (see iostream package).

casa::StManArrayFile::~StManArrayFile

(

)

Close the possibly opened file.

---

Member Function Documentation

void casa::StManArrayFile::copyArrayBool	(	Int64	to,
		Int64	from,
		uInt	nr
	)

Copy the array with nr elements from one file offset to another.

void casa::StManArrayFile::copyArrayChar	(	Int64	to,
		Int64	from,
		uInt	nr
	)

void casa::StManArrayFile::copyArrayComplex	(	Int64	to,
		Int64	from,
		uInt	nr
	)

void casa::StManArrayFile::copyArrayDComplex	(	Int64	to,
		Int64	from,
		uInt	nr
	)

void casa::StManArrayFile::copyArrayDouble	(	Int64	to,
		Int64	from,
		uInt	nr
	)

void casa::StManArrayFile::copyArrayFloat	(	Int64	to,
		Int64	from,
		uInt	nr
	)

void casa::StManArrayFile::copyArrayInt	(	Int64	to,
		Int64	from,
		uInt	nr
	)

void casa::StManArrayFile::copyArrayInt64	(	Int64	to,
		Int64	from,
		uInt	nr
	)

void casa::StManArrayFile::copyArrayShort	(	Int64	to,
		Int64	from,
		uInt	nr
	)

void casa::StManArrayFile::copyArrayString	(	Int64	to,
		Int64	from,
		uInt	nr
	)

void casa::StManArrayFile::copyArrayuChar	(	Int64	to,
		Int64	from,
		uInt	nr
	)

void casa::StManArrayFile::copyArrayuInt	(	Int64	to,
		Int64	from,
		uInt	nr
	)

void casa::StManArrayFile::copyArrayuInt64	(	Int64	to,
		Int64	from,
		uInt	nr
	)

void casa::StManArrayFile::copyArrayuShort	(	Int64	to,
		Int64	from,
		uInt	nr
	)

void casa::StManArrayFile::copyData	(	Int64	to,
		Int64	from,
		uInt	length
	)		[private]

Copy data with the given length from one file offset to another.

Bool casa::StManArrayFile::flush

(

Bool

fsync

)

Flush and optionally fsync the data.

It returns True when any data was written since the last flush.

void casa::StManArrayFile::get	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		Bool *
	)

Get nr elements at the given file offset and array offset.

The file offset of the first array element is the file offset of the shape plus the length of the shape in the file. The array offset is counted in number of elements. It can be used to get only a (contiguous) section of the array.

void casa::StManArrayFile::get	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		Char *
	)

void casa::StManArrayFile::get	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		uChar *
	)

void casa::StManArrayFile::get	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		Short *
	)

void casa::StManArrayFile::get	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		uShort *
	)

void casa::StManArrayFile::get	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		Int *
	)

void casa::StManArrayFile::get	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		uInt *
	)

void casa::StManArrayFile::get	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		Int64 *
	)

void casa::StManArrayFile::get	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		uInt64 *
	)

void casa::StManArrayFile::get	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		Float *
	)

void casa::StManArrayFile::get	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		Double *
	)

void casa::StManArrayFile::get	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		Complex *
	)

void casa::StManArrayFile::get	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		DComplex *
	)

void casa::StManArrayFile::get	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		String *
	)

uInt casa::StManArrayFile::get

(

Int &

value

)

[inline, private]

Get a single value at the current file offset.

It returns the length of the value in the file.

Definition at line 336 of file StArrayFile.h.

References iofil_p, and casa::TypeIO::read().

uInt casa::StManArrayFile::get

(

uInt &

value

)

[inline, private]

Definition at line 340 of file StArrayFile.h.

References iofil_p, and casa::TypeIO::read().

uInt casa::StManArrayFile::getRefCount

(

Int64

offset

)

Get the reference count.

uInt casa::StManArrayFile::getShape	(	Int64	fileOffset,
		IPosition &	shape
	)

Get the shape at the given file offset.

It will reshape the IPosition vector when needed. It returns the length of the shape in the file.

Int64 casa::StManArrayFile::length

(

)

[inline]

Return the current file length (merely a debug tool).

Definition at line 155 of file StArrayFile.h.

References leng_p.

void casa::StManArrayFile::put	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		const Bool *
	)

Put nr elements at the given file offset and array offset.

The file offset of the first array element is the file offset of the shape plus the length of the shape in the file. The array offset is counted in number of elements. It can be used to put only a (contiguous) section of the array.

void casa::StManArrayFile::put	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		const Char *
	)

void casa::StManArrayFile::put	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		const uChar *
	)

void casa::StManArrayFile::put	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		const Short *
	)

void casa::StManArrayFile::put	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		const uShort *
	)

void casa::StManArrayFile::put	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		const Int *
	)

void casa::StManArrayFile::put	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		const uInt *
	)

void casa::StManArrayFile::put	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		const Int64 *
	)

void casa::StManArrayFile::put	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		const uInt64 *
	)

void casa::StManArrayFile::put	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		const Float *
	)

void casa::StManArrayFile::put	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		const Double *
	)

void casa::StManArrayFile::put	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		const Complex *
	)

void casa::StManArrayFile::put	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		const DComplex *
	)

void casa::StManArrayFile::put	(	Int64	fileOffset,
		uInt	arrayOffset,
		uInt	nr,
		const String *
	)

uInt casa::StManArrayFile::put

(

const Int &

value

)

[inline, private]

Put a single value at the current file offset.

It returns the length of the value in the file.

Definition at line 326 of file StArrayFile.h.

References hasPut_p, iofil_p, casa::True, and casa::TypeIO::write().

uInt casa::StManArrayFile::put

(

const uInt &

value

)

[inline, private]

Definition at line 331 of file StArrayFile.h.

References hasPut_p, iofil_p, casa::True, and casa::TypeIO::write().

void casa::StManArrayFile::putRefCount	(	uInt	refCount,
		Int64	offset
	)

Put the reference count.

An exception is thrown if a value other than 1 is put for version 0.

uInt casa::StManArrayFile::putRes	(	const IPosition &	shape,
		Int64 &	fileOffset,
		float	lenElem
	)		[private]

Put the array shape at the end of the file and reserve space for nr elements (each lenElem bytes long).

It fills the file offset of the shape. It returns the length of the shape in the file.

uInt casa::StManArrayFile::putShape	(	const IPosition &	shape,
		Int64 &	fileOffset,
		const Bool *	dummy
	)

Put the array shape and store its file offset into the offset argument.

Reserve file space for the associated array. The length of the shape part in the file is returned. The file offset plus the shape length is the starting offset of the actual array data (which can be used by get and put). Space is reserved to store the reference count.

uInt casa::StManArrayFile::putShape	(	const IPosition &	shape,
		Int64 &	fileOffset,
		const Char *	dummy
	)

uInt casa::StManArrayFile::putShape	(	const IPosition &	shape,
		Int64 &	fileOffset,
		const uChar *	dummy
	)

uInt casa::StManArrayFile::putShape	(	const IPosition &	shape,
		Int64 &	fileOffset,
		const Short *	dummy
	)

uInt casa::StManArrayFile::putShape	(	const IPosition &	shape,
		Int64 &	fileOffset,
		const uShort *	dummy
	)

uInt casa::StManArrayFile::putShape	(	const IPosition &	shape,
		Int64 &	fileOffset,
		const Int *	dummy
	)

uInt casa::StManArrayFile::putShape	(	const IPosition &	shape,
		Int64 &	fileOffset,
		const uInt *	dummy
	)

uInt casa::StManArrayFile::putShape	(	const IPosition &	shape,
		Int64 &	fileOffset,
		const Int64 *	dummy
	)

uInt casa::StManArrayFile::putShape	(	const IPosition &	shape,
		Int64 &	fileOffset,
		const uInt64 *	dummy
	)

uInt casa::StManArrayFile::putShape	(	const IPosition &	shape,
		Int64 &	fileOffset,
		const Float *	dummy
	)

uInt casa::StManArrayFile::putShape	(	const IPosition &	shape,
		Int64 &	fileOffset,
		const Double *	dummy
	)

uInt casa::StManArrayFile::putShape	(	const IPosition &	shape,
		Int64 &	fileOffset,
		const Complex *	dummy
	)

uInt casa::StManArrayFile::putShape	(	const IPosition &	shape,
		Int64 &	fileOffset,
		const DComplex *	dummy
	)

uInt casa::StManArrayFile::putShape	(	const IPosition &	shape,
		Int64 &	fileOffset,
		const String *	dummy
	)

void casa::StManArrayFile::reopenRW

(

)

[inline]

Reopen the file for read/write access.

Definition at line 322 of file StArrayFile.h.

References file_p, and casa::LargeRegularFileIO::reopenRW().

void casa::StManArrayFile::resync

(

)

Resync the file (i.e.

clear possible cache information).

void casa::StManArrayFile::setpos

(

Int64

offset

)

[private]

Position the file on the given offset.

---

Member Data Documentation

LargeRegularFileIO* casa::StManArrayFile::file_p [private]

Definition at line 276 of file StArrayFile.h.

Referenced by reopenRW().

Bool casa::StManArrayFile::hasPut_p [private]

Definition at line 281 of file StArrayFile.h.

Referenced by put().

TypeIO* casa::StManArrayFile::iofil_p [private]

Definition at line 277 of file StArrayFile.h.

Referenced by get(), and put().

Int64 casa::StManArrayFile::leng_p [private]

Definition at line 278 of file StArrayFile.h.

Referenced by length().

uInt casa::StManArrayFile::sizeBool_p [private]

Definition at line 282 of file StArrayFile.h.

uInt casa::StManArrayFile::sizeChar_p [private]

Definition at line 283 of file StArrayFile.h.

uInt casa::StManArrayFile::sizeDouble_p [private]

Definition at line 292 of file StArrayFile.h.

uInt casa::StManArrayFile::sizeFloat_p [private]

Definition at line 291 of file StArrayFile.h.

uInt casa::StManArrayFile::sizeInt64_p [private]

Definition at line 289 of file StArrayFile.h.

uInt casa::StManArrayFile::sizeInt_p [private]

Definition at line 287 of file StArrayFile.h.

uInt casa::StManArrayFile::sizeShort_p [private]

Definition at line 285 of file StArrayFile.h.

uInt casa::StManArrayFile::sizeuChar_p [private]

Definition at line 284 of file StArrayFile.h.

uInt casa::StManArrayFile::sizeuInt64_p [private]

Definition at line 290 of file StArrayFile.h.

uInt casa::StManArrayFile::sizeuInt_p [private]

Definition at line 288 of file StArrayFile.h.

uInt casa::StManArrayFile::sizeuShort_p [private]

Definition at line 286 of file StArrayFile.h.

Bool casa::StManArrayFile::swput_p [private]

Definition at line 280 of file StArrayFile.h.

uInt casa::StManArrayFile::version_p [private]

Definition at line 279 of file StArrayFile.h.

---

The documentation for this class was generated from the following file:

• casacore/tables/Tables/StArrayFile.h