next up previous 264
Next: Controlling the Amount of Output
Up: Saving and Restoring Objects (Channels)
Previous: Storing an ID String with an Object


The Textual Output Format

Let us now examine the format of the textual output produced by writing an Object to a basic Channel ([*]). To give a concrete example, suppose the Object in question is a SkyFrame, written out as follows:

      INTEGER SKYFRAME

      ...

      NOBJ = AST_WRITE( CHANNEL, SKYFRAME, STATUS )

The output should then look like the following:

 Begin SkyFrame 	# Description of celestial coordinate system
#   Title = "FK4 Equatorial Coordinates, no E-terms, Mean Equinox B1950.0, Epoch B1958.0" 	# Title of coordinate system
    Naxes = 2 	# Number of coordinate axes
#   Domain = "SKY" 	# Coordinate system domain
#   Lbl1 = "Right Ascension" 	# Label for axis 1
#   Lbl2 = "Declination" 	# Label for axis 2
#   Uni1 = "hh:mm:ss.s" 	# Units for axis 1
#   Uni2 = "ddd:mm:ss" 	# Units for axis 2
#   Dir1 = 0 	# Plot axis 1 in reverse direction (hint)
    Ax1 = 	# Axis number 1
       Begin SkyAxis 	# Celestial coordinate axis
       End SkyAxis
    Ax2 = 	# Axis number 2
       Begin SkyAxis 	# Celestial coordinate axis
       End SkyAxis
 IsA Frame 	# Coordinate system description
    System = "FK4-NO-E" 	# Celestial coordinate system type
    Epoch = 1958 	# Besselian epoch of observation
#   Eqnox = 1950 	# Besselian epoch of mean equinox
 End SkyFrame

You will notice that this output is designed both for a human reader, in that it is formatted, and also to be read back by a computer in order to reconstruct the SkyFrame. In fact, this is precisely the way that AST_SHOW works ([*]), this routine being roughly equivalent to the following use of a Channel:

      CHANNEL = AST_CHANNEL( AST_NULL, AST_NULL, ' ', STATUS )
      NOBJ = AST_WRITE( CHANNEL, OBJECT, STATUS )
      CALL AST_ANNUL( CHANNEL, STATUS )

Some lines of the output start with a ``#'' comment character, which turns the rest of the line into a comment. These lines will be ignored when read back in by AST_READ. They typically contain default values, or values that can be derived in some way from the other data present, so that they do not actually need to be stored in order to reconstruct the original Object. They are provided purely for human information. The same comment character is also used to append explanatory comments to most output lines.

It is not sensible to attempt a complete description of this output format because every class of Object is potentially different and each can define how its own data should be represented. However, there are some basic rules, which mean that the following common features will usually be present:

  1. Each Object is delimited by matching ``Begin'' and ``End'' lines, which also identify the class of Object involved.

  2. Within each Object description, data values are represented by a simple ``keyword $=$ value'' syntax, with one value to a line.

  3. Lines beginning ``IsA'' are used to mark the divisions between data belonging to different levels in the class hierarchy ([*]). Thus, ``IsA Frame'' marks the end of data associated with the Frame class and the start of data associated with some derived class (a SkyFrame in the above example). ``IsA'' lines may be omitted if associated data values are absent and no confusion arises.

  4. Objects may contain other Objects as data. This is indicated by an absent value, with the description of the data Object following on subsequent lines.

  5. Indentation is used to clarify the overall structure.

Beyond these general principles, the best guide to what a particular line of output represents will generally be the comment which accompanies it together with a general knowledge of the class of Object being described.


next up previous 264
Next: Controlling the Amount of Output
Up: Saving and Restoring Objects (Channels)
Previous: Storing an ID String with an Object

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 210
R.F. Warren-Smith & D.S. Berry
24th May 2011
E-mail:ussc@star.rl.ac.uk

Copyright (C) 2009 Science \& Technology Facilities Council