D Core libraries

 D.1 ORAC::BaseFile
 D.2 ORAC::BaseFITS
 D.3 ORAC::BaseGSD
 D.4 ORAC::BaseNDF
 D.5 ORAC::Basic
 D.6 ORAC::Convert
 D.7 ORAC::Core
 D.8 ORAC::Display::Base
 D.9 ORAC::Display::GAIA
 D.10 ORAC::Display::KAPVIEW
 D.11 ORAC::Error
 D.12 ORAC::Inst::Defn
 D.13 ORAC::Msg::EngineLaunch
 D.14 ORAC::Msg::MessysLaunch

This section describes the libraries that are relevant for someone modifying the core.

D.1 ORAC::BaseFile

Shared Base class for Frame and Group classes

SYNOPSIS

  use base qw/ ORAC::BaseFile /;
DESCRIPTION

This class contains methods that are shared by both Frame and Group classes. For example, header and user-header manipulation. File format specific code should not be included (use, for example, ORAC::BaseNDF).

PUBLIC METHODS

The following methods are available in this class: Constructors  The following constructors are available:

new

Create a new ORAC::BaseFile object. In general this constructor should not be called directly but should be called from a subclass.

  $file = ORAC::BaseFile->new( $filename );  
  $file = ORAC::BaseFile->new( \@filenames );  
  $file = ORAC::BaseFile->new();

The filename is optional. Multiple files are supplied as a reference to an array.

The base class constructor should be invoked by sub-class constructors. If this method is called with the last argument as a reference to a hash it is assumed that this hash contains extra configuration information (’instance’ information) supplied by sub-classes.

  $file = ORAC::BaseFile->new( \%internal );

Calls the configure method to handle sub-class specific configuration. The file arguments to configure match the arguments to the constructor.

Accessor Methods 
allow_header_sync

Whether or not to allow automatic header synchronization when the Frame is updated via either the file or files method.

  $Frm->allow_header_sync( 1 );  
  my $allow = $Frm->allow_header_sync;

Defaults to false (0).

file

This method can be used to retrieve or set the file names that are currently associated with the frame. Multiple file names can be stored if required (for example the names associated with different SCUBA sub-instruments).

  $first_file = $Frm->file;     # First file name  
  $first_file = $Frm->file(1);  # First file name  
  $second_file= $Frm->file(2);  # Second file name  
  $Frm->file(1, value);         # Set the first file name  
  $Frm->file(value);            # Set the first filename  
  $Frm->file(10, value);        # Set the tenth file name

Note that counting starts at 1 (and not 0 as is normal for Perl arrays) and that the filename can not be an integer (otherwise it will be treated as an array index). Use files() to retrieve all the values in an array context.

If a file has been marked as temporary (ie with the nokeep() method) it is erased (running the erase() method) when the file name is updated.

For example, the second file (file_2) is marked as temporary with $Frm- >nokeep(2,1). The next time the filename is updated ($Frm- >file(2,’new_file’)) the current file is erased before the ’new_file’ name is stored. The temporary flag is then reset to zero.

If a file number is requested that does not exist, the first member is returned.

Every time the file name is updated, the new file is pushed onto the intermediates() array. This is so that intermediate files can be tidied up when required.

If the first argument is present but not defined the command is treated as if you typed

 $Frm->file(1, undef);

ie the first file is set to undef.

The first time a filename is stored the name will also be stored in raw() if no previous entries have been made in raw.

If the requested index is the number "0" an exception will be thrown since it is highly unlikely that you wanted a file name called "0".

files

Set or retrieve the array containing the current file names associated with the frame object.

    $Frm->files(@files);  
    @files = $Frm->files;

    $array_ref = $Frm->files;

In a scalar context the array reference is returned. In an array context, the array contents are returned.

The file() method can be used to set or retrieve individual filenames.

The previous files are stored as intermediates (similarly to the file method behaviour) and the nokeep flag is respected.

Note: It is possible to set and retrieve the array members using the array reference rather than the file() method:

  $first = $Frm->files->[0];

In this approach, the file numbering starts at 0. The file() method is the recommended way of addressing individual members of this array since the file() method could do extra processing of the string (especially when setting the value, for example the automatic deletion of temporary files).

The first time a filename is stored the name will also be stored in raw() if no previous entries have been made in raw.

gui_id

Returns the identification string that is used to compare the current frame with the frames selected for display in the display definition file.

Arguments:

 number - the file number (as accepted by the file() method)  
          Starts counting at 1. If no argument is supplied  
          a 1 is assumed.

To return the ID associated with the second frame:

 $id = $Frm->gui_id(2);

If nfiles() equals 1, this method returns everything after the last suffix (using an underscore) from the filename stored in file(1). If nfiles > 1, this method returns everything after the last underscore, prepended with ’s$number’. ie if file(2) is test_dk, the ID would be ’s2dk’; if file() is test_dk (and nfiles = 1) the ID would be ’dk’. A special case occurs when the suffix is purely a number (ie the entire string matches just "∖d+"). In that case the number is translated to a string "num" so the second frame in "c20010108_00024" would return "s2num" and the only frame in "f2001_52" would return "num".

Returns undef if the file name is not defined.

nfiles

Number of files associated with the current state of the object and stored in file(). This method lets the caller know whether an observation has generated multiple output files for a single input.

fits

Return (or set) the Astro::FITS::Header object associated with the FITS header from the raw data. If you simply want to access individual FITS headers then you probably should be using the hdr method.

  $Frm->fits( $fitshdr );  
  $fitshdr = $Frm->fits;

Translated FITS headers are available using the uhdr method.

If no FITS header has been associated with this object, one is automatically created from the hdr. This allows the header to be derived from either a FITS object or a normal hash.

format

Data format associated with the current file(). Usually one of ’NDF’ or ’FITS’. This format should be recognisable by ORAC::Convert.

hdr

This method allows specific entries in the header to be accessed. In general, this header is related to the actual header information stored in the file. The input argument should correspond to the keyword in the header hash.

  $tel = $Frm->hdr("TELESCOP");  
  $instrument = $Frm->hdr("INSTRUME");

Can also be used to set values in the header. A hash can be used to set multiple values (but does not overwrite other keys).

  $Grp->hdr("INSTRUME" => "IRCAM");  
  $Frm->hdr("INSTRUME" => "SCUBA",  
            "TELESCOP" => ’JCMT’);

If no arguments are provided, the reference to the header hash is returned.

  $Grp->hdr->{INSTRUME} = ’SCUBA’;

The header can be populated from the file by using the readhdr() method. If a FITS header object has been set via the fits method, a new header hash will be created automatically if one does not exist already (via a tie).

If there were two headers in the original FITS header only the last header is returned (in scalar context). All headers are returned in list context.

  @all = $Frm->hdr("COMMENT");  
  $last = $Frm->hdr("HISTORY");
hdrval

Return the requested header entry, automatically dealing with subheaders. Essentially overrides the standard hdr method for retrieving a header value. Returns undef if no arguments are passed.

    $value = $Frm->hdrval( "KEYWORD" );  
    $value = $Frm->hdrval( "KEYWORD", 0 );

Both return the values from the first sub-header (index 0) if the value is not present in the primary header.

hdrvals

Return all the different values associated with a single FITS header taken from all subheaders.

  @values = $Frm->hdrvals( $keyword );

Only unique values are returned. Quickly enables the caller to determine how many distinct states are in the Frame.

hdrkeys

Return a list of FITS header keys, including those found in subheaders.

inout

Method to return the current input filename and the new output filename given a suffix. For the base class the input filename is chopped at the last underscore and the suffix appended when the name contains at least 2 underscores. The suffix is simply appended if there is only one underscore. This prevents numbers being chopped when the name is of the form ut_num.

Note that this method does not set the new output name in this object. This must still be done by the user.

Returns $in and $out in an array context:

   ($in, $out) = $Frm->inout($suffix);

Returns $out in a scalar context:

   $out = $Frm->inout($suffix);

Therefore if in=file_db and suffix=_ff then out would become file_db_ff but if in=file_db_ff and suffix=dk then out would be file_db_dk.

An optional second argument can be used to specify the file number to be used. Default is for this method to process the contents of file(1).

  ($in, $out) = $Frm->inout($suffix, 2);

will return the second file name and the name of the new output file derived from this. An explicit undefined value will cause the file() method to be invoked without arguments.

The last suffix is not removed if it consists solely of numbers. This is to prevent truncation of raw data filenames.

intermediates

An array containing all the intermediate file names used during processing. Filenames are pushed onto this array whenever the file() method is used to update the current file information.

  $Frm->intermediates(@files);  
  @files = $Frm->intermediates;  
  push(@{$Frm->intermediates}, $file);  
  $first = $Frm->intermediates->[0];

As for the files() method, returns an array reference when called in a scalar context and an array of file names when called from an array context.

The array does not store information relating to the position of the file in the files() array [ie was it stored as $Frm- >file(1) or $Frm- >file(2)]. The order simply reflects the order the files were given to the file() method.

See also the push_intermediates() method.

push_intermediates

Equivalent to

  push(@{$Frm->intermediates}, @files);

but ensures that raw frames are not stored on the intermediates array (do not want to risk deleting raw data).

Returns the number of intermediates that were stored (ie either 0 or the number of file names supplied).

raw

This method returns (or sets) the name of the raw data file(s) associated with this object.

  $Frm->raw("raw_data");  
  $filename = $Frm->raw;

This method returns the first raw data file if called in scalar context, or a list of all the raw data files if called in list context.

Populated automatically the first time the files method is used (or during initial object configuration).

nokeep

Flag used to determine whether the current filename should be erased when the file() method is next used to update the current filename.

  $Frm->erase($i) if $Frm->nokeep($i);

  $Frm->nokeep($i, 1);  # make ith file temporary  
  $Frm->nokeep($i, 0);  # Make ith file permanent

  $nokeep = $Frm->nokeep($i);

The mandatory first argument specifies the file number associated with this flag (same scheme as used by the file() method). An optional second argument can be used to set the flag. ’True’ indicates that the file should not be kept, ’false’ indicates that the file is permanent.

nokeepArr

Array of flags. Used internally by nokeep() method. Set or retrieve the array containing the flags used by the nokeep() method to determine whether the current filename should be erased when the file() method is next used to update the current filename.

    $Frm->nokeepArr(@flags);  
    @flags = $Frm->nokeepArr;

    $array_ref = $Frm->nokeepArr;

In a scalar context the array reference is returned. In an array context, the array contents are returned.

The nokeep() method can be used to set or retrieve individual flags (the numbering scheme is different).

