NAME

XML::Document::RTML - module which builds and parses RTML documents

SYNOPSIS

An object instance can be created from an existing RTML document in a scalar, or directly from a file on local disk.

   my $object = new XML::Document::RTML( XML => $xml );
   my $object = new XML::Document::RTML( File => $file );
   

or via the build method,

   my $object = new XML::Document::RTML() 
   $document = $object->build( %hash );
   

once instantiated various query methods are supported, e.g.,

   my $object = new XML::Document::RTML( File => $file );
   my $role = $object->role();

DESCRIPTION

The module can build and parse RTML documents. Currently only version 2.2 of the standard is supported by the module.

REVISION

$Id: RTML.pm,v 1.16 2006/11/17 20:43:26 aa Exp $

METHODS

Constructor

new

Create a new instance from a hash of options

  my $object = new XML::Document::RTML( %hash );

returns a reference to an message object.

Accessor Methods

type

Return, or set, the type of the RTML document

  my $type = $object->type();
  $object->type( $type );

version

Return, or set, the version of the RTML specification used

  my $version = $object->version();
  $object->version( $version );

Scheduling Methods

group_count

Return, or set, the group count of the observation

  my $num = $object->group_count();
  $object->group_count( $num );
  

exposure_time

Return, or set, the exposure time of the observation

  my $num = $object->exposure_time();
  $object->exposure_time( $num );
  

signal_to_noise

Return, or set, the S/N of the observation

  my $num = $object->signal_to_noise();
  $object->signal_to_noise( $num );
  

reference_flux

Sets (or returns) the flux of the object needed for signal to noise calculations for the image

   my $mag = $object->reference_flux();
   $object->reference_flux( $mag );

the flux should be a continuum R band magnitude value.

exposure_type

Return, or set, the type of exposure of the observation

  my $string = $object->exposure_type();
  $object->exposure_type( $string );

where $string can have values of "snr" or "time".

series_count

Return, or set, the series count of the observation

  my $num = $object->series_count();
  $object->series_count( $num );
  

interval

Return, or set, the interval between a series of observations blocks

  my $num = $object->interval();
  $object->interval( $num );
  

tolerance

Return, or set, the tolerance between a series of observations blocks

  my $num = $object->tolerance();
  $object->tolerance( $num );
  

priority

Return, or set, the priority of the observation

  my $num = $object->priority();
  $object->priority( $num );
 

Schedule (RTML) priority Phase II Priority Phase II GUI N/A 5 Urgent 0 4 (default) Normal 1 3 High 2 2 Medium 3 1 Normal default(other) 1 Normal N/A 0 Normal

where: "Schedule (RTML) priority" is the number specified in the RTML: <Schedule priority="n">, "Phase II Priority" is the number stored in the Phase II database and "Phase II GUI" is what is displayed in the Phase II GUI.

Note: The Phase II priority 4 can be specified by the TEA but cannot be specified by the Phase II GUI (and displays as the default "Normal" in the GUI). The Phase II priority 5 cannot be specified by the TEA but can be specified by the Phase II GUI as Urgent.

time_constraint

Return, or set, the time constraints of the the observation

  my $array_reference = $object->time_constraint();
  $object->exposure_type( \@times );

where it takes and returns a scalar reference to an array of ISO8601 times, e.g. my $array_reference = [ $start, $end ] which maps to,

      <TimeConstraint>
        <StartDateTime>2006-09-10T11:12:51+0100</StartDateTime>
        <EndDateTime>2006-09-12T00:12:51+0100</EndDateTime>
      </TimeConstraint>
  

Device Methods

device_type

Return, or set, the device type for the observation

  my $string = $object->device_type();
  $object->device_type( $string );
  

filter_type

Return, or set, the filter type for the observation

  my $string = $object->filter_type();
  $object->filter_type( $string );
  

Target Methods

target_type

Return, or set, the type of target for the observation

  my $string = $object->target_type();
  $object->target_type( $string );

there are two types of valid target type; "normal" or "toop". A normal observation is placed into the queue

target_ident

Return, or set, the type identifier of target for the observation

  my $string = $object->target_ident();
  $object->target_ident( $string );

The target identity is used by the eSTAR system to choose post-observation processing blocks, e.g.

  <Target type="normal" ident="ExoPlanetMonitor">
  

signifies a normal queued observation which is part of the exo-planet monitoring programme on Robonet-1.0.

