DAL - aka pedal (Perl Enhanced Data Access Layer)
use DAL;
my $ds = DAL::dataset->new(-name => 'set', -mode => CREATE); my $tab = $ds->addTable(-name => 'table', -rows => 1234); my $col = $tab->addColumn(-name => 'column', -type => REAL32);
etc.
As of version 1.0 of the pedal, the static method
DAL->register($string)
is no longer supported. The corresponding actions are now carried out by default once the `use DAL' statement is executed.
If the application defined the variable $VERSION, this will be used to create a unique string with which the application is registered with the DAL.
The DAL module does no longer export data type and access mode constants into the application's name space. These constants must be fully qualified
The pedal makes use of named parameters. These are specified like so:
$ob->method(par1 => value, par2 => value ...);
The adoption of a new parameter handling library means that parameter names preceeded by a dash (-par1 => value) are no longer supported.
There has been a change in nomenclature in the DAL. Previously, tables, arrays, columns and attributes had a comment field. This is now called label.
The pedal is a Perl OO interface to the XMM Data Access Layer (DAL) libraries. In the following I assume that you are familiar with the DAL data model and the terminology that goes with it.
If you have successfully built this package, you can find more about the XMM DAL (and SAS) by following the links to the local documentation, usually file://${SAS_DIR}/README.html .
Most methods require one or more options to be set. In some cases default values are provided. Note that in general the pedal does not try to ensure that the parameters needed by a method are being set to something sensible (or at all). I made the design choice to make the Perl layer as simple as possible. That means, the parameter values are used in the Perl code are handed down to the underlying libraries that then decide whether this input makes sense or not.
In the following I shall use the following variables to label DAL objects:
*
$ds is a data set.
*
$tb is a table.
*
$co is a column.
*
$ar is an array.
*
$bl is a block.
*
$ob is any of the above, unless otherwise noted.
The variable $datatype is also used to indicate one of the following constants.
$DAL::BOOL: logical
$DAL::INT8: one-byte integer (unsigned)
$DAL::INT16: two-byte integer (signed)
$DAL::INT32: four-byte integer (signed)
$DAL::REAL32: eight-byte float
$DAL::REAL64: sixteen-byte float
$DAL::STRING: character string
The variable $mode is used to indicate one of the following constants. These too are exported
by default. The variable $mode refers to the way the DAL opens
a data set.
$DAL::READ: the data set cannot be modified.
$DAL::CREATE: the data set is created if it does not exist. If it exists, it is overwritten.
$DAL::MODIFY: the data set can be modified.
$DAL::TEMP: the data set is temporary, that is it is erased once it is released.
The variable $mem is used to indicate one of the following constants. These too are exported
by default. The variable $mem refers to the way the DAL makes
use of the available memory.
$DAL::HI: the DAL reads all the data in memory.
$DAL::LO: the DAL reads in memory the least possible amount of data, only when the data is actually needed.
DAL::version(); # returns the pedal version in use.
DAL::clobber(); # returns the clobber status.
$ds = DAL::dataset->new(name => $data_set_name,
accessmode => $mode, memorymodel => $mem);
Defaults:
accessmode => $DAL::CREATE
memorymodel => $DAL::HI
$tb = $ds->addTable(name => $table_name, nrows => $n,
position => $p, label => $label);
Defaults:
nrows => 0
position => -1 (leave it to the DAL to decide, a wise choice)
label => ''
$tb = $ds->table(name => $table_name);
Returns the named table, if it exists.
$co = $tb->addColumn(name => $column_name, datatype
=> $datatype, label => $string, units => $string, dimensions =>
$arrayRef, position => $n);
Defaults:
datatype => $DAL::REAL32
label => ''
units => ''
dimensons => [1]
position => -1 (leave it to the DAL, a wise choice)
$co = $tb->column(name => $column_name);
Returns the named column, if it exists.
$ar = $ds->addArray(name => $array_name, datatype =>
$type, dimensions => $arrayRef, position => $integer);
Defaults:
datatype => $DSAL::REAL32
dimensions => [0]
position => -1 (leave it to the DAL, a wise choice)
$ar = $ds->arrays(name => $array_name);
Returns the named array, if it exists.
$at = $ob->attribute(name => $attribute_name);
Returns the named attribute, if it exists.
$ob->data();
Returns a pointer to the data structure behind the object. See DATA METHODS.
$ob->label();
Returns the object's label.
$ob->relabel(newlabel => $new_object_label);
Relabels the object.
$ob->name();
Returns the name of the object.
$ob->rename(newname => $new_object_name);
Renames the object.
$ob->mode();
Returns the access mode used to open the data set.
$ob->release();
Releases the object. The DAL could decide to free the memory allocated to the object.
$ob->hasAttribute(-name => $attribute_name);
Returns true if the object has the named attribute.
$ob->addAttribute(name => $attribute_name, datatype => $datatype, value => $value, units => $units, label => $string);
Adds an attribute to the object. For columns the list of possible attributes is defined in the DAL.
Defaults:
datatype => $DAL::REAL32
value => 0
units => ''
label => ''
$ob->deleteAttribute(name => $attribute_name);
Removes the named attribute.
$ob->addComment(value => $string);
Adds a comment entry to the object.
Defaults:
value => ''
$ob->comments();
Returns the number of comment entries.
$ob->comment(position => $n);
Returns the n-th comment entry.
Defaults:
position => 0
$ob->addHistory(value => $string);
Add a history entry to the object.
Defaults:
value => ''
$ob->historys();
Returns the number of history entries for the object.
$ob->history(position => $n);
Returns the n-th history entry.
Defaults:
position => 0
$ob->units();
Returns the units of the object.
$ob->type();
Returns the data type of the object.
$ds->addArray(...);
See Array constructors.
$ds->array(...);
See Array constructors.
$ds->hasArray(name => $array_name);
Returns true if the named array exists.
$ds->deleteArray(name => $array_name);
Deletes the named array.
$ds->addTable(...);
See Array constructors.
$ds->table(...);
See Array constructors.
$ds->hasTable(name => $table_name);
Returns true if the named table exists.
$ds->deteleTable(name => $table_name);
Deletes the named table.
$ds->blocks();
Returns the number of blocks in the data set.
$ds->hasBlock(name => $block_name);
Returns true if the named block exists.
$ds->deleteBlock(name => $block_name);
Deletes the named block.
$ob->columns();
Returns the number of columns in the object.
$tb->hasColumn(name => $column_name);
Returns true if the named column exists in the table.
$co = $tb->addColum(...);
See Column constructors.
$co = $tb->column(...);
See Column constructors.
$tb->deleteColumn(name => $column_name);
Deletes the named column.
$ob->dimensions();
In list context it returns a list with the dimensions of the object. In scalar context it returns the number of dimensions of the object.
$ob->elements();
This returns the number of elements in a data cell. This is the product of the elements in the list returned by the previous method.
$ob->rows();
Returns the number of rows in the object.
These methods work on variable length column. A varaible length column is
created by setting dimensions = []> in the addColumn call.
$ob->setCellSize(row => $row, size => $size);
Sets $row to contain $size elements.
Defaults:
row => 0
size => 1
$ob->cellSize(row => $row);
Inquires the size of a row.
Defaults:
row => 0
$v = $ob->cellData(row => $row);
Returns the data object corresponsing to a given row. See DATA METHODS.
Defaults:
row => 0
Note that these methods are not efficient (i.e., they are slow). Good enough to manipulate small data sets.
$v = $ob->data();
Returns a pointer to the data associated with te object.
$v->set($value, $index);
Assigns $value to the $index-th elemnth of the object.
$oneElement = $v->value($index);
Returns the current elements.
$at->asInt8();
Returns the attribute as $DAL::INT8.
$at->asInt16();
Returns the attribute as $DAL::INT16.
$at->asInt32();
Returns the attribute as $DAL::INT32.
$at->asString();
Returns the attribute as $DAL::STRING.
$at->asBool();
Returns the attribute as $DAL::BOOL.
$at->asReal32();
Returns the attribute as $DAL::REAL32.
$at->asReal64();
Returns the attribute as $DAL::REAL64.
The pedal is based on a C interface to the XMM Data Access Layer C++ libraries. The C interface was then converted to a set of Perl-callable routines via SWIG (http://www.swig.org/). Then, an object oriented interface was built over the flat Perl interface.
*
The data methods are extremely slow. They are based on SWIG's pointer libraries, that possibly where never intended to handle large amounts of data. The pedal should interface to PDL (http://pdl.perl.org/).
*
It should be possible to insert/remove rows from a table.
*
It should be possible to copy rows from one table to another.
Giuseppe Vacanti, cosine science & comuting, XMM Science Operations Team
Mark Thomas, Cara, XMM Science Operations Team
Edward Chapin, XMM Science Operations Centre
The pedal was born out of an idea of Giuseppe Vacanti. It was made possible by Mark Thomas's hard work. Edward Chapin added a patch that fixes the use of BOOL, INT8 and STRING types.
DAL::utils.