Note: It is possible to set and retrieve the array members using the array reference rather than the nokeep() method:

  $first = $Frm->nokeepArr->[0];

In this approach, the numbering starts at 0. The nokeep() method is the recommended way of addressing individual members of this array since it could do extra processing of the string.

product

Set or return the "product" of the current File object.

  $self->product( ’Baselined cube’ );  
  $self->product( ’reduced’, ’White-light cube’ );  
  $product = $self->product;

A "product" is a description of what the current Frame actually is. For example, in an imaging pipeline this might be "dark-subtracted" or "flat-fielded".

tagexists

Check a given tag against the list of current tags and return true if a match is found.

  my $tag_exists = $self->tagexists( $tag );

The comparison is case sensitive.

tagset

Associate the current filenames with a key (or tag). Once a tag is initialised (it can be any string) the tagretrieve method can be used to copy these filenames back into the object so that the files() method will use those rather than the current values. This allows the data reduction steps to be "rewound".

  $Frm->tagset(’REBIN’);

The tag is case insensitive.

tagretrieve

Retrieve the files names from the tag and make them the default filenames for the object.

  my $status = $Frm->tagretrieve(’REBIN’);

The current filenames are stored in the ’PREVIOUS’ tag (unless the PREVIOUS tag is requested).

If the given tag does not exist, then this function returns false. Otherwise returns true.

Automatic header syncing is disabled inside this method.

uhdr

This method allows specific entries in the user-defined header to be accessed. The input argument should correspond to the keyword in the user header hash.

  $tel = $Grp->uhdr("Telescope");  
  $instrument = $Frm->uhdr("Instrument");

Can also be used to set values in the header. A hash can be used to set multiple values (but does not overwrite other keys).

  $Grp->uhdr("Instrument" => "IRCAM");  
  $Frm->uhdr("Instrument" => "SCUBA",  
             "Telescope" => ’JCMT’);

If no arguments are provided, the reference to the header hash is returned.

  $Frm->uhdr->{Instrument} = ’SCUBA’;
wcs

This method can be used to retrieve or set the World Coordinate System that is currently associated with the frame. Multiple WCSs can be stored if required (for example the WCSs associated with different ACSIS sub-instruments).

  $first_wcs = $Frm->wcs;     # First WCS  
  $first_wcs = $Frm->wcs(1);  # First WCS  
  $second_wcs= $Frm->wcs(2);  # Second WCS  
  $Frm->wcs(1, value);         # Set the first WCS  
  $Frm->wcs(value);            # Set the first WCS  
  $Frm->wcs(10, wcs);        # Set the tenth WCS

Note that counting starts at 1 (and not 0 as is normal for Perl arrays).

If a WCS number is requested that does not exist, the first member is returned.

If the first argument is present but not defined the command is treated as if you typed

  $Frm->wcs(1, undef);

ie the first wcs is set to undef.

General Methods 
sync_headers

This method is used to synchronize FITS headers with information stored in e.g. the World Coordinate System.

  $Frm->sync_headers;  
  $Frm->sync_headers(1);

This method takes one optional parameter, the index of the file to sync headers for. This index starts at 1 instead of 0.

Headers are only synced if the value returned by allow_header_sync is true.

header_override_file

Sets the name of the file containing header override information.

_get_header_override

Returns a hash of headers to be overridden by filename.

calc_orac_headers

This method calculates header values that are required by the pipeline by using values stored in the header.

Required ORAC extensions are:

ORACTIME: should be set to a decimal time that can be used for comparing the relative start times of frames. For IRCAM this number is decimal hours, for SCUBA this number is decimal UT days.

ORACUT: This is the UT day of the frame in YYYYMMDD format.

This method should be run after a header is set. Currently the readhdr() method calls this whenever it is updated.

  %translated = $Frm->calc_orac_headers;

This method updates the frame user header and returns a hash containing the new keywords.

configure

This method is used to configure the object. It is invoked automatically if the new() method is invoked with an argument. The file() and readhdr() methods are invoked by this command. A single argument is required (to provide compatibility with subclasses) that either refers to the filename or a reference to an array of filenames. Note that the 2 arg version is only supported by specific subclasses (see documentation).

  $Frm->configure( $filename );  
  $Frm->configure( \@files );

Multiple raw file names can be provided in the first argument using a reference to an array.

readhdr

A method that is used to read header information from the group file. This method does nothing by default since the base class does not know the format of the file associated with an object.

The calc_orac_headers() method is called automatically.

translate_hdr

Translates an ORAC-DR specific header (such as ORAC_TIME) to the equivalent FITS header(s).

  %fits = $Frm->translate_hdr( "ORAC_TIME" );

In some cases a single ORAC-DR header can be decomposed into multiple FITS headers (for example for SCUBA, ORAC_TIME is a combination of the UTDATE and UTSTART). The hash returned by translate_hdr() will include all the key/value pairs required to generate the ORAC header.

This method will be called automatically to update hdr() values ORAC_ keywords are updated via uhdr().

Returns an empty list if no translation is available.

fullfname

Convert the supplied string to the actual file on disk. This would be a string stored in the files() attribute. Normally a no-op but for the case of Starlink a suffix will be added.

  $full = $Frm->fullfname( $file );
force_product_update

Update the product() value and force the file to receive the update with a sync headers.

  $Obj->force_product_update( "snr", @filenames );

The supplied file names will become the associated with the files() method.

If no files are supplied or if files are supplied and the object has no files associated with it, sync_headers() will be called to force the header updates.

SEE ALSO

ORAC::Frame, ORAC::Group

COPYRIGHT

Copyright (C) 2007 Science and Technology Facilities Council. Copyright (C) 1998-2007 Particle Physics and Astronomy Research Council. All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA

D.2 ORAC::BaseFITS

Base class for FITS file manipulation

SYNOPSIS

  use base qw/ ORAC::BaseFITS /;
DESCRIPTION

This class provides base methods for use by classes that need to manipulate FITS files. For example, ORAC::Frame::MEF.

METHODS
General Methods 
readhdr

Reads the header from the observation file (the filename is stored in the object). This method sets the header in the object (in general that is done by configure() ).

    $Frm->readhdr;

The filename can be supplied if the one stored in the object is not required:

    $Frm->readhdr($file);

but the header in $Frm is over-written. All exisiting header information is lost. The calc_orac_headers() method is invoked once the header information is read. If there is an error during the read a reference to an empty hash is returned.

If used as a class method, the filename must be supplied and calc_orac_headers() will not be called.

Returns the Astro::FITS::Header object.

parsefname

Return the basename of a FITS file, (that is the name of the file without the .fit, .fits etc. filename extension) as well as the directory, filename suffix and FITS image extension number.

    ($basename,$dir,$suffix,$extn) = $Frm->parsefname($in);

The argument is optional. If you supply one, it will extract the basename of the argument stripping off the extension relevant to the object...

NOTES

This class must be in the class hierarchy ahead of the base frame class (ORAC::BaseFile) so that the readhdr method is picked up correctly.

SEE ALSO

ORAC::Frame::MEF

COPYRIGHT

Copyright (C) 1998-2002 Particle Physics and Astronomy Research Council. All Rights Reserved.

D.3 ORAC::BaseGSD

Base class for NDF file manipulation

SYNOPSIS

  use base qw/ ORAC::BaseGSD /;
DESCRIPTION

This class provides base methods for use by classes that need to manipulate GSD files. For example, ORAC::Frame::GSD and ORAC::Group::GSD.

METHODS
General Methods 
readhdr

Reads the header from the observation file (the filename is stored in the object). This method sets the header in the object (in general that is done by configure() ).

    $Frm->readhdr;

The filename can be supplied if the one stored in the object is not required:

    $Grp->readhdr($file);

but the header in $Frm is over-written. All exisiting header information is lost. The calc_orac_headers() method is invoked once the header information is read. If there is an error during the read a reference to an empty hash is returned.

Currently this method assumes that the reduced group is stored in GSD format. Only the FITS header is retrieved from the GSD.

If used as a class method, the filename must be supplied and calc_orac_headers() will not be called.

Returns the Astro::FITS::Header object.

NOTES

This class must be in the class hierarchy ahead of the base frame class (ORAC::BaseFile) so that the readhdr method is picked up correctly.

SEE ALSO

ORAC::Frame::GSD, ORAC::Group::GSD

COPYRIGHT

Copyright (C) 2003 Particle Physics and Astronomy Research Council. All Rights Reserved.

D.4 ORAC::BaseNDF

Base class for NDF file manipulation

SYNOPSIS

  use base qw/ ORAC::BaseNDF /;
DESCRIPTION

This class provides base methods for use by classes that need to manipulate NDF files. For example, ORAC::Frame::NDF and ORAC::Group::NDF.

METHODS
General Methods 
collate_headers

This method is used to collect all of the modified FITS headers for a given Frame object and return an updated Astro::FITS::Header object to be used by the sync_headers method.

  my $header = $Frm->collate_headers( $file );

Takes one argument, the filename for which the header will be returned.

readhdr

Reads the header from the observation file (the filename is stored in the object). This method sets the header in the object (in general that is done by configure() ).

    $Frm->readhdr;

The filename or filenames can be supplied if the one stored in the object is not required:

    $Grp->readhdr($file);

but the header in $Frm is over-written. If multiple files are in the frame or if multiple filenames are given the header information will be merged. Merged headers will be stored as subheaders and accessible in the hash interface via $Frm- >hdr- >{SUBHEADERS}- >[n]. By default only data that differs will be in a subheader.

An options hash as first argument can be used to override the default behaviour. Specifically if a single file is given (or stored in the object) but it contains multiple NDF components, the headers can be returned such that the component named HEADER or largest header is the primary and the subheaders are stored by component name.

  $Frm->readhdr( { nomerge => 1 }, $filename );

The subheaders will then be accessible as $Frm- >hdr- >{I1} (if the component is called "I1").

All existing header information is lost. The calc_orac_headers() method is invoked once the header information is read. If there is an error during the read a reference to an empty hash is returned.

Currently this method assumes that the reduced group is stored in NDF format. Only the FITS header is retrieved from the NDF.

If used as a class method, the filename(s) must be supplied and calc_orac_headers() will not be called.

Returns the FITS header object.

sync_headers

This method is used to synchronize FITS headers with information stored in e.g. the World Coordinate System.

  $Frm->sync_headers;  
  $Frm->sync_headers(1);

This method takes one optional parameter, the index of the file to sync headers for. This index starts at 1 instead of 0. If a non-number is given it is assumed to be the name of a file.

Headers are only synced if the value returned by allow_header_sync is true.

