3 Examples

 3.1 Getting Started
 3.2 Formatting
 3.3 Structures
 3.4 Character Arrays
 3.5 Current Value

In the following examples a a UNIX shell is used, but the commands would also work from ICL except where noted.

3.1 Getting Started

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.

  % hdstrace beq
  
  BEQ  <IMAGE>
    TITLE          <_CHAR*72>      ’KAPPA - Glitch’
    DATA_ARRAY(109,64)  <_REAL>    124,92,98,156,171,166,171,181,190,180,
                                   ... 127.32,127.56,128.36,129.4,130.08,130.44
    DATA_MIN       <_REAL>         12
    DATA_MAX       <_REAL>         254
  
  End of Trace.

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:

  % hdstrace beq.data_array
  
  BEQ.DATA_ARRAY  <_REAL>
    DATA_ARRAY(109,64)  124,92,98,156,171,166,171,181,190,180,196,205,217,
                        ... 126.6,127.32,127.56,128.36,129.4,130.08,130.44
  
  End of Trace.

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.

  % hdstrace beq.data_array nlines=3
  
  BEQ  <IMAGE>
    TITLE          <_CHAR*72>      ’KAPPA - Glitch’
    DATA_ARRAY(109,64)  <_REAL>    124,92,98,156,171,166,171,181,190,180,
     196,205,217,211,204,210,202,197,201,196,194,192,189,190,191,187,196,
     202,202,206,204,202,191,172,150,*,131,176,192,204,206,182,170,164,161,
     ... 127.16,126.2,126.36,126.6,127.32,127.56,128.36,129.4,130.08,130.44
    DATA_MIN       <_REAL>         12
    DATA_MAX       <_REAL>         254
  
  End of Trace.

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.

  % hdstrace SMALL.DATA_ARRAY
  
  SMALL  <IMAGE>
    TITLE          <_CHAR*72>      ’KAPPA - Pick2d’
    DATA_ARRAY(3,2)  <_REAL>       124,92,98,156,156,149
  
  End of Trace.

3.2 Formatting

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,

  % hdstrace beq typind=20
  
  BEQ  <IMAGE>
    TITLE               <_CHAR*72>      ’KAPPA - Glitch’
    DATA_ARRAY(109,64)  <_REAL>         124,92,98,156,171,166,171,181,190,
                                        ... 127.56,128.36,129.4,130.08,130.44
    DATA_MIN            <_REAL>         12
    DATA_MAX            <_REAL>         254
  
  End of Trace.

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.

  % hdstrace beq newline
  
  BEQ  <IMAGE>
    TITLE          <_CHAR*72>
     ’KAPPA - Glitch’
    DATA_ARRAY(109,64)  <_REAL>
     124,92,98,156,171,166,171,181,190,180,196,205,217,211,204,210,202,197,
     ... 127.16,126.2,126.36,126.6,127.32,127.56,128.36,129.4,130.08,130.44
    DATA_MIN       <_REAL>
     12
    DATA_MAX       <_REAL>
     254
  
  End of Trace.

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.

3.3 Structures

