This section describes the libraries that are relevant for someone modifying the core.
Shared Base class for Frame and Group classes
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).
The following methods are available in this class: Constructors The following constructors are available:
Create a new ORAC::BaseFile object. In general this constructor should not be called
directly but should be called from a subclass.
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.
Calls the configure method to handle sub-class specific configuration. The file arguments to configure match the arguments to the constructor.
Whether or not to allow automatic header synchronization when the Frame is updated
via either the file or files method.
Defaults to false (0).
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).
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
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".
Set or retrieve the array containing the current file names associated with the frame object.
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:
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.
Returns the identification string that is used to compare the current frame with the frames selected for display in the display definition file.
Arguments:
To return the ID associated with the second frame:
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.
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.
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.
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.
Data format associated with the current file(). Usually one of ’NDF’ or ’FITS’. This format should
be recognisable by ORAC::Convert.
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.
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).
If no arguments are provided, the reference to the header hash is returned.
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.
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.
Both return the values from the first sub-header (index 0) if the value is not present in the primary header.
Return all the different values associated with a single FITS header taken from all subheaders.
Only unique values are returned. Quickly enables the caller to determine how many distinct states are in the Frame.
Return a list of FITS header keys, including those found in subheaders.
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:
Returns $out in a scalar context:
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).
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.
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.
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.
Equivalent to
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).
This method returns (or sets) the name of the raw data file(s) associated with this object.
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).
Flag used to determine whether the current filename should be erased when the file() method is next used to update the current filename.
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.
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.
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:
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.
Set or return the "product" of the current File object.
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".
Check a given tag against the list of current tags and return true if a match is found.
The comparison is case sensitive.
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".
The tag is case insensitive.
Retrieve the files names from the tag and make them the default filenames for the object.
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.
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.
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).
If no arguments are provided, the reference to the header hash is returned.
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).
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
ie the first wcs is set to undef.
This method is used to synchronize FITS headers with information stored in e.g. the World Coordinate System.
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.
Sets the name of the file containing header override information.
Returns a hash of headers to be overridden by filename.
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.
This method updates the frame user header and returns a hash containing the new keywords.
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).
Multiple raw file names can be provided in the first argument using a reference to an array.
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.
Translates an ORAC-DR specific header (such as ORAC_TIME) to the equivalent FITS header(s).
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.
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.
Update the product() value and force the file to receive the update with a sync headers.
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.
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
Base class for FITS file manipulation
This class provides base methods for use by classes that need to manipulate FITS files. For example,
ORAC::Frame::MEF.
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() ).
The filename can be supplied if the one stored in the object is not required:
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.
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.
The argument is optional. If you supply one, it will extract the basename of the argument stripping off the extension relevant to the object...
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.
Copyright (C) 1998-2002 Particle Physics and Astronomy Research Council. All Rights Reserved.
Base class for NDF file manipulation
This class provides base methods for use by classes that need to manipulate GSD files. For example,
ORAC::Frame::GSD and ORAC::Group::GSD.
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() ).
The filename can be supplied if the one stored in the object is not required:
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.
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.
ORAC::Frame::GSD, ORAC::Group::GSD
Copyright (C) 2003 Particle Physics and Astronomy Research Council. All Rights Reserved.
Base class for NDF file manipulation
This class provides base methods for use by classes that need to manipulate NDF files. For example,
ORAC::Frame::NDF and ORAC::Group::NDF.
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.
Takes one argument, the filename for which the header will be returned.
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() ).
The filename or filenames can be supplied if the one stored in the object is not required:
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.
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.
This method is used to synchronize FITS headers with information stored in e.g. the World Coordinate System.
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 the frameset and store the resulting Starlink::AST object into the object for later retrieval
via the wcs() method.
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.
In scalar context the first WCS object is returned.
Write the frameset back into the NDF.
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.
In scalar context the first WCS object is returned.
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.
Specifying a reference epoch will mean that only a log messages since that epoch will be considered.
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.
Call without arguments to reset the name to the ORAC-DR app name and version number.
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.
The following methods are intended for use inside the module. They are included here so that authors of derived classes are aware of them.
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.
Given an array of filenames, open each one using HDS and see whether there are any top level NDFs inside.
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
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.
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.
ORAC::Frame::NDF, ORAC::Group::NDF
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
Some implementation subroutines
Routines that do not have a home elsewhere.
The following functions are provided:
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.
Does not canonicalize.
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.
Hash arguments can control behaviour to indicate master vs monitor behaviour. Options are:
Monitor files are always written if a master.
Make informational string to be shown in window titles given the parameters passed as options.
Standard exit handler for oracdr. Should be called instead of exit() when the pipeline is
complete.
Hash arguments control the behaviour. Allowed keys are:
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.
Exit handler when a problem has been encountered. Normally used a signal handler for SIGINT.
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.
Does nothing if there is no error text.
Change to the output directory. If that fails, exit the pipeline.
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.
Copyright (C) 1998-2004 Particle Physics and Astronomy Research Council. All Rights Reserved.
Methods for converting data formats
Provide a system for converting data formats. Currently the only output format supported are:
The only input formats supported are:
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).
The following methods are provided: Constructors
Object constructor. Should always be used before initiating a conversion.
Returns undef if there was an error creating the object. No arguments are required.
Returns the ORAC::Msg::EngineLaunch object that can be used to launch algorithm
engines as required by the particular conversion.
Method for storing or retreiving the current input filename. Used by default if omitted from convert() methods.
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.
Convert a file to the format specified by options.
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:
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.
Given ’name’ try to guess data format.
If no name is supplied, infile() is used to retrieve the current filename.
Returns the algorithm engine object, launching it if required.
Returns undef if a monolith can not be contacted or fails to start. This is launched using
ORAC::Msg::LaunchEngine.
Convert a fits file to an NDF. Returns the output name.
Retrieves the input filename from the object via the infile() method.
Convert an NDF file to a FITS file.
Convert a HDS file into a multi-extension FITS file
Convert a GEMINI multi-extension FITS file to an HDS container
Convert an ING format Multi-Extension FITS file into an HDS container.
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.
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.
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).
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).
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
Core routines for data pipelining
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.
The following subroutines are available:
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).
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.
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.
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.
Wrapper for the orac_print_configuration function, but including code to configure default
logging switches before configuring the print system.
@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.
Attempt to load Tk and create a main window indexed by the identifying string.
This routine can safely be called multiple times.
Returns the top level MainWindow object.
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.
where %options is the command line options hash.
Attempt to retrive the pipeline output directory from a file in ORAC_LOCATION_DIR. See orac_declare_location for the details of this file.
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
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.
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.
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.
This routine pre-launches the relevant algorithm engines which are always required by the instrument
it returns a reference to the algorithm engine hash, $Mon.
This routine is a wrapper for the orac_setup_display() subroutine in ORAC::Basic. It starts the ORAC display unless $nodisplay is set.
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.
This routine creates a calibration object of the specified class and overrides methods as specified
in the --calib option string.
Multiple calibrations specifications can be supplied. The calibrations are specified as comma separated keyword=value strings or as hash references.
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.
it returns an array of files to be read.
"#" is a comment character.
Parse the command line argument specifying recipe parameters and return either a ORAC::Recipe::Parameters object or undef.
This routine checks that your data exists and decides which data loop approach to use.
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.
This routine handles the main data processing.
There are two approaches to the data processing.
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).
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
Default mode is
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.
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.
Print out the recipe summary using the hash generated by orac_store_recipe_status.
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 (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
Base class for ORAC display interface
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).
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.
This constructor does not attempt to launch a display device. That is up to the sub-classes.
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:
The value associated with the supplied key is returned if one argument is provided:
The supplied value is stored in key if two arguments are supplied:
Undefined values are accepted.
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.
If the windows were launched with bad status we should set the device name to something recognisable as bad since status is not returned.
ORAC::Display::GAIA, ORAC::Display::KAPVIEW
Copyright (C) 1998-2000 Particle Physics and Astronomy Research Council. All Rights Reserved.
ORAC interface to the the GAIA (ESO Skycat) display tool. Provides methods for displaying images.
Available options are:
IMAGE - display image in GAIA window
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.
Whether or not GAIA can be automatically launched.
Defaults to true. If this is set to false (0), then a new GAIA will never be started.
Returns or sets the socket to Gaia. Private to this class.
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).
Returns the IO::Select object associated associated with the current socket.
This object is used to determine whether the GAIA process can be contacted through the established socket connection.
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.
Clone a new GAIA window and associate it with ’win’. This is different to launching a new display device (ie running up GAIA itself).
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.
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.
Load the startup image into GAIA. Essentially used to test that GAIA can display images correctly.
Returns ORAC status.
Sends the supplied command to gaia. Any response from Gaia is returned.
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.
Returns the name to be used for the new GAIA window based on the supplied window name.
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.
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.
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.
ORAC::Display::Base, ORAC::Display::KAPVIEW, ORAC::Display, IO::Socket
Copyright (C) 1998-2000 Particle Physics and Astronomy Research Council. All Rights Reserved.
ORAC-DR interface to Kapview (KAPPA)
ORAC interface to KAPPA Kapview. Provides methods for displaying images and spectrum with Kapview.
Available options are:
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.)
Returns the ORAC::Msg::EngineLaunch object that can be used to launch algorithm
engines as required by the particular conversion.
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.
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.
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.
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.
Set or retrieve the previous lookup table.
Messaging object associated with the Kapview display object.
Given ’win’, calculates a new device name that should be unique for each ’win’.
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.
Currently, the method dies if the device can not be successfully created.
This method starts the kapview monolith and stores the associated Task object.
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.
This method configures the display regions so that they can be selected later by select_region.
A window name must be supplied.
The regions are defined as follows:
The picture labels are stored in the regions() array.
Selects the requested region as the current region in the display system by using a supplied hash.
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.
This method converts a file name and options hash into a filename with an attached NDF section.
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:
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 N2, the leading letter is dropped and replaced by the dimension number. For example,
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:
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 the given LUT.
This method also calls lookup_table to store the name of the specified LUT.
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:
Default is to autoscale.
ORAC Status is returned.
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:
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:
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
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.
Displays a channel map of a central region of a cube.
Recognized options:
WIDTH defaults to 100. AXIS defaults to 3. NCHAN defaults to 9. SHAPE defaults to 3.
ORAC status is returned.
Collapse the central region of a cube along one axis, and display an image of the collapse region.
Recognised options:
WIDTH defaults to 100. AXIS defaults to 3.
ORAC status is returned.
Display contours of a 2-D data set.
Recognised options:
Default is to autoscale.
ORAC status is returned.
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.
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:
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.
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:
Default is for autoscaling and for NBINS=20. Note that the presence of SIGMA overrides ZMIN/ZMAX.
ORAC status is returned.
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:
Default is to autoscale.
ORAC status is returned.
ORAC::Display, ORAC::Display::GAIA
Copyright (C) 1998-2000 Particle Physics and Astronomy Research Council. All Rights Reserved.
Exception handling in an object orientated manner.
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.
ORAC::Error exports subroutines to perform exception handling. These will be exported if the :try
tag is used in the use line.
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.
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.
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
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 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.
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.
Create a new ORAC::Error object and returns it. This is defined for syntactic sugar, eg
Create a new ORAC::Error object and returns it. This is defined for syntactic sugar,
eg
Return the last error created, or the last error associated with 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.
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.
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.
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.
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.
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.
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.
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.
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).
Definition of instrument class dependencies
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.
The following functions are provided:
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.
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.
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.
Returns a list of directories that should be searched in order to locate recipes for the specified instrument.
Root location is specified by the ORAC_DIR environment variable.
Any instruments that start with "PICARD" will only include the PICARD search paths.
Returns a list of directories that should be searched in order to locate primitives for the specified instrument.
Root location is specified by the ORAC_DIR environment variable.
Returns a list of directories that should be searched in order to locate calibration files for the specified instrument.
Root location is specified by the ORAC_CAL_ROOT environment variable. ORAC_DATA_CAL is
included if it is set explicitly.
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.
In principal this list can be empty if no pre-launching is required.
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.
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.
Useful for converting a base class or a PICARD variant to a specific type.
Returns undef if none can be guessed.
Returns the details for a specified algorithm engine.
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
The name of the class to be used for this engine. (e.g. ORAC::Msg::Task::ADAM).
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.
The name of the message system required to contact the engine. See
orac_messys_description below for details.
Returns an empty list on error.
Returns the details for a specified message system.
The hash that is returned contains information on the class to be used to initialise the message system. It has the following keys
The name of the class to be used for this message system (e.g.
ORAC::Msg::ADAM::Control).
Returns an empty list on error.
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.
Helper task for the CGS4-DR P4 display system.
Copyright (C) 1998-2006 Particle Physics and Astronomy Research Council. All Rights Reserved.
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.
The following methods are provided: Constructor Object constructors.
Instantiate a new object ready for launching.
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).
Retrieve the object associated with the specified engine, launching it if required.
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".
Returns a hash reference containing all the currently launched engines if called without arguments.
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.
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.
Returns the ORAC::Msg::MessysLaunch object that can be used to initialise message systems as
required by the particular algorithm engines.
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.
In a scalar context simply returns true if all engines could be contacted. Also returns true if there are no registered engines.
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.
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 the specified monolith.
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.
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.
Return a new ID for the specified engine.
The current ID is updated (see engine_id for more details).
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:
It is also possible to tie a hash to an existing object:
The following can be used to retrieve the object associated with "polpack_mon" launching the engine if necessary:
Engines can be dissassociated from the object using the standard hash delete command:
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".
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.
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
Generic interface for initialising message systems
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).
The following methods are provided: Constructor Object constructors.
Instantiate a new object ready for launching.
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.
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.
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.
Retrieve the object associated with the specified message system, initialising it if required.
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".
Returns a hash reference containing all the currently launched engines if called without arguments.
See also messys_active.
Returns a hash containing all the message system objects that have been created.
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.
Configure all the current message systems using the configuration options that have been
set previously by use of the config method.
Configures the named message system using the configuration options that have been set
previously by use of the config method.
Given a message system name (for example ’AMS’) initialise the message system so that it can be used by algorithm engines.
Returns the object that was instantiated, or undef on error.
If the message system has been initialised previously that object is returned.
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