read_wcs

Read the frameset and store the resulting Starlink::AST object into the object for later retrieval via the wcs() method.

  $Frm->read_wcs();

If a file name or filenames are provided the default behaviour is over-ridden and the frameset is only read for the provided files. The resultant framesets are returned without being stored in the object.

  $wcs = $Frm->read_wcs( $file );

In scalar context the first WCS object is returned.

write_wcs

Write the frameset back into the NDF.

  $Frm->write_wcs( $frameset );

If a file name or filenames are provided the default behaviour is over-ridden and the frameset is only read for the provided files. The resultant framesets are returned without being stored in the object.

  $wcs = $Frm->write_wcs( $file );

In scalar context the first WCS object is returned.

flush_messages

Flush any pending oracdr log messages to the history block of the associated file or files. Each file in the object is modified. Only new history is written to the file.

  $Frm->flush_messages();  
  $Grp->flush_messages();

Specifying a reference epoch will mean that only a log messages since that epoch will be considered.

  $Frm->flush_messages( $refepoch );
set_app_name

A class method that is used to set the NDF application name from the supplied arguments. Usually triggered automatically on entry to a new primitive.

  $File->set_app_name( Primitive => $primitive );

Call without arguments to reset the name to the ORAC-DR app name and version number.

fullfname

Convert the supplied string to the actual file on disk. This would be a string stored in the files() attribute. HDS components are removed from the name and ".sdf" is added.

  $full = $Frm->fullfname( $file );
PRIVATE METHODS

The following methods are intended for use inside the module. They are included here so that authors of derived classes are aware of them.

stripfname

Method to strip file extensions from the filename string. This method is called by the file() method. We strip all extensions of the form ".sdf", ".sdf.gz" and ".sdf.Z" since Starlink tasks do not require the extension when accessing the file name if Convert has been started.

_find_ndf_children

Given an array of filenames, open each one using HDS and see whether there are any top level NDFs inside.

 @paths = $frm->_find_ndf_children( @files );

If a filename looks like it includes an HDS path (ie a file suffix that is not ".sdf") it will be returned unmodified without being opened.

Options can be used to control behaviour if the first argument is a reference to a hash

 @paths = $frm->_find_ndf_children( { compnames => 1}, $file );

If the "compnames" options is true only the names of component NDFs within an HDS structure will be returned, rather than the filename with paths.

NOTES

This class must be in the class hierarchy ahead of the base frame class (ORAC::BaseFile) so that the readhdr method is picked up correctly.

SEE ALSO

ORAC::Frame::NDF, ORAC::Group::NDF

COPYRIGHT

Copyright (C) 2007-2008 Science and Technology Facilities Council. Copyright (C) 1998-2007 Particle Physics and Astronomy Research Council. All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA

D.5 ORAC::Basic

Some implementation subroutines

SYNOPSIS

  use ORAC::Basic;

  $Display = orac_setup_display;  
  orac_exit_normally($message);  
  orac_exit_abnormally($message);
DESCRIPTION

Routines that do not have a home elsewhere.

FUNCTIONS

The following functions are provided:

orac_force_abspath

Force ORAC_DATA_IN and ORAC_DATA_OUT to use an absolute path rather than a relative path. Must be called before pipeline does the first chdir.

 orac_force_abspath();

Does not canonicalize.

orac_setup_display

Create a new Display object for use by the recipes. This includes the association of this object with a specific display configuration file (disp.dat). If a configuration file is not in $ORAC_DATA_OUT one will be copied there from $ORAC_DATA_CAL (or $ORAC_DIR if no file exists in $ORAC_DATA_CAL).

If the $DISPLAY environment variable is not set, the display subsystem will be started but only for use by monitor programs.

The display object is returned.

  $Display = orac_setup_display;

Hash arguments can control behaviour to indicate master vs monitor behaviour. Options are:

  - monitor =>  configure as a monitor (default is to be master) (false)  
  - nolocal =>  disable master display, monitor files only.  
                Default is to display locally (false)  
  - orac_instrument => additional information for display title (where possible)  
  - picard_recipe => additional information for display title (where possible)  
  - recsuffix => additional information for display title (where possible)

Monitor files are always written if a master.

orac_make_title_info

Make informational string to be shown in window titles given the parameters passed as options.

orac_exit_normally

Standard exit handler for oracdr. Should be called instead of exit() when the pipeline is complete.

Hash arguments control the behaviour. Allowed keys are:

  quiet - Do not print any informational messages to stdout (default is false)  
  message - Any string to be printed  
  err   - true if the supplied message is an error message  
          or if the process should exit with bad status (default is false  
          unless error stack is populated)

If called with a single argument, it is assumed to be an informational message and is equivalent to using the "message" argument. "err" will default to true if we are called when there are messages in the ORAC::Error stack.

Message is printed using orac_err if we know it is an error message. It will be printed even if "quiet" is true.

orac_exit_abnormally

Exit handler when a problem has been encountered. Normally used a signal handler for SIGINT.

orac_exit_if_error

Wrapper around orac_exit_normally(). Will flush errors, display the error message and exit with bad error status if a defined message is supplied. Useful when handling an error from a try block.

  orac_exit_if_error( $errtext );

Does nothing if there is no error text.

orac_chdir_output_dir

Change to the output directory. If that fails, exit the pipeline.

  orac_chdir_output_dir();

Default output directory is controlled by ORAC_DATA_OUT environment variable.

Takes one argument, a boolean dictating whether or not a check that the data is on an NFS disk should be done. By default this check is done, and if ORAC_DATA_OUT is on an NFS-mounted disk, then the pipeline will exit.

SEE ALSO

ORAC::Core, ORAC::General

COPYRIGHT

Copyright (C) 1998-2004 Particle Physics and Astronomy Research Council. All Rights Reserved.

D.6 ORAC::Convert

Methods for converting data formats

SYNOPSIS

  use ORAC::Convert

  $conv = new ORAC::Convert;  
  $outfile = $conv->convert($infile, {IN => ’FITS’, OUT => ’NDF’});

  $outfile = $conv->convert($infile, { OUT => ’NDF’});

  $outfile = $conv->fits2ndf($infile);

  $conv->infile($infile);  
  $outfile = $conv->convert;  # uses infile()
DESCRIPTION

Provide a system for converting data formats. Currently the only output format supported are:

  NDF     - simple NDF files  
  HDS     - HDS containers with .HEADER and .Inn NDFs  
  FITS    - Simple FITS files

The only input formats supported are:

  NDF     - simple NDF files  
  FITS    - FITS file  
  UKIRTIO - UKIRT I/O file  
  HDS     - HDS containers with .HEADER and .Inn NDFs  
            In general this can only be converted to a NDF or FITS  
            output file if there is only one data frame in the container.  
  GMEF    - Gemini Multi-Extension FITS.  
  INGMEF  - Isaac Newton Group Multi-Extension FITS.

In many cases the NDF format is used as the intermediate format for all conversions (should probably use PDLs as the intermediate format....)

Uses the Starlink CONVERT package (via monoliths) where necessary.

Can be used to convert from instrument specific NDF files (eg multi-frame CGS4 data or I- and O- frames for IRCAM) to HDS formats usable by the pipeline (either as HDS containers or NDFs with combined I and O information).

The output filename is always related to the input filename (usually simply with a change of suffix).

METHODS

The following methods are provided: Constructors 

new

Object constructor. Should always be used before initiating a conversion.

  $Cvt = new ORAC::Convert;

Returns undef if there was an error creating the object. No arguments are required.

Accessor Methods  The following methods are available for accessing the ’instance’ data.
engine_launch_object

Returns the ORAC::Msg::EngineLaunch object that can be used to launch algorithm engines as required by the particular conversion.

 $messys = $self->messys_launch_object;
infile

Method for storing or retreiving the current input filename. Used by default if omitted from convert() methods.

  $infile = $Cvt->infile;
overwrite

Method for storing or retreiving the flag governing whether a file should be overwritten if it already exists.

If false, the file will be converted regardless.

General Methods 
convert

Convert a file to the format specified by options.

  ($infile, $outfile) = $Cvt->convert;  
  @files = $Cvt->convert($oldfile, { IN => ’FITS’, OUT => ’NDF’ });

File is optional - uses infile() to retrieve the name if not specified. The options hash is optional (assumed to be last argument). If not specified the input format will be guessed and the output format will be set to NDF.

Recogised keywords in the hash are:

  IN  => input format (NDF, UKIRTio or FITS)  
  OUT => desired output format (NDF or HDS)

If ’IN’ is not specified it will try to derive the format from name.

The output format is set to NDF if non-specified.

Returns a list containing the input filename and output filename. Neither of these filenames has any directory structure removed.

Output filename is written to the current working directory of the CONVERT monoliths (defaults to the CWD of the program when the monoliths were launched - no attempt is made to correct the CWD of the monoliths before conversion).

Will return an undefined output file if the conversion failed.

guessformat

Given ’name’ try to guess data format.

  $format = $Cvt->guessformat("test.sdf");

If no name is supplied, infile() is used to retrieve the current filename.

mon

Returns the algorithm engine object, launching it if required.

  $object = $Cvt->mon($name);

Returns undef if a monolith can not be contacted or fails to start. This is launched using ORAC::Msg::LaunchEngine.

Data Conversion Methods 
fits2ndf

Convert a fits file to an NDF. Returns the output name.

  $newfile = $Cvt->fits2ndf;

Retrieves the input filename from the object via the infile() method.

ndf2fits

Convert an NDF file to a FITS file.

hds2mef

Convert a HDS file into a multi-extension FITS file

gmef2hds

Convert a GEMINI multi-extension FITS file to an HDS container

ingmef2hds

Convert an ING format Multi-Extension FITS file into an HDS container.

UKIRTio2hds

Converts observations that are taken as a header file plus multiple NDFs into a single HDS container that contains a .HEADER NDF and .Inn NDFs for each of the nn data files. This is the scheme used for IRCAM and CGS4 data at UKIRT.

  $hdsfile = $Cvt->UKIRTio2hds;

This routine assumes the old UKIRT data acquisition system (at least for IRCAM and CGS4) is generating the data files. The name of the header file (aka the O-file) must be stored in the object (via the infile() method) before running this method. The I files are assumed to be in the directory ../idir relative to the header file with a starting character of ’i’ rather than ’o’ and are multiple files with suffixes of ’_1’, ’_2’ etc. The new output file is named ’cYYYYMMDD_NNNNN’ where the date is retrieved from the IDATE header keyword and observation number from the OBSNUM header keyword.

Returns undef on error.

hds2ndf

