In the following examples a a UNIX shell is used, but the commands would also work from ICL except where noted.
The first HDS file is quite simple. It is an old IMAGE-format file may still be used in Kappa. Note that on UNIX the HDS file name is case sensitive.
The first line tells us that the structure’s name is BEQ and its type is IMAGE. (Note that the
structure’s name is not necessarily the file name.) The <> delimiters are just a convention to
differentiate name from type; they are not part of the type itself. The next few lines are
indented. Hdstrace uses indentation to indicate the position within the hierarchy. Here TITLE,
DATA_ARRAY etc. are at the top level of the hierarchy within the container file. (If they are at
the top, why is BEQ negatively indented? BEQ applies to the file as a whole—a kind of
zeroth level. An analogy is your login directory. It is at the top of your hierarchy of files in
directories. However, it is a file itself stored on disc.) The second line shows that the TITLE is a
character object of length 72, and has a value of ’KAPPA - Glitch’. The third line shows
an array. The dimensions follow the name thus DATA_ARRAY has 109 columns and 64
lines. Since there is insufficient room to list the values of 6976 elements, Hdstrace lists the
first few and last few values separated by an ellipsis to indicate that there are missing
values.
We can look at a specific object or structure. For example to look at just the data array in beq enter:
The case of the object name you supply does not matter since in HDS all object names are in uppercase.
We can look at more of the DATA_ARRAY as follows.
The nlines=3 specifies that up to a maximum of three lines, excluding any extra line that shows the
final few values, can be used to present the values. In order to present more values the continuation
lines are indented one column right of the object’s name. Notice nlines=3 has no effect
on the other objects in the structure because their values each fit onto a line; had there
been other arrays these too may have up to three lines to list their values. The NLINES
parameter normally defaults to one, hence we usually just see the initial values on a single
line.
The observant reader will have noticed an asterisk replacing a numerical value in the third line. This is shorthand for a bad value, and it has the added advantage that it is more distinctive.
For inspection of two-dimensional arrays and subsets Gaia or LOOK in Kappa may be more convenient.
If the array was much smaller we could display all the values on a single line.
If you wish to use the output for some documentation you might like to align the trace into neat columns. In the above examples the type of the DATA_ARRAY is displaced because of the dimensions. The indentation of the type with respect to the start of the name, and the values with respect to the start of the type may be controlled by Parameters TYPIND and VALIND respectively. For example,
indents the type five characters more than the default.
There is another way to format the output, and that it to place the values on a new line rather than appending them to the name and type. This can help when dealing with moderate-sized arrays.
A record of the trace may be stored in an text file given by the Parameter LOGFILE. The width of the output defaults to the screen width and may be altered via Parameter WIDTH.
Let us move on to a different example HDS file to demonstrate some of the other parameters of Hdstrace.
This HDS file stores the values of global parameters shared by ADAM applications. LUT,
GRAPHICS_DEVICE etc. are structures, and therefore instead of listing values, Hdstrace writes the
comment {structure}. Each of these structures contains one object, NAMEPTR, which is indented in
the trace. Hdstrace inserts a blank line after listing the contents at the end of a structure for
clarity.
Structures can also be arrays, as in the following example of an NDF.
AXIS is an array of structures. Therefore it has no values and Hdstrace puts the comment {array of
structures}. By default Hdstrace only lists the contents of the first element of an array of
structures. To obtain a full trace of arrays of structures you must set the Parameter FULL to be
true.
In MOIMP there is an array of characters—the NDF FITS extension. If Hdstrace cannot accommodate a string in the space available it attempts to give the first few characters followed by an ellipsis to indicate only a part of the string is reported. Thus in the above trace only part of the first FITS header card is shown. Part of the anti-penultimate header is reported. The last two lines are blank and ’END’ and are listed in full. These truncations are not very convenient. Hdstrace provides a mechanism for placing each character-array element on a new line.
To list the whole array specify nlines=all or give an NLINES with at least the number of array
elements. Note the object need not necessarily be the array. Below we trace the MORE
extension.1
The nlines=all facility should be used with care; select an individual component or a structure that
does not contain a large array. The output from a data array such as found in a typical NDF will be
huge.
If you wish to examine the same object repeatedly perhaps with other parameters changed you can use the ACCEPT keyword or its shorthand. Thus
would give a full trace of the last object traced.