NhlPError

NhlPError, NHLPERROR, NhlErrGetId, NhlErrNumMsgs, NhlErrGetMsg, NhlErrCleanMsgs, NhlErrAddTable, NhlErrSPrintMsg, NhlErrFPrintMsg

The Fortran names of these functions are NhlFPError, NhlFErrGetId, NhlFErrNumMsgs, NhlFErrGetMsg, NhlFErrCleanMsgs, NhlFErrSprintMsg, and NhlFErrFPrintMsg. There are no Fortran bindings for NHLPERROR and NhlErrAddTable.

Error handling functions for the HLU library.


C synopsis

#include <ncarg/hlu/hlu.h>

const char *NhlPError(
		NhlErrorTypes	severity,
		int		errnum,
		char		*format,
		...
		)

void NHLPERROR((
		NhlErrorTypes	severity,
		int		errnum,
		char		*format,
		...
		))

int NhlErrGetId()

int NhlErrNumMsgs()

NhlErrorTypes NhlErrGetMsg(
		int		msgnum,
		const NhlErrMsg	**msgptr
		)

NhlErrorTypes NhlErrClearMsgs()

NhlErrorTypes NhlErrAddTable(
		int		start,
		int		tlen,
		const char	**etable
		)

char *NhlErrSPrintMsg(
		char		*buffer,
		const NhlErrMsg	*msg
		)

const char *NhlErrFPrintMsg(
		FILE		*fp,
		const NhlErrMsg	*msg
		)


Fortran synopsis

      subroutine NhlFPError(severity, errnum, message)
      character*(*) severity, message
      integer errnum

      subroutine NhlFErrGetId(id_ret)
      integer id_ret

      subroutine NhlFErrNumMsgs(nummsg)
      integer nummsg

      subroutine NhlFErrGetMsg(msgnum, sev, emsg, errorno, sysmsg
     +                         line, fname, ierr)
      integer msgnum, sev, errorno, line, ierr
      character*(*) emsg, sysmsg, fname

      subroutine NhlFErrClearMsgs(ierr)
      integer ierr

      subroutine NhlFErrSprintMsg(buffer, msgnum)
      character*(*) buffer
      integer imsg

      subroutine NhlFErrFprintMsg(iunit, msgnum)
      integer iunit, imsg

Arguments

severity (input)
Specifies the severity level of the error message being reported.
errnum (input)
Specifies a unique error number that references an error message from an installed error table.
format (input, C only)
Message to report with argument replacement like format string for printf.
... (input, C only)
Arguments for format string aka printf.
msgnum (input)
Identifies the index of the error message to retrieve.
msgptr (output, C only)
Pointer to an NhlErrMsg pointer that fully describes an error message that was reported. This arg is used to retrieve a pointer to an NhlErrMsg.
start (input, C only)
Index to assign to the first error message in the table being installed.
tlen (input, C only)
Length of the error table being installed.
etable (input, C only)
Pointer to an error table to install.
buffer (output)
Character buffer to place the formatted message into.
msg (input, C only)
Pointer to an NhlErrMsg structure that fully describes an error message.
fp (input, C only)
File pointer to print formatted error message to.
message (input, Fortran only)
Message to report.
id_ret (output, Fortran only)
Id for Error object.
nummsg (output, Fortran only)
Number of error messages currently buffered.
sev (output, Fortran only)
Indicates the severity level of the message being retrieved.
emsg (output, Fortran only)
Actual text of the error message being retrieved. This corresponds to the format argument (after argument replacement) if the error was reported from C and the message argument if it was reported from Fortran.
errorno (output, Fortran only)
Error number of the error message being retrieved.
sysmsg (output, Fortran only)
Text from the error table for the message being retrieved.
line (output, Fortran only)
Line number the error message was reported from, or 0.
fname (output, Fortran only)
File name the error message was reported from, or NULL.
ierr (output, Fortran only)
Error code.
iunit (input, Fortran only)
Unit number to print formatted error message to.