Converts frames taken as HDS container files (container file with .HEADER and .I1) to a simple NDF file. This method only works for the first frame (.I1).

  $ndf = $Cvt->hds2ndf;

If the input HDS has a .I1 component with FITS headers, then the resulting NDF file has the FITS headers from both the .HEADER and the .I1 components merged. Otherwise, the resulting NDF has the FITS headers from just the .HEADER component. No warning is given if more than one component exists (all higher numbers are ignored).

SEE ALSO

The Starlink CONVERT package.

COPYRIGHT

Copyright (C) 1998-2005 Particle Physics and Astronomy Research Council. All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA

D.7 ORAC::Core

Core routines for data pipelining

SYNOPSIS

  use ORAC::Core;

  orac_process_frame($CURRENT_RECIPE, $PRIMITIVE_LIST, $opt_showcurrent,  
                     $Frm, $Grp, $Cal,\%Mon,$OverRecipe, $instrument);

  orac_store_frm_in_correct_grp($Frm, $GrpType, $GrpHash, $GrpArr, $ut);

  orac_print_configuration( $opt_debug, $opt_showcurrent, $log_options,  
                            $win_str, \$STATUS_TEXT  );

  orac_message_launch( $opt_nomsgtmp, $opt_verbose );

  orac_start_algorithm_engines( $opt_noeng, $InstObj );

  orac_start_display( $nodisplay );

  orac_calib_override( $opt_calib, $calclass );

  orac_parse_files( $opt_files );

  orac_process_argument_list( $opt_from, $opt_to, $opt_skip, $opt_list,  
                               $frameclass );

  orac_main_data_loop( $opt_batch, $opt_ut, $opt_resume, $opt_skip,  
                       $opt_debug, $recsuffix, $grptrans,  
                       $loop, $frameclass, $groupclass,  
                       $instrument, $Mon, $Cal, \@obs, $Display, $orac_prt,  
                       $ORAC_MESSAGE, \$STATUS_TEXT, $PRIMITIVE_LIST,  
                       $Override_Recipe );
DESCRIPTION

This module contains the core routines that actually handle the data processing. Routines are provided for constructing groups and for processing those groups, along with routines to do the inital pipeline configuration and algorithm engine startup.

SUBROUTINES

The following subroutines are available:

orac_store_frm_in_correct_grp

Stores the supplied frame into a Grp (usually specified in the Frame), creating a new Group object if necessary. The Group objects are stored in a hash (reference supplied) and, optionally, an array (unless undef). This is so that Groups can be retrieved in the order in which they were created. The GrpType specifies the type of Group that should be created (eg ORAC::Group::UFTI, ORAC::Group::JCMT etc). The UT is supplied purely so that the Group can be named (using the file_from_bits() method).

  orac_store_frm_in_correct_grp($Frm, $GrpType, \%Groups, \@Groups,  
        $ut, $resume, $transient);  
  orac_store_frm_in_correct_grp($Frm, $GrpType, \%Groups, undef,  
        $ut, $resume, $transient);

The resume flag is used to determine the behaviour of the group when it is first created. If resume is false, any existing Group file is removed before proceeding; if it is true, the Group file is retained and any coadd information is read using the coaddsread() Group method.

The transient argument controls whether more than one group can be created. If transient is 1 only a single group is stored in %Groups, although multiple may be created during processing. If transient is -1 then only one group is ever created, and every Frame object goes into that group.

The current Grp (ie the Group associated with the supplied Frm) is returned.

orac_process_frame

This is the core ORAC-DR pipeline processing routine. It processes the supplied frame object that belongs to the group object, using the supplied calibration object. The instrument name and default recipe are required for recipe/primitive reading since recipes and primitives are stored in instrument specific directories. The %Mon hash is supplied so that a recipe has full access to all the monoliths launched for this instrument.

  orac_process_frame( CurrentRecipe => $STATUS_TEXT,  
                      PrimitiveList => $PRIMITIVE_LIST,  
                      Frame => $Frm,  
                      Group => $Grp,  
                      Calibration => $Cal,  
                      Engines =>\%Mon,  
                      Display => $Display,  
                      Beep => $opt_beep,  
                      Debug => $opt_debug,  
                      CmdLineRecipe => $Override_Recipe,  
                      Instrument => $instrument,  
                      Batch => 0,  
                      RecSuffix => "A,B,C",  
                      RecPars => $parameterfile,  
                      RecOpts => {},  
                     );

Additional parameters are provided to configure the recipe environment. Defaults are provided for Debug and Batch. (both false). Those options relate to the -debug and -batch command line options.

Returns the recipe exit status or throws an exception.

orac_print_config_with_defaults

Wrapper for the orac_print_configuration function, but including code to configure default logging switches before configuring the print system.

  my ($orac_prt, $msg_prt, $err_prt, $ORAC_MESSAGE,  
      $PRIMITIVE_LIST, $CURRENT_PRIMITIVE) =  
        orac_print_config_with_defaults( \$CURRENT_RECIPE,  
                                         \@ARGV, %cloptions );

@ARGV contains the command line arguments for the log file. %cloptions are the command line switches. -debug, -showcurrent and -log are used by this routine. -log will be read and modified to provide default behaviour.

orac_launch_tk

Attempt to load Tk and create a main window indexed by the identifying string.

  $w = orac_launch_tk($win_str, \%opt);

This routine can safely be called multiple times.

Returns the top level MainWindow object.

orac_declare_location

Write a file indicating where the pipeline is going to be writing any output data (ie ORAC_DATA_OUT). This file will be written into a directory obtained from the ORAC_LOCATION_DIR or else fall back to the default JAC location of "/jac_sw/oracdr-locations".

The file will be named for the ORAC_INSTRUMENT environment variable and any recipe suffices that are in use. For example "scuba2_450-ql". The file will contain one line with the value of $ORAC_DATA_OUT.

A file is only written if the UT date being used is the current UT date.

  orac_declare_location( %options );

where %options is the command line options hash.

orac_retrieve_location

Attempt to retrive the pipeline output directory from a file in ORAC_LOCATION_DIR. See orac_declare_location for the details of this file.

orac_print_configuration

This routine setups the orac print system, it takes the $opt_debug and $log_options and the $MW variable and determines which file handles to return

  my($orac_prt, $msg_prt, $msgerr_prt, $ORAC_MESSAGE,  
     $PRIMITIVE_LIST, $CURRENT_PRIMITIVE)  
     = orac_print_configuration(  
                                 $log_options, $win_str, \$CURRENT_RECIPE  
                                 \@ORAC_ARGS, %options  
                                );

The ORAC_ARGS are assumed to be the command line options. %options is the options hash. -debug and -showcurrent are used by this routine.

The tied file handles $orac_prt, $msg_prt and $msgerr_prt are returned, along with the Tk packed variable $ORAC_MESSAGE and a reference to arrays containing the primitive information.

orac_message_launch

This routine creates a message launch system object and configures it, we pass $opt_nomsgtmp and $opt_verbose to the routine to configure the object.

  orac_message_launch( $opt_nomsgtmp, $opt_verbose );

The message system itself will be initialised when it is required rather than at the start. If we know there is one messsys and we know that it will always be the same one then we can configure it here explicitly. The main reason for doing that is to make sure that it works before starting recipe processing.

orac_start_algorithm_engines

This routine pre-launches the relevant algorithm engines which are always required by the instrument

   my ( $Mon )  = orac_start_algorithm_engines( $opt_noeng, $InstObj );

it returns a reference to the algorithm engine hash, $Mon.

orac_start_display

This routine is a wrapper for the orac_setup_display() subroutine in ORAC::Basic. It starts the ORAC display unless $nodisplay is set.

   my $Display = orac_start_display( $nodisplay, %opt );

the routine returns the display object $Display.

Note that an object is returned in all cases, but if display is disabled the display is created in monitor mode.

Additional options are passed to orac_setup_display.

orac_calib_override

This routine creates a calibration object of the specified class and overrides methods as specified in the --calib option string.

   my $Cal = orac_calib_override( $calclass, @opt_calib, );

Multiple calibrations specifications can be supplied. The calibrations are specified as comma separated keyword=value strings or as hash references.

orac_parse_files

This routine parses the text file which has a list of the files to be processed, this should have one filename per line, filenames are assumed to be relative to ORAC_DATA_IN. If there are any duplicates an error will be thrown.

   my @obs = orac_parse_files( $opt_files );

it returns an array of files to be read.

"#" is a comment character.

orac_parse_recparams

Parse the command line argument specifying recipe parameters and return either a ORAC::Recipe::Parameters object or undef.

 $params = orac_parse_recparams( $params );
orac_process_argument_list

This routine checks that your data exists and decides which data loop approach to use.

 my $loop =  
     orac_process_argument_list( $frameclass, \@obs, %opt );

it returns the looping scheme and a list of observations if one does not already exist.

This routine is fairly complex since there are many combinations of -from, -to, -skip, -loop and -list that interact with each other.

The options hash may contain the following keys: from, to, skip, list and loop. All these are optional as the values may or may not be defined or supplied by the user.

orac_main_data_loop

This routine handles the main data processing.

  orac_main_data_loop( \%options, $loop, $instrument, \@obs,  
                       $Display, $orac_prt,  
                       $ORAC_MESSAGE, $CURRENT_RECIPE, \@PRIMITIVE_LIST,  
                       $CURRENT_PRIMITIVE, $Override_Recipe );

There are two approaches to the data processing.

(1)

The default processing method where data are read in and processed as it arrives and Groups are extended as needed. This has the advantage that the data is processed as it is taken, has very good feedback to the user in real time. The down side is that Groups are processed as soon as possible and in an off-line batch processing envrionment this is very wasteful (why work out the flatfield every time a frame arrives when you simply want to work out the flatfield from the entire group).

(2)

The "batch" method where the data are analysed in two passes. First the groups are setup, secondly the frames are processed in each group in turn. This has the advantage that frames can be coadded into a group only once and is the most efficient way of processing data off-line. Note that this presupposes that the primitives are written in such a way that they can spot the last member of the group (via the lastmember method). Grp Primitives without this check will probably fail since the some of the members will not have been processed even though the group contains many members.

One other issue is calibration -- in principal all calibration groups should be processed before observation groups and currently this is not supported (only important when calibrations are taken after the observation).

Batch mode can be summarised as

    - Read in all frames and allocate groups  
    - Loop over all groups Loop over all frames in  
      group process frames

Default mode is

    - Loop over all frames  
    - Allocate groups  
    - process frames

Batch mode can be turned on with the -batch switch.

