SSN/4.14

Starlink Project
Starlink System Note 4.14

P.C.T. Rees
A.J. Chipperfield
P.W. Draper

31 Jul 2008

Copyright © 2001 Council for the Central Laboratory of the Research Councils
 Copyright © 2008 Science and Technology Facilities Council

EMS
Error Message Service

Version 2.2-0

Programmer’s Manual


Abstract

This document describes the Error Message Service, EMS, and its use in system software. The purpose of EMS is to provide facilities for constructing and storing error messages for future delivery to the user – usually via the Starlink Error Reporting System, ERR (see SUN/104). EMS can be regarded as a simplified version of ERR without the binding to any software environment (e.g. for message output or access to the parameter and data systems). The routines in this library conform to the error reporting conventions described in SUN/104. A knowledge of these conventions, and of the ADAM system (see SG/4), is assumed in what follows.

This document is intended for Starlink systems programmers and can safely be ignored by applications programmers and users.

Contents

1 Introduction
2 When to Use the Error Message Service
3 Reporting Errors
4 Message Tokens
5 Reporting Status, Fortran I/O and Operating System Errors
6 Message Output
 6.1 No EMS_FLUSH
 6.2 EMS without an environment
 6.3 EMS within an environment
7 Intercepting Messages
8 C Language Interface
9 Compiling and Linking with the Error Message Service
10 References
A Justification for EMS
B Using EMS together with POSIX threads
C Using EMS within ADAM system software
 C.1 Overview
 C.2 Message parameters
 C.3 Parameter references
 C.4 Reserved tokens
 C.5 Synchronising message output
 C.6 Routines specific to the ADAM fixed part
ERR_CLEAR – Return the error table to the default context and flush its contents
ERR_START – Initialise the Error Reporting System
ERR_STOP – Close the Error Reporting System

D Portability
 D.1 Porting prerequisites
 D.2 Operating system specific routines
E Include Files
F Fortran Subroutine List
G C Interface Function Prototypes
H Fortran Subroutine Specifications
EMS_ANNUL – Annul the contents of the current error context
EMS_BEGIN – Begin a new error reporting environment
EMS_ELOAD – Return error messages from the current error context
EMS_END – End the current error reporting environment
EMS_EXPND – Expand and return a message
EMS_FACER – Assign the message associated with a Starlink status value to a token
EMS_FIOER – Assign a Fortran I/O error message to a token
EMS_GTUNE – Inquire an EMS tuning parameter
EMS_LEVEL – Inquire the current error context level
EMS_MARK – Start a new error context
EMS_MLOAD – (Deprecated) Expand and return a message
EMS_RENEW – Renew any annulled message tokens in the current context
EMS_REP – Report an error message
EMS_RLSE – Release (end) an error context
EMS_SETx – Assign a value to a message token (concise)
EMS_STAT – Inquire the last reported error status
EMS_SYSER – Assign an operating system error message to a token
EMS_TUNE – Set an EMS tuning parameter