target_name

Return, or set, the target name for the observation

  my $string = $object->target_name();
  $object->target_name( $string );

coordinate_type

Sets (or returns) the type of co-ordinate system expected,

   my $ra = $object->coordinate_type();
   $object->coordinate_type( 'equatorial' );

defaults to "equatorial". Don't change this unless you know what you're doing and set all the other relevant parameters via the relevant private methods provided by the class.

ra

Sets (or returns) the target RA

   my $ra = $object->ra();
   $object->ra( '12 35 65.0' );

must be in the form HH MM SS.S.

dec

Sets (or returns) the target DEC

   my $dec = $object->dec();
   $object->dec( '+60 35 32' );

must be in the form SDD MM SS.S.

equinox

Sets (or returns) the equinox of the target co-ordinates

   my $equnox = $object->equinox();
   $object->equinox( 'B1950' );

default is J2000, currently the telescope expects J2000.0 coordinates, no translation is currently carried out by the library before formatting the RTML message. It is therefore suggested that the user provides their coordinates in J2000.0 as this is merely a placeholder routine.

Agent Methods

host

Return, or set, the host to return asynchronous messages to regarding the status of the observation, see also port( ).

  my $string = $object->host();
  $object->host( $string );

defaults to the current machine's IP address

port

Return, or set, the port to return asynchronous messages to regarding the status of the observation, see also host( ).

  my $string = $object->port();
  $object->port( $string );

defaults to 8000.

id

Sets (or returns) the unique ID for the observation request

   my $id = $object->id();
   $object->id( 'IATEST0001:CT1:0013' );

note that there is NO DEFAULT, a unique ID for the score/observing request must be supplied, see the eSTAR Communications and the TEA command set documents for further details.

Note: This is not the same thing as the target identity for the observation.

Contact Methods

name

Return, or set, the name of the observer

  my $string = $object->name();
  $object->name( $string );

  

user

Return, or set, the user name of the observer

  my $string = $object->user();
  $object->user( $string );

e.g. PATT/keith.horne

institution

Return, or set, the institutional affliation of the observer

  my $string = $object->institution();
  $object->institution( $string );

e.g. University of Exeter

email

Return, or set, the email address of the observer

  my $string = $object->email();
  $object->email( $string );
  

project

Return, or set, the user name of the observer

  my $string = $object->user();
  $object->user( $string );

e.g. PATT/keith.horne

Scoring Methods

score

Sets (or returns) the target score

   my $score = $object->score();
   $object->score( $score );

the score will be between 0.0 and 1.0

completion_time

Sets (or returns) the target completion time

   my $time = $object->completion_time();
   $object->completion_time( $time );

the completion time should be of the format YYYY-MM-DDTHH:MM:SS

Data Methods

data

Sets (or returns) the data associated with the observation

   my @data = $object->data( );
   $object->data( @data );

Takes an array of hashes where,

   @data = [ { Catalogue => ' ', Header => ' ', URL => ' ' },
             { Catalogue => ' ', Header => ' ', URL => ' ' },
                   .
                   .
                   .
             { Catalogue => ' ', Header => ' ', URL => ' ' } ];

and the value of the Catalogue hash entry is a URL pointing to a VOTavle, the Header hash entry is a FITS header block and the URL is either points to a FITS file, or other associated data product. You can not append data to an existing memory structure, any data passed via this routine will overwrite any existing data structure in memory.

The routine returns a similar array when queried. This array will be populated either by calling build( ), or through parsing a document.

General Methods

dump_buffer

Dumps the contents of the RTML buffer in memory to a scalar,

   my $object = new XML::Document::RTML();
   $object->build( %hash );
   my $document = $object->dump_buffer();

If build( ) has not been called this function will return an undef.

dump_tree

Returns a refence to the parsed RTML document hash currently held in memory,

   my $object = new XML::Document::RTML( XML => $xml );
   my $hash_reference = $object->dump_tree();

should return an undefined value if that tree is empty. This error will occur if we haven't called build( ) to create a document, or populated the tree using the object creator by calling the XML or File methods to read in a document.

configure

Configures the object, takes an options hash as an argument

  $message->configure( %options );

Does nothing if the hash is not supplied. This is called directly from the constructor during object creation

cpanm XML::Document::RTML

perl -MCPAN -e shell
install XML::Document::RTML