Returns a hash containing information on the error status from all the frames that were processed. The hash can be analyzed using orac_print_recipe_summary.

orac_store_recipe_status

Translates a return status from "orac_process_frame" into a hash entry for tracking statistics, and recording the filenames where the processing failed or the supplied data were deemed bad.

  orac_store_recipe_status( \%ongoing, $status, $filename );
orac_print_recipe_summary

Print out the recipe summary using the hash generated by orac_store_recipe_status.

  $exstat = orac_print_recipe_summary( $color, \%Stats );

Returns 0 if all recipes processed successfully and non-zero if some failed. This value can be passed directly to exit().

Returns 0 if the stats hash is empty and -1 if no hash reference is supplied.

COPYRIGHT

Copyright (C) 2008-2010 Science and Technology Facilities Council. Copyright (C) 1998-2007 Particle Physics and Astronomy Research Council. All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA

D.8 ORAC::Display::Base

Base class for ORAC display interface

SYNOPSIS

  use ORAC::Display::Base;
DESCRIPTION

Provides the generic methods for handling ORAC Display devices. The generic routines (those worth inheriting) deal with display device name allocation (eg mapping a device number to a real device).

PUBLIC METHODS
Constructor 
new

Base class constructor. Can be called as SUPER::new() from sub-classes. Accepts a configuration hash as input in order to initialise extra instance data components of the class that are required by sub-classes.

  $a = new ORAC::Display(a => ’b’, c => ’d’);

This constructor does not attempt to launch a display device. That is up to the sub-classes.

Accessor Methods 
dev

Method for handling the hash of device name mapping. ie Which device name (as required for each Display interface, eg ’.rtd0’, ’xwindows;$$’) is associated with the ORAC name (eg ’0’,’1’,’default’).

The hash reference is returned when called with no arguments:

  $href = $self->dev;

The value associated with the supplied key is returned if one argument is provided:

  $value = $self->dev(’key’);

The supplied value is stored in key if two arguments are supplied:

  $self->dev(’key’,’value’);

Undefined values are accepted.

General Methods 
window_dev

Returns the device id (eg GWM device name or RTD window name) associated with window ’win’. If ’win’ is undefined a new window is launched, the id stored in the hash and the new id returned. (see the launch_dev() method). If this is the first time the routine is called (ie the only window name present is ’default’, the name of the default window is associated with window win.). We go through this hoop so that devices will open a window before the user has associated their user-defined name with the actual window name.

  $name = $self->window_dev(’win’);

If the windows were launched with bad status we should set the device name to something recognisable as bad since status is not returned.

SEE ALSO

ORAC::Display::GAIA, ORAC::Display::KAPVIEW

COPYRIGHT

Copyright (C) 1998-2000 Particle Physics and Astronomy Research Council. All Rights Reserved.

D.9 ORAC::Display::GAIA

ORAC interface to GAIA

SYNOPSIS

  $disp = new ORAC::Display::GAIA;

  $disp->image($file);
DESCRIPTION

ORAC interface to the the GAIA (ESO Skycat) display tool. Provides methods for displaying images.

Available options are:

IMAGE - display image in GAIA window

PUBLIC METHODS
Constructor 
new

Object constructor. The constructor starts up a new version of GAIA (if one is not running) and connects via a socket.

The program aborts if there is an error launching or contacting gaia.

Accessor Methods 
launchable

Whether or not GAIA can be automatically launched.

  $gaia->launchable( 0 );

Defaults to true. If this is set to false (0), then a new GAIA will never be started.

sock

Returns or sets the socket to Gaia. Private to this class.

  $sock = $gaia->sock();

This is usually IO::Socket object. This socket is automatically added to the IO::Select object returned by the sel method. (and all previous sockets registered with the IO::Select object are removed).

sel

Returns the IO::Select object associated associated with the current socket.

  $select = $gaia->sel();

This object is used to determine whether the GAIA process can be contacted through the established socket connection.

use_remote_gaia

Controls whether we are allowed to connect to a GAIA process that is already running on a remote machine. By default this is allowed (true) but in some cases you may not want to connect to a remote GAIA. For example, at UKIRT, the display must be sent to the machine running the pipeline and not one of the other GAIAs that are running on separate machines for QuickLook and general data inspection.

General Methods 
create_dev

Clone a new GAIA window and associate it with ’win’. This is different to launching a new display device (ie running up GAIA itself).

  $status = $Display->create_dev($win, $name);

For GAIA (V <= 2.3-2) the device name ($name) must be an integer. (enforced if the newdev() method is used).

ORAC status is returned.

launch

Connect to a pre-existing Gaia process or launch a new Gaia process. If the first connection attempt fails, launches a new gaia process. After this, attempts to connect to a new gaia process every 3 seconds and attempts to launch a new gaia process every 60 seconds. A maximum of 5 attempts are made (5 minutes) to launch a new Gaia process before giving up.

There is no return status -- the program croaks if it can not get a connection to GAIA !!

Whilst it is waiting, does not attempt to keep a Tk event loop running.

configure

Load the startup image into GAIA. Essentially used to test that GAIA can display images correctly.

Returns ORAC status.

send_to_gaia

Sends the supplied command to gaia. Any response from Gaia is returned.

  ($status, $return_string) = $obj->send_to_gaia(’command’);  
  ($status, @return_strings) = $obj->send_to_gaia(@commands);

The returned status is translated into an ORAC status (either ORAC__OK or ORAC__ERROR). On error, the return_string contains the error message. The status returned is the status of the last command processed by GAIA.

newdev

Returns the name to be used for the new GAIA window based on the supplied window name.

   $name = $obj->newdev($win);

Currently, for gaia, the argument is ignored. The name is simply returned as an integer calculated from the number of devices already stored in the object.

DISPLAY METHODS
image

Routine to display images in Gaia. Note that the full file name is required. If an image name does not include an extension then ’.sdf’ is appended. (ie NDF is assumed).

Takes a file name and arguments stored in a hash.

  $disp->image("filename", \%options)  
  $disp->image("filename", { WINDOW => 2 });

Currently no image sectioning is supported. Display range can be adjusted with ZAUTOSCALE, ZMIN and ZMAX.

Component can be selected with COMP option. DATA is the default. QUALITY and VARIANCE are supported.

Note that for GAIA, ZAUTOSCALE implies a 95 percent cut level and not 100 percent.

Will attempt to relaunch GAIA if it can not be contacted. Will attempt to create a new clone window if a clone can not be contacted even though it has been used previously.

ORAC status is returned.

SEE ALSO

ORAC::Display::Base, ORAC::Display::KAPVIEW, ORAC::Display, IO::Socket

COPYRIGHT

Copyright (C) 1998-2000 Particle Physics and Astronomy Research Council. All Rights Reserved.

D.10 ORAC::Display::KAPVIEW

ORAC-DR interface to Kapview (KAPPA)

SYNOPSIS

  use ORAC::Display::KAPVIEW;  
  $disp = new ORAC::Display::KAPVIEW;

  $disp->image($file, { XAUTOSCALE => 1});
DESCRIPTION

ORAC interface to KAPPA Kapview. Provides methods for displaying images and spectrum with Kapview.

Available options are:

 IMAGE - display image using DISPLAY  
 GRAPH - display graph using LINPLOT  
 SIGMA - display scatter plot with a Y-range of +/- N sigma.  
 DATAMODEL - Display data (as points) with a model overlaid  
 HISTOGRAM - Histogram of values in data array  
 VECTOR - Display image + vectors
PUBLIC METHODS
Constructor 
new

Object constructor. The constructor starts up a new version of kapview, starts a GWM window and displays the startup logo.

The program aborts if there is an error launching kapview.

The message system must be running so that Kapview can be configured. (AMS is started if needed.)

Accessor Methods 
engine_launch_object

Returns the ORAC::Msg::EngineLaunch object that can be used to launch algorithm engines as required by the particular conversion.

 $messys = $self->messys_launch_object;
kappa

Messaging object associated with the kappa_mon monolith. This is used by some of the modes in order to determine display related values (e.g. statistics to determine plotting ranges for SIGMA, dimension compression with COMPAVE).

A KAPPA messaging object is created if the object is undefined.

Note also that the HISTOGRAM task is present in the KAPPA monolith rather than in the KAPVIEW monolith.

ndfpack

Messaging object associated with the ndfpack_mon monolith. This is used by some of the modes in order to reshape date arrays (e.g. in SIGMA mode - reshape is run to convert to 1-d).

A NdfPack messaging object is created if the object is undefined.

polpack

Messaging object associated with the polpack_mon monolith. This is used by the VECTOR mode to plot vectors from catalogues.

Note that this is technically not part of the KAPVIEW system. It is here for convenience since in all cases POLPLOT is better than VECPLOT for vector plotting.

A Polpack messaging object is created if the object is undefined.

Returns undef if polpack_mon is not available.

regions

A hash containing the mapping of region name (number) to AGI picture label.

Returns hash reference in scalar context, full hash in array context. Contents can be modified by directly using the hash reference (in order to modify specific entries) or completely rewritten by supplying a hash as argument.

  $hashref = $self->regions;  
  %hash = $self->regions;  
  $self->regions(%hash);  
  $self->regions->{Key} = "value";
lookup_table

Set or retrieve the previous lookup table.

obj

Messaging object associated with the Kapview display object.

General Methods 
newdev

Given ’win’, calculates a new device name that should be unique for each ’win’.

 $dev = $Display->newdev($win);
calc_centre_region
create_dev

Start the GWM window associated with the supplied window. In general this is used by the startup configuration. The lookup table is configured by this routine (so that this routine really does start the GWM window).

Currently the GWM window itself is not started directly by this routine (since KAPVIEW will automatically open the specified device if one is not running).

The only reason to use this routine to actually START a window is that it will give us some control over the colour allocation and allow us to set the window name.

ORAC status is returned.

  $status = $Display->create_dev($win);

Currently, the method dies if the device can not be successfully created.

launch

This method starts the kapview monolith and stores the associated Task object.

configure

Load a startup image. This tests the system to make sure that images can be displayed and that the colour map is loaded.

Returns ORAC status.

config_regions

This method configures the display regions so that they can be selected later by select_region.

  $status = $self->config_regions($window);

A window name must be supplied.

The regions are defined as follows:

  0 - full screen  
  1 - top left  
  2 - top right  
  3 - bottom left  
  4 - bottom right  
  5 - left  
  6 - right  
  7 - top  
  8 - bottom  
  17:32 - position in 4x4 grid (starting top left)

The picture labels are stored in the regions() array.

select_region

Selects the requested region as the current region in the display system by using a supplied hash.

  $device = $Display->select_region(%options);

