2 Running HDSTRACE

 2.1 UNIX
 2.2 UNIX
 2.3 Getting Help
 2.4 Parameters

This document adheres to the normal style, where your input follows the $, % or > prompts.

2.1 UNIX

Hdstrace runs as an ADAM task. ADAM must therefore be initiated directly or indirectly using the ADAMSTART or ADAM command before Hdstrace can be run.

Hdstrace may be run directly from the UNIX shell with the following command.

  % hdstrace

You will be prompted for the HDS object or structure to be traced.

If you wish to trace several files or objects it is more efficient to run Hdstrace from ICL. If you are already using ICL just enter


If you are in DCL, the following will start both ICL and Hdstrace.


The command can be abbreviated to HDST and the old command TRACE will also work from both the shell and ICL.

2.2 UNIX

Hdstrace may be also run directly from a UNIX shell,

  % hdstrace

There is no initialisation procedure to run first, but the command may not be abbreviated.

2.3 Getting Help

The following command gives help on HDSTRACE.


Notice that this only available for ICL since there is no global help system for Starlink applications. However, it is possible to access the full help on Hdstrace from the UNIX shell by entering ?? in response to a prompt for a parameter.

  % hdstrace
  OBJECT - Object to be examined > ??

2.4 Parameters

All but one of the parameters used by Hdstrace are normally defaulted. If you wish to be prompted for all or some of the defaulted values give the PROMPT keyword on the command line; you can terminate the prompting by entering a at any prompt and each remaining parameter will take its default value. Normally, this should not be necessary as most of the time the defaults will be satisfactory or just one or two need changing by specifying them on the command line. Prompting does have one advantage in that a ? may be entered to elicit help on that parameter.

Parameters may be given by keyword, e.g. 

  % hdstrace object=myfile nlines=3

or by position, e.g. 

  % hdstrace myfile no 3

where the no is for the FULL parameter, or by a combination of both provided the positional parameters come before any keywords, e.g. 

  % hdstrace myfile nlines=3

Full details of the parameters, their defaults and their command-line positions are given in the Appendix.

2.4.1 Tailoring HDSTRACE

Beginners can skip over this section.

If you want to alter some of the defaults, or always make Hdstrace prompt for a normally defaulted parameter, you can have your own version of the interface file. To achieve this enter the following from the UNIX shell.

  % cd ~abc/xyz                    # Substitute the actual disk and directory
                                  # where you keep private versions of IFLs
  % cp $HDSTRACE_DIR/hdstrace.ifl .
  % vi trace.ifl                   # Make the changes you wish.
  % setenv ADAM_IFL ~abc/xyz:$ADAM_IFL # Append the directory to the
                                  # interface-file search path.

SUN/115 tells you how to interpret the interface file; it describes the meanings and available options of the various keywords, and the use of the ADAM_IFL environment variable. The most likely things that you would wish to alter are the values of default and vpath.

SUN/144 has more details of the ADAM_IFL environmental variable.

The best way to describe the parameters is to show some examples.