Starlink Project
Starlink User Note 104.12

P C T Rees
A J Chipperfield
T Jenness

23 July 2009

Message and Error Reporting Systems

Version 2.1

Programmer’s Manual


This document describes two C subroutine libraries, MSG and ERR, which can be used to provide informational text to the user from any application program. It also describes the Fortran interface for the two libraries.

The Message Reporting System, MSG, is used for reporting non-error information and the Error Reporting System, ERR, is used specifically for reporting error messages. The conventions for reporting errors from Starlink software are also discussed in detail.

This document is recommended reading for anyone writing applications software for use on Starlink.


1 Introduction
2 MSG – Message Reporting System
 2.1 Overview
 2.2 Reporting messages
 2.3 Conditional message reporting
 2.4 Conditional Message Reporting and msgOut
 2.5 Message tokens
 2.6 Formatted tokens from C
 2.7 Formatted tokens from Fortran
 2.8 Direct formatted message output with msgOut
 2.9 Including escape characters in messages
 2.10 Intercepting messages
 2.11 Renewing annulled message tokens
 2.12 Resilience
3 ERR – Error Reporting System
 3.1 Overview
 3.2 Inherited status checking
 3.3 Setting and defining status values
 3.4 Reporting errors
 3.5 Message tokens in error messages
 3.6 When to report an error
 3.7 The content of error messages
 3.8 Adding contextual information
 3.9 Deferred error reporting
 3.10 Error table limits
 3.11 Format of delivered messages
 3.12 Routines which perform “cleaning-up” operations
 3.13 Intercepting error messages
 3.14 Protecting tokens
 3.15 Reporting Status, Fortran I/O and operating system errors
 3.16 Incorporating foreign routines
 3.17 Converting existing subroutine libraries
4 Tuning
5 The C Interface
6 Compiling and Linking with MSG and ERR
7 References
A Include Files
B Subroutine List
 B.1 Message System subroutines
 B.2 Error System subroutines
 B.3 ADAM-special user subroutines
 B.4 ADAM-special system subroutines
C C Interface Function Prototypes
D Subroutine Specifications
 D.1 Message System subroutines
MSG_BELL – Deliver an ASCII BEL character
MSG_BLANK – Output a blank line
MSG_BLANKIF – Conditionally output a blank line
MSG_FMTx – Assign a value to a message token (formatted)
MSG_IFLEV – Return the current filter level for conditional message output
MSG_IFSET – Set the filter level for conditional message output
MSG_LOAD – Expand and return a message
MSG_OUT – Output a message
MSG_OUTIF – Conditionally deliver the text of a message to the user
MSG_RENEW – Renew any annulled message tokens in the current context
MSG_SETx – Assign a value to a message token (concise)
MSG_TUNE – Set an MSG tuning parameter

 D.2 Error System subroutines
ERR_ANNUL – Annul the contents of the current error context
ERR_BEGIN – Create a new error reporting environment
ERR_END – End the current error reporting environment
ERR_FACER – Assign a Starlink facility status message to a token
ERR_FIOER – Assign a Fortran I/O error message to a token
ERR_FLBEL – Deliver an ASCII BEL and flush the current error context
ERR_FLUSH – Flush the current error context
ERR_LEVEL – Inquire the current error context level
ERR_LOAD – Return error messages from the current error context
ERR_MARK – Mark (start) a new error context
ERR_REP – Report an error message
ERR_RLSE – Release (end) the current error context
ERR_STAT – Inquire the last reported error status
ERR_SYSER – Assign an operating system error message to a token
ERR_TUNE – Set an ERR tuning parameter

 D.3 Deprecated Routine ERR_OUT
ERR_OUT – Report a message then flush and annul the current error context.

E Using MSG and ERR within ADAM
 E.1 Overview
 E.2 Using MSG within ADAM applications
  E.2.1 Message parameters
  E.2.2 Parameter references
  E.2.3 Using program parameters as tokens
  E.2.4 Reserved token STATUS
  E.2.5 Getting the conditional output level
  E.2.6 Synchronising message output
 E.3 Using ERR within ADAM applications
  E.3.1 Error message parameters
  E.3.2 Initial error context level
  E.3.3 Reserved token STATUS
  E.3.4 Returning the status to the environment
 E.4 Using the Error Message Service for ADAM system programming
 E.5 ADAM-special subroutine specifications
MSG_IFGET – Get the filter level for conditional message output from the ADAM parameter system
MSG_SYNC – Synchronise message output via the user interface

F Portability
 F.1 Overview
 F.2 Coding and porting prerequisites
 F.3 Operating system specific routines
G Calculating Globally Unique Error Codes
H Changes and New Features in Version 1.4
I Changes and New Features in Version 1.4-1
J Changes and New Features in Version 1.5
K Changes and New Features in Version 1.6
L Changes and New Features in Version 1.7
M Changes in Version 1.7-1
N Changes in Version 1.8
O Changes in Version 1.8-1
P Changes in Version 1.8-2