2 General Applications Programming

2-1 PAR SUN/114.1
ADAM Parameter System Routines

Provides access to “parameters” from within applications. These are the values which provide external control over an application (broadly similar to command line switches in UNIX, or command qualifiers in VMS). The PAR library allows these values to be obtained from the command line, by prompting the user, or by a variety of other mechanisms. The latest version of PAR includes a complete revision of the documentation and the addition of a new set of routines which permit parameter values to be obtained subject to various constraints.

2-2 NDF SUN/33.3
Extensible N-Dimensional Data Format

The Extensible N-Dimensional Data Format (NDF) is the Starlink format for storing bulk data in the form of N-dimensional arrays of numbers. It is typically used for storing spectra, images and similar datasets with higher dimensionality. The NDF format is based on the Hierarchical Data System, HDS (see SUN/92), and is extensible; not only does it provide a comprehensive set of standard ancillary items to describe the data, it can also be extended indefinitely to handle additional user-defined information of any type. SUN/33 describes the routines provided for accessing NDF data objects. It also discusses all the important NDF concepts and includes a selection of simple example applications.

2-3 MSG & ERR SUN/104.5
Message and Error Reporting

These provide a means for sending simple messages to the user of an application, together with a mechanism for reporting errors. They address many of the common problems encountered when formatting and displaying text through their use of “message tokens”, a concept which is also exploited by a number of other ADAM libraries. Most importantly, SUN/104 explains the ideas underlying the error handling scheme and “inherited status checking” used by the bulk of Starlink software.

2-4 CHR SUN/40.3
Character Handling

This library provides a simple way to perform many commonly required operations on Fortran character variables. These include: formatting and decoding numerical values, case conversion, analysing lists, string searching and character testing. This library is currently being upgraded to include a substantial number of new routines.

Graphics Library SUN/15.5

If you are unsure which high-level graphics library to use, then this is probably the one for you. It caters for most simple graph-plotting needs in a straightforward way (although it may not satisfy the more demanding user, for whom NCAR may be preferable – see SUN/88). The PGPLOT manual, entitled “PGPLOT – Graphics Subroutine Library”, is available from Starlink site managers in the Miscellaneous User Documents (MUD) series. SUN/15 describes the PGPLOT implementation on Starlink and shows how it integrates with SGS (see SUN/85). Note that the Applications Graphics Interface AGI also provides special routines for ease of use with PGPLOT (see SUN/48).

2-6 SGS SUN/85.5
Simple Graphics System SUN/113.2

SGS provides an easy-to-use interface to the Graphical Kernel System, GKS (see SUN/83). GKS is the underlying system which provides graphics “device-independence” but it is too low-level for general use, so calls to SGS routines may be used instead to perform simple plotting operations which do not amount to complete graph drawing. SGS is particularly useful for managing the layout of plotting surfaces which are to be filled with graphs drawn by higher-level routines. SUN/85 describes the “stand-alone” version of SGS, while SUN/113 describes additional routines which connect SGS to ADAM. The Applications Graphics Interface AGI also provides special routines for ease of use with SGS (see SUN/48).

2-7 FIO & RIO SUN/143
File Input/Output

Provides a set of routines to facilitate the reading and writing of Fortran files. These routines are not intended to replace the portable features of standard Fortran 77, but to help integrate these features with ADAM. They also hide some of the unavoidable, but non-portable, features of Fortran input/output. The latest version of FIO & RIO includes a complete revision of the documentation and new facilities to assist with error reporting and the portable classification of I/O error status values. Some rationalisation of routine naming has also occurred.

2-8 MAG SUN/171
Magnetic Tape Handling

Provides routines for accessing magnetic tapes and controlling tape drive operations via the ADAM parameter system. A feature is incorporated to minimise tape movement between applications by keeping track of the absolute tape position.

2-9 PRIMDAT SUN/39.1
Primitive Numerical Data Processing

Provides arithmetic and mathematical functions for processing primitive numerical data (real, integer & double precision values, etc.) including the non-standard data types (e.g. unsigned byte) which are used in ADAM but are not directly supported by Fortran 77. Routines are provided for both scalar values and arrays, with optional recognition of “undefined” data and methods for handling numerical errors such as overflow. A set of include files is also provided to define machine-dependent constants, including the important “bad” values used to flag undefined data. The systematic naming of files and routines in this library is designed to integrate with the GENERIC pre-processor (see SUN/7).

2-10 ICL SG/5.1
ADAM Command Language

Although ICL is really a command language from which applications are run, the writer of ADAM applications will still find it useful to refer to this document. It describes the ICL language, which includes a number of special features for controlling and communicating with ADAM tasks.

2-11 IFL SUN/115.1
ADAM Interface Module Reference Manual

An “interface module” (or “interface file”) acts as an interface between an application and its user. It describes to the ADAM parameter system (see SUN/114) how to obtain values and other information (e.g. help text) for an application’s parameters, and hence influences, in broad terms, how the application behaves. This document provides reference information describing in detail how to write an interface module.