Returns undef without action if the REGION keyword is not available (since have no idea where to put it) or if REGION is not in the allowed range. Otherwise the name of the device containing the selected region is returned. undef is returned if no arguments are supplied.

If the window name is not supplied (WINDOW) then ’default’ is assumed.

select_section

This method converts a file name and options hash into a filename with an attached NDF section.

  $newfile = $Display->select_section($file, \%options, $dimensionality);

An optional 3rd argument can be used to specify the required dimensionality. If the number of dimensions in the data file is greater than that requested, sections in higher dimensions are set to 1 by compressing the undesired dimension (with the assumption that KAPPA will discard axes with 1 pixel). The desired dimension is specified with the CUT option. For example, a graph can be displayed from a 2-D image by displaying a cut in the X direction (averaging over the Ys).

If the number of dimensions in the data file is fewer than that requested, a warning message is printed but we continue in the hope that KAPPA will work something out....

The return value is the original filename with the NDF section attached.

Relevant keywords in options hash:

  CUT  - Specify the significant dimension[s] (X,Y,3,4,5)  
         Should be a comma-separated list specifying  
         dimensionality - number of entries should equal the  
         requested dimensionality. For a graph only 1 value  
         is required since a graph is 1-D  
  XMIN/XMAX - X pixel max and min values  
  YMIN/YMAX - Y pixel max and min values  
  XAUTOSCALE - Use autoscaling for X?  
  YAUTOSCALE - Use autoscaling for Y?

If Xautoscale and Yautoscale are true, no section command is appended. If the XAUTOSCALE/YAUTOSCALE/nAUTOSCALE keywords can not be found they are assumed to be true. If CUT is not specified the first slice is selected (e.g. a NDF section of N,1,1,1).

For data arrays with N >2, the leading letter is dropped and replaced by the dimension number. For example,

  3MIN/3MAX - pixel range of the 3rd dimension  
  4AUTOSCALE - autoscale the 4th dimension?

For NDFs the maximum dimensionality is 7.

The bounds of the input file are compared to the supplied bounds. If any of the requested bounds are exceeded, the maximum value will be used instead.

Returns undef on error. The unmodified file name is returned if no options hash can be found.

Returns the following:

  No CUT requested + auto-scaling  
    returns the original filename.  
  No CUT requested + some dimension ranges specified  
    returns the original filename with an NDF section.  
    Dimensions above the requested dimensionality are set to the  
    min value in the section (1 if not specified)  
  CUT requested but dimensionality of data matches requested  
    dimensionality.  
    Just return the file + any relevant section  
  CUT + auto-scaling + image too large  
    Data file is collapsed down to required size keeping the specified  
    dimensions and averaging over the rest. A new temporary filename  
    is returned.  
  CUT + some ranges specified + image too large  
    NDF section constructed and then the data file is collapsed  
    down to the required size. A new temporary file is generated.  
  CUT + range + image + one pixel selected  
    If the non-cut dimensions have min=max a section is  
    sufficient and no averaging required.

The temporary files themselves are added to a global class array and removed by the destructor.

Note that this routine does not remove the temporary filename. This is probably a bug. Should probably create some kind of object that will have a destructor that removes the file rather than using a simple file name. (an ORAC::TempFile)?

set_lut

Set the given LUT.

  $status = $Display->set_lut($device, $lut);

This method also calls lookup_table to store the name of the specified LUT.

DISPLAY METHODS
image

Display an image. Takes a file name and arguments stored in a hash. Note that currently it does not take a format argument and NDF is assumed.

Recognised options:

  XMIN/XMAX - X pixel max and min values  
  YMIN/YMAX - Y pixel max and min values  
  XAUTOSCALE - Use autoscaling for X?  
  YAUTOSCALE - Use autoscaling for Y?  
  ZMIN/ZMAX  - Z-range of greyscale (data units)  
  ZAUTOSCALE - Autoscale Z?  
  KEY        - Display key to colour table?  
  COMP       - Component to display (Data (default), Variance or Error)  
  LUT        - Color lookup table name [default: ’bgyrw’]  
  BADCOL     - Bad color name [default: ’grey50’]

Default is to autoscale.

ORAC Status is returned.

graph

Display a 1-D plot.

If the data are not 1-D, a section is taken that assures 1-D (e.g. NDF section= :,1,1,1 for 4D data).

Takes a file name and arguments stored in a hash. Note that currently it does not take a format argument and NDF is assumed.

Display keywords:

  XMIN/XMAX  - X-pixel range of graph  
  XAUTOSCALE - Autoscale pixel range?  
  YMIN/YMAX  - Y-pixel range of graph (in pixels)  
  YAUTOSCALE - Autoscale Y-axis  
  YMIN/YMAX  - Z-range of graph (in data units)  
  YAUTOSCALE - Autoscale Z-axis  
  CUT        - Decide which direction is the primary axis  
               Can be X,Y,3,4,5 (for higher-dimensional data sets)  
               For a 1-D data set (or section), this value is ignored  
  COMP       - Component to display (Data (default), Variance or Error)  
  ERRBAR     - Plot error bars or not (if variance information is  
               present)  
  YLOG       - Plot Y-axis on a logarithmic scale  
  MULTILINE  - Plot multiple lines (using mlinplot)  
  ABSAXIS    - Axis selection (when using MULTILINE)  
  HLRANGE    - Range (NDF section axis specifier) to highlight

Default is to autoscale. Note that the X/Y cuts are converted to a 1-D slice before displaying by averaging over the section.

For example:

   XMIN=5 XMAX=5 YAUTOSCALE=YES

would display column 5 (i.e. the whole of Y for X=5). [CUT is irrelevant since the resulting image section is 1-D], and

   XAUTOSCALE=YES YMIN=20 YMAX=30 CUT=X

would display the average of rows 20 to 30 for each X.

Need to add way of controlling line style (e.g. replace with symbols)

ORAC status is returned.

chanmap

Displays a channel map of a central region of a cube.

Recognized options:

  XMIN/XMAX  - X pixel min and max values.  
  YMIN/YMAX  - Y pixel min and max values.  
  ZMIN/ZMAX  - Z-range of greyscale (data units)  
  XAUTOSCALE - Use autoscaling for X?  
  YAUTOSCALE - Use autoscaling for Y?  
  ZAUTOSCALE - Use autoscaling for Z?  
  WIDTH      - Width of central region to use, in percent.  
  AXIS       - Axis to collapse over.  
  NCHAN      - Total number of channels to display.  
  SHAPE      - Number of channels to display along X-axis.

WIDTH defaults to 100. AXIS defaults to 3. NCHAN defaults to 9. SHAPE defaults to 3.

ORAC status is returned.

cubecentre

Collapse the central region of a cube along one axis, and display an image of the collapse region.

Recognised options:

  XMIN/XMAX  - X pixel min and max values.  
  YMIN/YMAX  - Y pixel min and max values.  
  ZMIN/ZMAX  - Z-range of greyscale (data units)  
  XAUTOSCALE - Use autoscaling for X?  
  YAUTOSCALE - Use autoscaling for Y?  
  ZAUTOSCALE - Use autoscaling for Z?  
  WIDTH      - Width of central region to use, in percent.  
  AXIS       - Axis to collapse over.

WIDTH defaults to 100. AXIS defaults to 3.

ORAC status is returned.

contour

Display contours of a 2-D data set.

Recognised options:

  XMIN/XMAX - X pixel max and min values  
  YMIN/YMAX - Y pixel max and min values  
  XAUTOSCALE - Use autoscaling for X?  
  YAUTOSCALE - Use autoscaling for Y?  
  ZMIN/ZMAX  - Z-range of greyscale (data units)  
  ZAUTOSCALE - Autoscale Z?  
  NCONT      - Number of contours  
  COMP       - Component to display (Data (default), Variance or Error)  
  KEY        - Display key to contour levels?

Default is to autoscale.

ORAC status is returned.

sigma

Display a scatter plot of the data with Y range of N-sigma (sigma is derived from the data) with dashed lines overlaid at the X-sigma points.

By default a range of +/-5 sigma with dashed lines at +/-3 sigma are used.

These values can be overriden by using the RANGE and DASHED keywords.

Takes a file name and arguments stored in a hash. Note that currently it does not take a format argument and NDF is assumed.

If we are running KAPPA 0.13, the NDF is converted to 1-DIM with the KAPPA/RESHAPE command before displaying.

ORAC status is returned.

datamodel

Display mode where the supplied filename is plotted as individual points and a model is overlaid as a solid line. This can be used to determine the goodness of fit of data and model.

The model filename is derived from the input filename (a _model extension is expected). The data are displayed if the model file can not be found.

Takes a file name and arguments stored in a hash. Note that currently it does not take a format argument and NDF is assumed.

Option keywords:

  XMIN/XMAX  - X-pixel range of graph  
  XAUTOSCALE - Autoscale pixel range?  
  ZMIN/ZMAX  - Y-range of graph (in data units)  
  ZAUTOSCALE - Autoscale Y-axis  
  COMP       - Component to display (Data (default), Variance or Error)

Default is to autoscale on the data (the model may not be visible).

If the input file is greater than 1-D, the section is automatically converted to 1-D by selecting the ?MIN slice from each of the higher axes (e.g. the value specified in YMIN, 3min...).

ORAC status is returned.

histogram

Display a histogram of the data values present in the data array.

Takes a file name and arguments stored in a hash. Note that currently it does not take a format argument and NDF is assumed.

Arguments:

  XMIN/MAX   - minimum/maximum x-pixel value  
  XAUTOSCALE - Use full X-range  
  YMIN/YMAX  - minimum/maximum x-pixel value  
  YAUTOSCALE - use full Y-range  
  ZMIN/ZMAX  - Z range of histogram (data units)  
  ZAUTOSCALE - use full Z-range  
  NBINS      - Number of bins to be used for histogram calculation  
  COMP       - Component to display (Data (default), Variance or Error)  
  SIGMA      - Number of sigma to clip data before computing histogram  
  TITLE      - title string to label the histogram

Default is for autoscaling and for NBINS=20. Note that the presence of SIGMA overrides ZMIN/ZMAX.

ORAC status is returned.

vector

Vectors are overlaid on an image. The supplied file is displayed and vectors are then drawn. The vector information is expected to be stored in the ORAC extension of the supplied file (in .P and .THETA NDFs) or, preferably, in a catalogue of the same name as the I image. POLPLOT is used for display if the catalogue is available.

