Philip Brohan

Back to Philip's IMMA page.

IMMA.pm

IMMA.pm is a Perl module allowing IMMA records to be used by Perl scripts. It provides methods for reading and writing IMMA files and for manipulating IMMA records.

IMMA records are objects with the usual Perl properties. Data values are accessible through the object. I.e. if the object is $record ($record = new IMMA;) the observation year is stored as $record->{YR}, the sea-surface temperature is $record->{SST}, and the wet-bulb temperature indicator is $record->{WBTI}. The elements available are those listed in the IMMA documentation, but note that they are not all guaranteed to be available: if the record has no SST given, $record->{SST} will be undefined.

Methods

1. new: Create a new IMMA object
   Usage: $record = new IMMA;
   All the data are initially undefined.



2. imma_read: read in an IMMA record from a file (class method)
   Usage: $record = imma_read(\*DIN) or die "Couldn't read in IMMA data";
   where DIN is a filehandle for an IMMA file (open(DIN,"file.imma");). This method is exported by default.



3. read: read in an IMMA record from a file (instance method)
   Usage: $record->read(\*DIN) or die "Couldn't read in IMMA data";
   where DIN is a filehandle for an IMMA file (open(DIN,"file.imma");)



4. write: write_out an IMMA record to a file (instance method)
   Usage: $record->write(\*DOUT) or die "Couldn't output IMMA data";
   where DOUT is a filehandle for an IMMA file (open(DOUT,">file.imma");)

Examples

The following example reads in all IMMA fields from the file "old.imma", selects all the records with a known SST and where the latitude is greater than 0 and the longitude is between -70 and 10 (in the North Atlantic) and writes them out to the file "new.imma".

use IMMA;

open(DIN,"old.imma");
open(DOUT,">new.imma");
while($record = imma_read(\*DIN)) {
    if(defined($record->{SST}) &&
       defined($record->{LAT}) && $record->{LAT}>0 &&
       defined($record->{LON}) && $record->{LON}>=-70 && $record->{LON}<=10) {
        $record->write(\*DOUT);
    }
}

Extensions

IMMA is designed to be extensible. Each IMMA record contains a core component and a number of optional extensions (described in the documentation). The details of data for the core and each extension is defined in a separate module:

• core
• ICOADS
• IMMT2
• Model quality control
• Ship metadata
• Historical
• Supplemental

These modules are included automatically by the main IMMA module and for most purposes their use is transparent. Users will only need to be aware of them when explicitly adding or deleting an attachment from an IMMA record. To do this, manipulate the attachments element of the IMMA record: this is a list of the attachments possessed by the record. So, for example push @{$record->{attachments}},3 will add a model quality control attachment (with all data undefined) to $record, 3 is the attachment ID of model quality control attachments.