NhlPError

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

The Fortran names of these functions are NhlFPError, NhlFErrGetId, NhlFErrNumMsgs, NhlFErrGetMsg, NhlFErrCleanMsgs, NhlFErrSpringMsg, and NhlFErrFPrintMsg. There are no Fortran bindings for NHLPEROR 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, format)
      character*(*) severity, format
      integer errnum

      subroutine NhlFErrGetId(id_ret)
      integer id_ret

      subroutine NhlFErrNumMsgs(nummsg)
      integer nummsg

      subroutine NhlFErrGetMsg(msgnum, severity, emsg, errorno, sysmsg
     +                         line, fname, ierr)
      integer msgnum, severity, 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: Specifies the severity level of the error message being reported.
errnum: Specifies a unique error number that references an error message from an installed error table.
format: Format string like printf.
...: Arguments for format string aka printf.
msgnum: Identifies the index of the error message to retrieve.
msgptr (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.
msg (C only): Pointer to an NhlErrMsg structure that fully describes an error message.
start (C only): Index to assign to the first error message in the table being installed.
tlen (C only): Length of the error table being installed.
etable (C only): Pointer to an error table to install.
buffer: Character buffer to place the formatted message into.
fp (C only): File pointer to print formatted error message to.
nummsg (Fortran only): Number of error messages currently buffered.
id_ret (Fortran only): Id for Error object.
iunit (Fortran only): Unit number to print formatted error message to.
emsg (Fortran only): Actual text of the error message.
errorno (Fortran only): Error number.
sysmsg (Fortran only): Actual text in the error table indexed by errorno.
line (Fortran only): Line number the error message was reported from, or 0.
fname (Fortran only): File name the error message was reported from, or NULL.
ierr (Fortran only): Error code.

Types

typedef struct _NhlErrMsg{
		NhlErrorTypes	severity;
		char		*msg;
		int		errorno;
		const char	*sysmsg;
		int		line;
		char		*fname;
} NhlErrMsg, *NhlErrMsgList;

severity: Specifies level of this error message.
msg: Actual Text of this error message.
errorno: Error number of this error message.
sysmsg: Actual Text in the error table indexed by errorno.
line: Line number the error message was reported from, or 0.
fname: File name the error message was reported from, or NULL.

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.

Copyright

Reference Manual Control Panel

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

$Revision: 1.13 $ $Date: 1995/07/26 23:28:20 $