Recognised options:

  XMIN/XMAX  - X pixel max and min values  
  YMIN/YMAX  - Y pixel max and min values  
  XAUTOSCALE - Use autoscaling for X?  
  YAUTOSCALE - Use autoscaling for Y?  
  ZMIN/ZMAX  - Z-range of greyscale (data units)  
  ZAUTOSCALE - Autoscale Z?  
  ANGROT     - angle to add to all vectors  
  MULTIVECTOR- Plot multi-coloured vectors (yellow with blue trim)?

Default is to autoscale.

ORAC status is returned.

SEE ALSO

ORAC::Display, ORAC::Display::GAIA

COPYRIGHT

Copyright (C) 1998-2000 Particle Physics and Astronomy Research Council. All Rights Reserved.

D.11 ORAC::Error

Exception handling in an object orientated manner.

SYNOPSIS

    use ORAC::Error qw /:try/;  
    use ORAC::Constants qw /:status/;

    # throw an error to be caught  
    throw ORAC::Error::UserAbort( $message, ORAC__ABORT );  
    throw ORAC::Error::FatalError( $message, ORAC__FATAL );

    # record and then retrieve an error  
    do_stuff();  
    my $Error = ORAC::Error->prior;  
    ORAC::Error->flush if defined $Error;

    sub do_stuff {  
        record ORAC::Error::FatalError( $message, ORAC__FATAL);  
    }

    # try and catch blocks  
    try {  
       stuff();  
    }  
    catch ORAC::Error::UserAbort with  
    {  
        # normally we just want to catch and then ignore UserAborts  
        my $Error = shift;  
        orac_exit_normally();  
    }  
    catch ORAC::Error::FatalError with  
    {  
        # its a fatal error  
        my $Error = shift;  
        orac_exit_normally($Error);  
    }  
    otherwise  
    {  
       # this block catches croaks and other dies  
       my $Error = shift;  
       orac_exit_normally($Error);  
    }; # Don’t forget the trailing semi-colon to close the catch block
DESCRIPTION

ORAC::Error is based on a modifed version of Graham Barr’s Error package, and more documentation about the (many) features present in the module but currently unused by ORAC-DR can be found in the documentation for that module.

As with the Error package, ORAC::Error provides two interfaces. Firstly it provides a procedural interface to exception handling, and secondly ORAC::Error is a base class for exceptions that can either be thrown, for subsequent catch, or can simply be recorded.

If you wish to throw an FatalError or UserAbort then you should also use ORAC::Constants qw / :status / so that the ORAC constants are available.

PROCEDURAL INTERFACE

ORAC::Error exports subroutines to perform exception handling. These will be exported if the :try tag is used in the use line.

try BLOCK CLAUSES

try is the main subroutine called by the user. All other subroutines exported are clauses to the try subroutine.

The BLOCK will be evaluated and, if no error is throw, try will return the result of the block.

CLAUSES are the subroutines below, which describe what to do in the event of an error being thrown within BLOCK.

catch CLASS with BLOCK

This clauses will cause all errors that satisfy $err- >isa(CLASS) to be caught and handled by evaluating BLOCK.

BLOCK will be passed two arguments. The first will be the error being thrown. The second is a reference to a scalar variable. If this variable is set by the catch block then, on return from the catch block, try will continue processing as if the catch block was never found.

To propagate the error the catch block may call $err- >throw

If the scalar reference by the second argument is not set, and the error is not thrown. Then the current try block will return with the result from the catch block.

otherwise BLOCK

Catch any error by executing the code in BLOCK

When evaluated BLOCK will be passed one argument, which will be the error being processed.

Only one otherwise block may be specified per try block

CLASS INTERFACE
CONSTRUCTORS  The ORAC::Error object is implemented as a HASH. This HASH is initialized with the arguments that are passed to it’s constructor. The elements that are used by, or are retrievable by the ORAC::Error class are listed below, other classes may add to these.
        -file  
        -line  
        -text  
        -value
If -file or -line are not specified in the constructor arguments then these will be initialized with the file name and line number where the constructor was called from.

The ORAC::Error package remembers the last error created, and also the last error associated with a package.

throw ( [ ARGS ] )

Create a new ORAC::Error object and throw an error, which will be caught by a surrounding try block, if there is one. Otherwise it will cause the program to exit.

throw may also be called on an existing error to re-throw it.

with ( [ ARGS ] )

Create a new ORAC::Error object and returns it. This is defined for syntactic sugar, eg

    die with ORAC::Error::FatalError ( $message, ORAC__FATAL );
record ( [ ARGS ] )

Create a new ORAC::Error object and returns it. This is defined for syntactic sugar, eg

    record ORAC::Error::UserAbort ( $message, ORAC__ABORT )  
        and return;
METHODS 
prior ( [ PACKAGE ] )

Return the last error created, or the last error associated with PACKAGE

    my $Error = ORAC::Error->prior;
flush ( [ PACKAGE ] )

Flush the last error created, or the last error associated with PACKAGE.It is necessary to clear the error stack before exiting the package or uncaught errors generated using record will be reported.

    $Error->flush;
OVERLOAD METHODS 
stringify

A method that converts the object into a string. By default it returns the -text argument that was passed to the constructor, appending the line and file where the exception was generated.

value

A method that will return a value that can be associated with the error. By default this method returns the -value argument that was passed to the constructor.

PRE-DEFINED ERROR CLASSES
ORAC::Error::FatalError

Used for fatal errors where we want the pipeline to die with cause. This class can be used to hold simple error strings and values. It’s constructor takes two arguments. The first is a text value, the second is a numeric value, ORAC__FATAL. These values are what will be returned by the overload methods.

ORAC::Error::UserAbort

Used for user generated pipeline aborts, which are handled slightly differently than fatal errors generated by the pipeline itself. The constructor for a UserAbort is similar to that for a FatalError except that the numeric value ORAC__ABORT is passed.

ORAC::Error::TermProcessing

Terminate processing of this recipe but continue on as if everything is fine. This can be used to stop a recipe early but will not trigger any long term errors to propagate through the pipeline.

ORAC::Error::TermProcessingErr

As for TermProcessing except that whilst the pipeline will continue to run the exit status of the pipeline will be non-zero to indicate that a problem was found. This can be used when the pipeline can work around the problem but would like the final exit status to reflect that there is a problem to be investigated.

KNOWN PROBLEMS

ORAC::Error which are thrown and not caught inside a try block will in turn be caught by Tk::Error if used inside a Tk environment, as will croak and die. However if is a croak or die is generated inside a try block and no otherwise block exists to catch the exception it will be silently ignored until the application exits, when it will be reported.

ACKNOWLEDGMENTS

This class is a slightly modified, with the addition of the flush method, version of Graham Barr’s (gbarr@pobox.com) Error class. That code was in turn based on code written by Peter Seibel (peter@weblogic.com) and Jesse Glick (jglick@sig.bsh.com).

D.12 ORAC::Inst::Defn

Definition of instrument class dependencies

SYNOPSIS

  use ORAC::Inst::Defn;

  @pars = orac_determine_inst_classes( $instrument );  
  orac_determine_initial_algorithm_engines  
  orac_determine_recipe_search_path  
  orac_determine_primitive_search_path  
  orac_engine_description  
  orac_messys_description  
  orac_configure_for_instrument( $instrument, \%options );
DESCRIPTION

This module provides all the instrument specific initialisation information. This is the information required by ORAC-DR in order to configure itself before the data detection loop can begin.

This module provides information on class hierarchies, recipe search paths and initialisation or algorithm engines.

All instrument dependencies are specified in this module.

FUNCTIONS

The following functions are provided:

orac_determine_inst_classes

Given an ORAC instrument name, returns the class names to be used for frames, groups, calibration messaging. The classes are used so that objects can be instantiated immediately.

  ($frameclass, $groupclass, $calclass, $instclass) =  
        orac_determine_inst_classes( $instrument );

The function dies if the classes can not be used. An empty list is returned if the instrument is not known to the system.

Returns the Frame class in scalar context.

orac_list_generic_observing_modes

Returns a list of the standard observing modes supported by ORAC-DR. Currently the list includes just "imaging" and "spectroscopy" (implicitly assumed to be near-infrared).

Specific instruments always have their own modes.

The list is determined by looking in the recipe directory for directories that contain all lower case characters. Upper case characters imply a specific instrument rather than a generic mode. This is probably over-the-top given that the search path functions (below) have to assume that they know the answer.

orac_determine_recipe_search_path

Returns a list of directories that should be searched in order to locate recipes for the specified instrument.

  @paths = orac_determine_recipe_search_path( $instrument );

Root location is specified by the ORAC_DIR environment variable.

Any instruments that start with "PICARD" will only include the PICARD search paths.

orac_determine_primitive_search_path

Returns a list of directories that should be searched in order to locate primitives for the specified instrument.

  @paths = orac_determine_primitive_search_path( $instrument );

Root location is specified by the ORAC_DIR environment variable.

orac_determine_calibration_search_path

Returns a list of directories that should be searched in order to locate calibration files for the specified instrument.

  @paths = orac_determine_calibration_search_path( $instrument );

Root location is specified by the ORAC_CAL_ROOT environment variable. ORAC_DATA_CAL is included if it is set explicitly.

orac_determine_initial_algorithm_engines

For the supplied instrument name, returns a list containing the names of engines to be launched by the pipeline prior to executing any recipes. This is used so that engines that are always used will be available at the start of execution rather than being launched on demand. This approach provides a slight efficiency gain over starting each engine on demand.

  @engines = orac_determine_initial_algorithm_engines( $instrument)

In principal this list can be empty if no pre-launching is required.

orac_configure_for_instrument

This routines configures the user environment (e.g. %ENV) for the instrument, it is called by Xoracdr to replace functionality present in the c-shell setup scripts.

   orac_configure_for_instrument( $instrument, \%options );
orac_guess_instrument

Given a Frame object (assumed to be a generic type frame with a translated FITS header) make a guess at the corresponding ORAC_INSTRUMENT that should be used.

  $guess = orac_guess_instrument( $Frm );

Useful for converting a base class or a PICARD variant to a specific type.

Returns undef if none can be guessed.

orac_engine_description

Returns the details for a specified algorithm engine.

  %details = orac_engine_description("polpack_mon");

The hash that is returned contains information on the class to be used to launch the engine and the location of the engine. In future it may also return the messaging system required for the engine to function. The hash currently has the following keys

CLASS

The name of the class to be used for this engine. (e.g. ORAC::Msg::Task::ADAM).

PATH

The location of the engine in the file system. If this is a code reference it should be executed immediately prior to launching the monolith to configure associated parameters correctly and to return the actual path. Additionally, if the helper task is executed it returns a reference to a cleanup subroutine. See §D.12.

