14

SUN/104.12

Starlink Project
Starlink User Note 104.12

P C T Rees
A J Chipperfield
T Jenness

23 July 2009

MERS (MSG and ERR)
Message and Error Reporting Systems

Version 2.1

Programmer’s Manual

Abstract

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.

Contents

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