Error(S_ADM)

Error -- C/C++ error management routines

Syntax

C++ interface

#include "sysAdmLib/sysAdmStd/basicIncl.h"

bool_t isOk;

unsigned stackSize;

void
errStatus_cl::errStatus_cl ()

void
errStatus_cl::Push (const intlMsg_t *errorMsgPtr,
                    ...);

void
errStatus_cl::VPush (const intlMsg_t *errorMsgPtr,
                     va_list          argsPtr);

void
errStatus_cl::PushUnixErr (int              errorNum,
                           const intlMsg_t *errorMsgPtr = NULL,
                           ...);

void
errStatus_cl::VPushUnixErr (int              errorNum,
                            const intlMsg_t *errorMsgPtr = NULL,
                            va_list          argsPtr);

void
errStatus_cl::PushNonStd (const intlMsg_t *errorMsgPtr,
                          int              exitCode,
                          const char      *message);

bool_t
errStatus_cl::AddData (const char **dataArgvPtr)

bool_t
errStatus_cl::AddData (const char *data1,
                       ...);

void
errStatus_cl::Clear ();

localMsg_t*
errStatus_cl::Value (int depth = 0);

const char **
errStatus_cl::Data (int depth = 0);

bool_t
errStatus_cl::Equal (const intlMsg_t *errorMsgPtr,
                     int              depth = 0)

bool_t
errStatus_cl::ModuleEqual (const moduleId_t *moduleIdPtr,
                           int               depth);

void
errStatus_cl::Output (FILE       *filePtr,
                      unsigned    options,
                      const char *prefix);

char *
errStatus_cl::Export (unsigned options);

bool_t
errStatus_cl::Import (const char *externStack)

C interface

#include "sysAdmLib/sysAdmStd/basicIncl.h"

errStatus_cl
ErrorNew ()

void
ErrorDelete (errStatus_cl objectPtr)

bool_t
ErrorIsOk (errStatus_cl objectPtr)

unsigned
ErrorStackSize (errStatus_cl objectPtr)

void
ErrorPush (errStatus_cl     objectPtr,
           const intlMsg_t *errorMsgPtr,
           ...)

void
ErrorVPush (errStatus_cl     objectPtr,
            const intlMsg_t *errorMsgPtr,
            ...)

void
ErrorPushUnixErr (errStatus_cl  objectPtr,
                  int           errorNum,
                  intlMsg_t    *errorMsgPtr,
                  ...)

void
ErrorVPushUnixErr (errStatus_cl  objectPtr,
                   int           errorNum,
                   intlMsg_t    *errorMsgPtr,
                   va_list       argsPtr);

void
ErrorPushNonStd (errStatus_cl     objectPtr,
                 const intlMsg_t *errorMsgPtr,
                 int              exitCode,
                 const char      *message);

void
ErrorAddData (errStatus_cl   objectPtr,
              const char   **dataArgvPtr);

void
ErrorAddDataArgs (errStatus_cl   objectPtr,
                  const char    *data1,
                  ...);

void
ErrorClear (errStatus_cl  objectPtr)

localMsg_t *
ErrorValue (errStatus_cl objectPtr,
            int          depth)

const char **
ErrorData (errStatus_cl objectPtr,
           int          depth);

bool_t
ErrorEqual (errStatus_cl     objectPtr,
            const intlMsg_t *errorMsgPtr,
            int              depth)

bool_t
ErrorModuleEqual (errStatus_cl     *objectPtr,
                  const moduleId_t *moduleIdPtr,
                  int               depth);

ErrorOutput (errStatus_cl  *objectPtr,
             FILE          *filePtr,
             unsigned       options,
             const char    *prefix);

char *
ErrorExport (errStatus_cl  objectPtr)

bool_t
ErrorImport (errStatus_cl  objectPtr,
             const char   *externStack);

Description

The error management interface includes C and C++ versions. The C interface parallels the member functions to the errStatus_cl class. The descriptions provided focus on the C++ interface, with the C version indicated in parentheses.

WARNING: If the main or the program is written in C instead of C++, then IntlMgrInit must be called before any use of either the internationalization or error managers, either directly or by indirectly calling C++ code that uses these facilities.

The errStatus_cl class manages the storage of active error status. Its main feature is an error stack that keeps track of all levels of failure that occurred because of a error. The stack consists of a series of frames which hold multiple error values. If a stack frame is filled, a new frame is allocated and linked into the stack. The first frame is allocated as part of the class, so that a memory allocation is only required if that frame overflows.

The top levels of the executables should have the class allocated in some manner suitable to their execution environment and then passes references to the class to lower levels. Generally a single instance of the class is needed in most threads of execution. The exception to this are execution threads used to handle an error that don't wish to destroy the original error status.

The convention for clearing an error status is to clear it as part of the error recovery code. Thus all procedures can expect an error status passed to them has a value of OK and they do not need to clear the error status to indicated success.

ErrorNew is the C language interface to allocate an errStatus object. This is only used if the main of a program is in C rather than C++.

ErrorDelete is the C language interface to delete an errStatus object. This is only used if the main of a program is in C rather than C++.

isOk is checked to determine if a routine returned an error. TRUE if no error is encountered, FALSE if there is an error. (C interface: ErrorIsOk.)