MESSYS

The name of the message system required to contact the engine. See orac_messys_description below for details.

Returns an empty list on error.

orac_messys_description

Returns the details for a specified message system.

  %details = orac_messys_description("AMS");

The hash that is returned contains information on the class to be used to initialise the message system. It has the following keys

CLASS

The name of the class to be used for this message system (e.g. ORAC::Msg::ADAM::Control).

Returns an empty list on error.

HELPER TASKS

Some algorithm engines need to be configured in a slighlty more complex way than providing a simple path to the engine. This section describes specific functions that return the name of the path whilst also configuring the program before launch. For example, can be used to create a temporary directory for special output. The helper tasks accept no arguments and are required to return a path to an engine and a reference to a subroutine to be exected when the object has been launched. This allows for cleanup code to be executed and are usually closures.

p4_helper

Helper task for the CGS4-DR P4 display system.

  ($path, $cleanup) = p4_helper;
COPYRIGHT

Copyright (C) 1998-2006 Particle Physics and Astronomy Research Council. All Rights Reserved.

D.13 ORAC::Msg::EngineLaunch

Launch engines on demand

SYNOPSIS

  use ORAC::Msg::EngineLaunch;

  $eng = new ORAC::Msg::EngineLaunch;

  $obj = $eng->engine("polpack_mon");  
  $eng->detach("polpack_mon");  
  (@ok, @nok) = $eng->contact_all;

  tie %Mon, "ORAC::Msg::EngineLaunch";  
  $obj = $Mon{"polpack_mon"};  
  delete $Mon{"polpack_mon"};
DESCRIPTION

This class provides a means of launching arbritrary algorithm engines on demand. If an engine has not previously been launched the class will start it, if it has been launched it will retrieve the current object. The algorithm engines will be ORAC::Msg task objects (eg ORAC::Msg::ADAM::Task). This allows engines to be launched only when required to minimize resource demand.

It is also possible to tie the class to a hash. This allows for a non-object oriented approach where the engine can be launched simply by accessing the engine through the hash.

METHODS

The following methods are provided: Constructor  Object constructors.

new

Instantiate a new object ready for launching.

  $launch = new ORAC::Msg::EngineLaunch( $unique );

Since, in general, it is convenient for all parts of the code to have access to previously launched engines, the default behaviour is for the constructor to return the same object reference each time it is called. If it is required for a completely new object to be created each time the argument must be set to true.

ORAC-DR usually requires that access is provided to all previously launched engines for efficiency (and to prevent name clashes).

Accessor Methods 
engine

Retrieve the object associated with the specified engine, launching it if required.

  $obj = $launch->engine("polpack_mon");

undef is returned if the engine could not be launched.

The engine object can be stored if two arguments are used. A rudimentary check is made to make sure that the object is a reference and that the contactw method is supported. It is not possible to check a true ISA relationship. If the object does not satisfy this condition it is not stored and a warning is raised with "-w".

  $launch->engine("polpack_mon", $object);

Returns a hash reference containing all the currently launched engines if called without arguments.

  $launched = $launch->engine;
engine_id

The message system identifier. This is used by some message systems (e.g. ADAM) to indicate a specific identifier that should be used to name the engine in the message system. This allows, for example, the pipeline to attach to an engine that has been launched outside of the pipeline infrastructure. For engines launched by the pipeline each new identifier must be unique for each pipeline and for each repeat monolith launch (in the case where engines die and are restarted).

This method is used to store the previous id for each engine so that a new id can be generated.

  $id = $launch->engine_id( $engine );  
  $launch->engine_id( $engine, $id );

The engine_inc method should be used to generate a new id.

If no arguments are supplied a reference to the hash of IDs is returned. undef is returned if an id is requested for an engine that has not been launched.

messys_launch_object

Returns the ORAC::Msg::MessysLaunch object that can be used to initialise message systems as required by the particular algorithm engines.

 $messys = $self->messys_launch_object;
General Methods 
contact_all

Runs the contactw method on each registered engine. Can be used to make sure that all the registered engines are okay. If an engine can not be contacted it is removed from the object.

Returns two arrays, one for engines that could be contacted and one for engines that could not be contacted.

  ($okay, $notokay) = $launch->contact_all;

In a scalar context simply returns true if all engines could be contacted. Also returns true if there are no registered engines.

  $all_okay = $launch->contact_all;

The message system timeout is reduced to 30 seconds whilst waiting for contact. It is subsequently reset afterwards. This allows the pipeline configuration of timeout to vary from that required simply to check that the monolith can be contacted.

detach

Disassociate the named engine from the object. This can be used if an engine has crashed and it is necessary to launch a new engine next time.

  $launch->detach( $engine );
launch

Launch the specified monolith.

  $obj = $launch->launch( $engine );

The engine object is stored in the class. Returns undef on error.

The routine does not return until the engine has completed loading (i.e. the contactw method returns successfully). This is less efficient than launching all the monoliths and then waiting for them but it is the price paid for launching on demand.

This overhead can be overcome by pre-launching engines that are known to be required and launching optional engines on demand. If multiple engine names are supplied to this method they will all be launched at once without waiting for each one in turn. A hash is returned containing all the objects that were launched.

  %obj = $launch->launch( $engine1, $engine2 );

If multiple engines are launched simultaneously, the status of the engines must then be checked explicitly using the contact_all method.

If the engines are launched outside this infrastructure they can be registered with the object using the engine method for the object, and engine_id method to register the messaging name (if appropriate).

If a request is made to launch an engine that has been launched previously the request returns the current engine object. Use detach to force a reload.

engine_inc

Return a new ID for the specified engine.

  $id = $self->engine_inc( $engine );

The current ID is updated (see engine_id for more details).

TIED INTERFACE

This class also provides a means of tieing an object to a standard perl hash allowing for transparent access to engines.

A hash can be tied to an object by using the tie function:

  tie %Mon, "ORAC::Msg::Engine::Launch";

It is also possible to tie a hash to an existing object:

  tie %Mon, ref($object), $object;

The following can be used to retrieve the object associated with "polpack_mon" launching the engine if necessary:

  $object = $Mon{"polpack_mon"};

Engines can be dissassociated from the object using the standard hash delete command:

  delete $Mon{"polpack_mon"};

exists, keys and each are supported.

Note that exists will not launch a monolith. It can only be used to check that one has already been launched.

In addition, it is possible to explicitly set entries in the hash. A rudimentary check is made to check that the stored entry is an object that can invoke a "contactw" method but it is not possible to check that the object is of the correct type (since there is currently no complete inheritance tree for engines). If the argument is not okay the object a warning will be issued under "-w".

  $Mon{engine} = $some_object;

A reference to the hash still has access to the tied hash. A copy of the hash (e.g. %New = %Old) will copy the contents of the hash without copying the tie. In order to copy the hash and retain the tie, it is necessary to tie the new hash rather than copying it.

  $object = tied %Mon;  
  tie %New, ref($object), $object;
COPYRIGHT

Copyright (C) 2001-2005 Particle Physics and Astronomy Research Council. All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA

D.14 ORAC::Msg::MessysLaunch

Generic interface for initialising message systems

SYNOPSIS

  use ORAC::Msg::MessysLaunch;

  $msl = new ORAC::Msg::EngineLaunch;

  $obj = $msl->messys( ’AMS’ );  
  %objs = $msl->messys_active;
DESCRIPTION

This class provides a generic interface to the messaging systems supported by ORAC-DR. The knowledge of how to setup and initialise all the supported messaging systems is included in this class.

The message systems are started on demand (that is, the first time an object is requested by name). The message systems will be ORAC::Msg::Control objects (eg ORAC::Msg::Control::AMS).

This interface allows message systems to be initialised only when specific algorithm engines are required (rather than starting every message system even if none are required).

METHODS

The following methods are provided: Constructor  Object constructors.

new

Instantiate a new object ready for launching.

  $launch = new ORAC::Msg::MessysLaunch( $unique );

Since, in general, it is convenient for all parts of the code to have access to previously started message systems (and in many cases it is an error to start 2 identical message systems), the default behaviour is for the constructor to return the same object reference each time it is called. If it is required for a completely new object to be created each time the argument must be set to true.

ORAC-DR usually requires that access is provided to all previously initialised message systems so that the messaging layer can be configured by any subsystem.

Accessor Methods 
config

Allows the message system configuration to be stored. These options are used to configure each message system that is initialised.

If it is required to configure message systems that are already running use the configure_all method.

Accepts a hash containing the names of the methods to invoke on the message system object and the options to use.

  $msl->config( messages => 1,  
                   timeout => 600,  
                   ... );

Currently, all options are configured at once and any previous options (even if they have different names) are lost.

Returns a hash with the current configuration.

messys

Retrieve the object associated with the specified message system, initialising it if required.

  $obj = $msl->messys("AMS");

undef is returned if the message system could not be initialised.

The message system object can be stored if two arguments are used. A rudimentary check is made to make sure that the object is a reference. It is not possible to check a true ISA relationship until the class structure is reorganized. If the object does not satisfy this condition it is not stored and a warning is raised with "-w".

  $msl->messys("AMS", $object);

Returns a hash reference containing all the currently launched engines if called without arguments.

  $launched = $launch->messys;

See also messys_active.

messys_active

Returns a hash containing all the message system objects that have been created.

 %Messys = $msl->messys_active;
preserve

This method is used to set or retrieve the preserve flag. The preserve flag controls whether the messys environment variables should be left unchanged for initialisation or whether the system should be initialised such that it does not interfere with non-ORAC-DR environments.

The default is that the message system should be initialised such that it does not interfere with other external systems. This is required if multiple ORAC-DR pipelines are to be run on the same machine by the same user.

If preserve is set to true it may be possible for the pipeline to interact with algorithm engines launched outside the context of the pipeline. This is the case when ORAC-DR is configure to interact with CGS4DR.

  $msl->preserve(1);  
  $preserve = $msl->preserve;
General Methods 
configure_all

Configure all the current message systems using the configuration options that have been set previously by use of the config method.

  $msl->configure_all;
configure_messys

Configures the named message system using the configuration options that have been set previously by use of the config method.

  $msl->configure_messys( ’AMS’ );
init_messys

Given a message system name (for example ’AMS’) initialise the message system so that it can be used by algorithm engines.

  $messys_obj = $msl->init_messys( ’AMS’ );

Returns the object that was instantiated, or undef on error.

If the message system has been initialised previously that object is returned.

COPYRIGHT

Copyright (C) 2001-2005 Particle Physics and Astronomy Research Council. All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA