Reference Section

$\parbox{\sstbannerlength}{\flushleft{\Large {\bf HDSTRACE }}}$ $\parbox{\sstcaptionlength}{\center{\Large Examines the contents of a data-system object }}$ $\parbox{\sstbannerlength}{\flushright{\Large {\bf HDSTRACE }}}$

Description:

Data files in ADAM are stored in an hierarchical format (HDS). This cannot be read by just typing the file at the terminal or spooling it to a printer--a special application is required. Now rather than writing separate code to read a variety of structures, this application is sufficiently general to examine almost all HDS structures or objects. The examination may also be written to an text file as well as being reported to the user.

For the specified ADAM data-system object ($X$) there are three cases which are handled:

1) $X$ is a primitive object. The value, or the first and last few values of $X$ are listed.

2) $X$ is a structure. The contents of the structure are listed. If a component is encountered which is itself a structure then its contents are listed down to a level of six nested structures.

3) $X$ is an array of structures. All elements will be listed if parameter FULL is set to TRUE; only the first element will be listed when parameter FULL is set to FALSE (default).

Listings are in the following order: name; dimensions, if any; type; and value or comment. Comments are enclosed in braces.

The values are normally listed at the end of each line, but may start on a new line. The maximum number of lines of data values may also be set. For all but the smallest arrays where the values of all elements can be displayed in the space provided, the last few values in the array as well as the first few are presented. The last few values appear on a new line, indented the same as the line above with the ellipsis notation to indicate any missing values. Note the number of elements shown depends on the number of characters that will fit on the line. The ellipsis notation is also used for long character values where there is only room to show the first and last few characters. Bad values appear as asterisks.

The exact layout may be adjusted and is controlled by four additional parameters: a) the indentation of the type string with respect to the beginning of the name string; b) indentation of the value(s) (if not on a new line) with respect to the beginning of the type string; and c) the width of the output, 80 or 132. If the name and dimensions do not fit within the space given by parameters a) and b), the alignment will be lost because at least two spaces will separate the name from the type, or the type from the value(s). The fourth parameter defines how character arrays are arranged. The default is that character-array elements are concatenated to fill the available space delimited by commas. The alternative is to write the value of each element on a new line. This improves readability for long strings.

Usage:

Parameters:

EACHLINE = _LOGICAL (Read)

If true the elements of a character array will each appear on a separate line. Otherwise elements fill the available space and may span several lines, paragraph style. [FALSE]

FULL = _LOGICAL (Read)

If true, all the contents of an array of structures will be traced, otherwise only the first element is examined. [FALSE]

LOGFILE = FILENAME (Read)

The name of the text file to contain a log of the examination of the data object. Null (!) means do not create a log file. [!]

NEWLINE = _LOGICAL (Read)

True indicates that data values are to start on a new line below the name and type, and indented from the name. Otherwise the values are appended to the same line. [FALSE]

NLINES = LITERAL (Read)

The maximum number of lines in which data values of each primitive array component may be displayed, but excluding the continuation line used to show the last few values. Note that there may be several data values per line. There is no formatting of the values. If you require the whole of each array use NLINES = "ALL". Beware this facility can result in a large report, so select just the array or arrays you wish to trace. [1]

OBJECT = UNIV (Read)

The name of the data-system object to be traced. This may be a whole structure if the name of the container file is given, or it may be an object within the container file, or even a sub-section of an array component.

TYPIND = _INTEGER (Read)

Column indentation of the component's type with respect to the current indentation of the component's name. If the name plus dimensions cannot fit in the space provided alignment will be lost, since HDSTRACE insists that there be a gap of at least two columns. Note that HDS names can be up to 15 characters, and the dimension in the format (dim1,dim2,...) is abutted to the name. [15]

VALIND = _INTEGER (Read)

Column indentation of the component's value(s) with respect to the current indentation of the component's type provided NEWLINE is false. If, however, NEWLINE is true, VALIND is ignored and the value is indented by one column with respect to the component's name. If the type cannot fit in the space provided alignment will be lost, since HDSTRACE insists that there be a gap of at least two columns. HDS types can be up to 15 characters. [15]

WIDEPAGE = _LOGICAL (Read)

If true a 132-character-wide format is used to report the examination. Otherwise the format is 80 characters wide. [FALSE]

Notes:

This application allows far more flexibility in layout than earlier applications like LS and the original TRACE, though the order of the attributes of an object has been fixed and rearranged for standardisation, particularly for documentation purposes.