Types

Type name:		NhlTErrorTypes
Definition:
typedef enum _NhlErrType{
	NhlFATAL	= -4,	/* "FATAL"	*/
	NhlWARNING	= -3,	/* "WARNING"	*/
	NhlINFO		= -2,	/* "INFO"	*/
	NhlNOERROR	= -1	/* "NOERROR"	*/
} NhlErrorTypes;
Type name:		<none>
typedef struct _NhlErrMsg{
		NhlErrorTypes	severity;
		char		*msg;
		int		errorno;
		const char	*sysmsg;
		int		line;
		char		*fname;
} NhlErrMsg, *NhlErrMsgList;

Description

The error handling module of the HLU library has two purposes. First, it allows the programmer to report errors using the same error mechanism as the HLU library if they want to. Second, it allows the programmer to configure the way those errors are reported.

The NhlPError function is used to report errors to the error module. The fmt and arg parameters are parsed in the same way as printf parses its arguments. The NHLPERROR macro is used in the same way as the NhlPError function except that it prepends File and Line information to the error message. Notice the double parentheses, this was necessary to get the macro to take variable number arguments.

Another function that is useful to programmers--if they plan to use the NhlPError function to report errors--is NhlErrAddTable. This function allows the programmer to add an additional error table in the same format as the system error table. The values 0 - 1000 are reserved for the system error table. The error module will not allow overlapping error tables to be installed.

The error module was implemented as another object in the Nhl library. This is important because all configuration of the Error module is done by setting resources in this object. The NhlOpen function creates the Error object so the resources are not available to the programmer at create time, except by using a resource file. However the programmer does have NhlSetValues and NhlGetValues access. The NhlErrGetId function is provided so the programmer can get the Id that is necessary to set or get resources in an object.

The rest of the functions are provided to allow the programmer to do as much of the error handling as they want. They are really only useful if the error object's NhlNbufferErrors resource is set to True.

The NhlErrNumMsgs function is provided so the programmer can query the error object to find out how many error messages it currently has buffered. The NhlErrGetMsg function is used to retrieve a pointer to the error message indexed by msgnum. The error message is saved internally in a NhlErrMsg structure. The index is from 1 to NhlErrNumMsgs.

The NhlErrClearMsgs function is used to clear the Error object's internal message buffer. The NhlErrFPrintMsg and NhlErrSPrintMsg functions were provided so the programmer can print messages in the NhlErrMsg structure format in the same way the error object prints them out internally.

The error object is destroyed when the NhlClose function is called. The programmer can use the NhlPError function when the error object doesn't exist (before NhlOpen or after NhlClose). However, all messages are printed to stderr because no configuration is possible.


Return values

The NhlPError function returns a const char* that points to the formatted error message.

The NHLPERROR macro does not return a value.

The NhlErrGetId function returns an int that is a unique id for the Error object.

The NhlErrNumMsgs function returns an int that is the number of error messages that have been buffered in the Error object.

The NhlErrGetMsg, NhlErrClearMsgs, and NhlErrAddTable functions return values of type NhlErrorTypes. These error eunctions return NOERROR if they were able to complete the function, and FATAL otherwise.

The NhlErrSPrintMsg function returns a pointer to the buffer provided, or NULL on error.

The NhlErrFPrintMsg function returns a pointer to a const char buffer that contains the formatted string that was printed to the fp argument, or NULL on error.


See also


Copyright

Copyright 1987-1999 University Corporation for Atmospheric Research
The use of this Software is governed by a License Agreement.

NCAR Graphics is a registered trademark of the University Corporation for Atmospheric Research.

Reference Manual Control Panel

NG4.1 Home, Index, Examples, Glossary, Feedback, Ref Contents, Ref WhereAmI?


$Revision: 1.17 $ $Date: 1998/06/15 21:26:24 $