stackSize is the current size of the stack. A value of zero indicates that no entries are currently pushed onto the stack. This is useful when used in conjunction with ValueAtDepth to walk the stack. (C interface: ErrorStackSize.)

errStatus_cl is the constructor for the error status class.

Push pushes an localized error message onto the error stack. (C interface: ErrorPush.)

Vpush pushes an localized error message onto the error stack. This version is to be called after va_start has found the first parameter. (C interface: ErrorVPush.)

PushUnixErr pushes an error from a UNIX system or library call onto the error stack and optionally push an error that explains what application specific task was being attempted when the error occurred. (C interface: ErrorPushUnixErr.)

VPushUnixErr pushes an error from a UNIX system or library call onto the error stack and optionally pushes an error that explains what application specific task was being attempted when the error occurred. This version is to be called after va_start has found the first parameter. (C interface: ErrorVPushUnixErr.)

PushNonStd pushes an error from a program returning an error message that does not conform to the standard format. (C interface: ErrorPushNonStd.)

AddData (vector version) adds error data to the entry on the top of the error stack. Since it is not possible to retrieve arguments formatted into a localized message, this function allows inclusion of data that can then be accessed by code examining the error. The actual contents are defined on by the client on an error ID basis. This will append to existing extra information that is already associated with the top of stack entry. There must be an entry on the top of the stack. (C interface: ErrorAddData - vector version.)

AddData (argument list version) adds error data to the entry on the top of the error stack. Since it is not possible to retrieve arguments formatted into a localized message, this function allows inclusion of data that can then be accessed by code examining the error. The actual contents are defined on by the client on an error ID basis. This will append to existing extra information that is already associated with the top of stack entry. There must be an entry on the top of the stack. (C interface: ErrorAddDataArgs - argument list version.)

Clear clears the error stack. All values pushed onto the stack are removed and its value becomes OK. (C interface: ErrorClear.)

Value gets a value out of the error stack. If the entry has not been localized, localization will take place. Returns a pointer to the localized message on the top of the stack, or NULL if no error has occurred. The pointer will remain valid until the stack is altered. (C interface: ErrorValue.)

Data gets a pointer to the error data that were saved with the entry on the top of the stack. Returns a pointer to the error data vector terminated by a NULL entry. If there are extra arguments associated with the entry, a pointer to a vector containing just NULL is returned. This pointer is valid until the stack object is changed in any way. (C interface: ErrorData.)

Equal tests if a value in the stack is equal to an error constant. Returns TRUE if they are equal, FALSE if they are not. (C interface: ErrorEqual.)

ModuleEqual tests if a value in the stack belongs to a specified module. Returns TRUE if they are equal, FALSE if they are not. (C interface: ErrorModuleEqual.)

Output outputs an error stack to file in a human-readable format. (C interface: ErrorOutput.)

Export exports the error stack to the external format. options control the return of the exported message. (Optional; default is no options.) These options are available:

INTLMGR_STATIC: don't allocate the message dynamically, instead return a pointer to a static buffer within the object.
ERRORMGR_DYNAMIC: returns a dynamically-allocated string. If neither ERRORMGR_STATIC or ERRORMGR_DYNAMIC is supplied, static is assumed.

Output returns a Tcl-style list with each element an external format localized message. If the stack is empty, then a zero length string is still returned. The only option supported is ERRORMGR_OUTPUT_IDS, which specifies the output of symbolic IDs as well as the text. (Optional; default is 0.) If ERRORMGR_STATIC is specified, then it is a pointer to a static string. The string remains valid until another message is localized or the object is deleted. The pointer should not be freed. If ERRORMGR_DYNAMIC is specified, then it is a pointer to a dynamically allocated string. Use MemFree to release the storage, not delete. (C interface: ErrorExport.)

Import imports the error stack from the external format. The stack will be cleared of any data currently in it. Returns TRUE if the import succeeded, FALSE if the stack was invalid. (C interface: ErrorImport.)

Arguments

other arguments: arguments to format into the localized string as with sprintf. All arguments must have a corresponding format specification in the string taken from the message catalog.
objectPtr: a pointer to the errStatus object.
argsPtr: the pointer returned by va_start for the arguments to format into the message.
errorNum: the UNIX errno error number.
errorMsgPtr: a pointer to the error message id of the error to push onto the stack. This must be the statically allocated error message constant, as delayed localization may be implemented as an optimization, and a pointer kept to the declaration until it is needed. If NULL is specified, then no additional error is pushed. (Optional; default is NULL.)
exitCode: the exit code for program that produced the non-standard error, or zero if not applicable. The exit code will be added as the first error data entry associated with this error.
message: the message returned from a program that does not conform to the system administration internationalization standard.
dataArgvPtr: a vector of strings to include as extra information with the error on the top of the stack.
data1, ...: all the string arguments are gathered into an error data vector and appended to the entry on the top of the stack. NULL must be the last argument.
depth: depth in the stack of the value. Zero is the top of the stack. Must be less than stackSize. (Optional; default is zero.)
: moduleIdPtr pointer to the module Id to compare the entry against.
: externStack the external stack list. The caller retains ownership of the string if it is dynamically allocated.
filePtr: a pointer to the stdio structure for the file the stack is to be written to.
prefix: a string to output before each line, normally blanks or a tab. If NULL, no prefix string is output. (Optional; default is NULL.)