Let us move on to a different example HDS file to demonstrate some of the other parameters of Hdstrace.

  % hdstrace $ADAM_USER/GLOBAL valind=18
  
  GLOBAL  <STRUC>
    LUT            <ADAM_PARNAME>     {structure}
       NAMEPTR        <_CHAR*132>        ’xmascomet_lut’
  
    IMAGE_OVERLAY  <ADAM_PARNAME>     {structure}
       NAMEPTR        <_CHAR*132>        ’ikonov’
  
    GRAPHICS_DEVICE  <ADAM_PARNAME>   {structure}
       NAMEPTR        <_CHAR*132>        ’ikon’
  
    IMAGE_DISPLAY  <ADAM_PARNAME>     {structure}
       NAMEPTR        <_CHAR*132>        ’ikon’
  
    DATA_ARRAY     <ADAM_PARNAME>     {structure}
       NAMEPTR        <_CHAR*132>        ’cac1d’
  
    HDSOBJ         <_CHAR*132>        ’AST_ROOT:<DATA.DEMO>PSS_DEMO’
    SST_SOURCE     <_CHAR*132>        ’TRACE.FOR’
  
  End of Trace.

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.

  % hdstrace moimp
  
  MOIMP  <NDF>
    DATA_ARRAY(512,512)  <_REAL>   0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
                                   ... 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
    TITLE          <_CHAR*16>      ’created with pro’
    UNITS          <_CHAR*18>      ’NORMALIZED       B’
    AXIS(2)        <AXIS>          {array of structures}
  
    Contents of AXIS(1)
       DATA_ARRAY(512)  <_REAL>       -3542.08,-3512.186,-3482.291,
                                      ... 11644.38,11674.27,11704.17,11734.06
       LABEL          <_CHAR*18>      ’PIXELS           B’
  
    MORE           <EXT>           {structure}
       FITS(31)       <_CHAR*80>      ’SIMPLE  =                    T / St...’
                                      ... ’HISTORY  ESO-DESCRIPTOR...’,’’,’END’
  
  End of Trace.

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.

  % hdstrace MOIMP FULL
  
  MOIMP  <NDF>
    DATA_ARRAY(512,512)  <_REAL>   0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
                                   ... 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
    TITLE          <_CHAR*16>      ’created with pro’
    UNITS          <_CHAR*18>      ’NORMALIZED       B’
    AXIS(2)        <AXIS>          {array of structures}
  
    Contents of AXIS(1)
       DATA_ARRAY(512)  <_REAL>       -3542.08,-3512.186,-3482.291,
                                      ... 11644.38,11674.27,11704.17,11734.06
       LABEL          <_CHAR*18>      ’PIXELS           B’
  
    Contents of AXIS(2)
       DATA_ARRAY(512)  <_REAL>       11734.1,11704.21,11674.31,11644.42,
                                      ... -3482.252,-3512.146,-3542.041
       LABEL          <_CHAR*18>      ’PIXELS           B’
  
    MORE           <EXT>           {structure}
       FITS(31)       <_CHAR*80>      ’SIMPLE  =                    T / St...’
                                      ... ’HISTORY  ESO-DESCRIPTOR...’,’’,’END’
  
  End of Trace.

3.4 Character Arrays

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.

  % hdstrace moimp.more.fits newline eachline
  
  MOIMP.MORE.FITS  <_CHAR*80>
    FITS(31)
     ’SIMPLE  =                    T / Standard FITS format’, ...
     ’END’
  
  End of Trace.

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

  % hdstrace moimp.more nlines=a newline eachline
  
  MOIMP.MORE  <EXT>
    FITS(31)       <_CHAR*80>
     ’SIMPLE  =                    T / Standard FITS format’,
     ’BITPIX  =                   32 / No. of bits per pixel’,
     ’NAXIS   =                    2 / No. of axes in image’,
     ’NAXIS1  =                  512 / No. of pixels’,
     ’NAXIS2  =                  512 / No. of pixels’,
     ’EXTEND  =                    T / FITS extension may be present’,
     ’BLOCKED =                    T / FITS file may be blocked’,
     ’ ’,
     ’BUNIT   = ’NORMALIZED       B  ’ / Units of data values’,
     ’BSCALE  =   7.450580607332E-06 / Scaling factor: r = f*i + z’,
     ’BZERO   =   1.600000000000E+04 / Zero offset: r = f*i + z’,
     ’ ’,
     ’CRPIX1  =   1.000000000000E+00 / Reference pixel’,
     ’CRVAL1  =  -3.542080000000E+03 / Coordinate at reference pixel’,
     ’CDELT1  =   2.989460000000E+01 / Coordinate increment per pixel’,
     ’CTYPE1  = ’PIXELS           B  ’ / Units of coordinate’,
     ’CRPIX2  =   1.000000000000E+00 / Reference pixel’,
     ’CRVAL2  =   1.173410000000E+04 / Coordinate at reference pixel’,
     ’CDELT2  =  -2.989460000000E+01 / Coordinate increment per pixel’,
     ’CTYPE2  = ’PIXELS           B  ’ / Units of coordinate’,
     ’ ’,
     ’ORIGIN  = ’ESO-MIDAS’          / Written by MIDAS’,
     ’OBJECT  = ’created with pro’   / MIDAS desc.: IDENT(1)’,
     ’ ’,
     ’HISTORY  ESO-DESCRIPTORS START   ................’,
     ’HISTORY  ’HEADER_VERS’    ,’C*1 ’   ,    1,   13,’13A1’,’ ’,’ ’’,
     ’HISTORY  06-APR-1990’,
     ’HISTORY’,
     ’HISTORY  ESO-DESCRIPTORS END     ................’,
     ’ ’,
     ’END’
  
  End of Trace.

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.

3.5 Current Value

If you wish to examine the same object repeatedly perhaps with other parameters changed you can use the ACCEPT keyword or its shorthand. Thus

  % hdstrace full \\

would give a full trace of the last object traced.

1FITSLIST in Kappa offers a more-convenient way of listing the FITS headers within NDFs.