The following are definitions about and error that has occurred:

int errorCode

The returned int by a function that has experienced an error. This is usually a large negative number that can be decoded into the following.

int severity

The severity of the error, ranging from 1 (information) to 9 (memory error):

STATUS_OKAY (0): if no error has occurred.
INFORMATION (1): An inconsequential action failed.
WARNING (2): Unable to compete the request given.
INVALID_ARGUMENT (3): A invalid argument (e.g., a null pointer) was passed to a function.
WARNING_NO_WRITE_ACCESS (4): You cannot write to the file.
WARNING_NO_FILE_ACCESS (5): You cannot read or write to the file.
WRITE_ERROR (6): An error was thrown on a write action.
READ_ERROR (7): An error was thrown on a read action. The file maybe damaged. It might be recovered by a squeeze, at the user's discretion.
CORRUPT_FILE (8): Flags and pointers are not correct, indicating that something has changed the file outside of DSS.
MEMORY_ERROR (9): Flags and pointers in memory are not correct.

int errorType
        Indicates what kind of error occurred and what should be done about it:

0 - Warning or Informational (do nothing)
1 - Access error (file does not exist, permission problem, ...) (User needs to fix.)
2 - File error (broken file, junk in file) (Squeeze the file)
3 - Memory error or memory exhausted. Exit program without saving anything.

int errorNumber

The actual number of the error (usually a 2 digit number).

char *errorMessage

A description of the error. This is what is printed to output when an error occurs.

int systemError

If the operating system threw an error (e.g., no permission to write), then this is error number.

char *systemErrorMessage

If the error was a system error (e.g., no permission to write), then this is that message, otherwise blank.

long long lastAddress

The last file address in memory when the error occurred.

int functionID

A numerical identifier for the function where the error occurred.

char *functionName

The name of the function where the error occurred

int calledByFunction

A numerical identifier for the name of the highest level function when the error occurred.

char *calledByFunctionName

The name of the highest level function when the error occurred

Notes:

A severity of CORRUPT_FILE (8) or MEMORY_ERROR (9) indicates you should exit the program. Do not close or attempt other operations, as they will fail or cause the program to crash. MEMORY_ERROR (9) generally indicates that memory is exhausted (and is not all that uncommon.)

zerror

Description:  When an error occurs, this returns specifics about the last error, in a struct from.

Declaration:

int zerror(hec_zdssLastError *errorStruct);

Parameters:

hec_zdssLastError *errorStruct

A struct that will contain specifics about the last error.

Returns:

STATUS_OKAY (0):  No error.
<0:  The severity of the error, ranging from 1 (informational) to 9 (memory error).

Struct:

zdssLastError:

typedef struct {
       int errorCode;
       int severity;
       int errorNumber;
       int errorType;
       int systemError;
       long long lastAddress;
       int functionID;
       int calledByFunction;
       char errorMessage[MAX_LEN_ERROR_MESS];
       char systemErrorMessage[MAX_LEN_ERROR_MESS];
       char lastPathname[MAX_PATHNAME_SIZE];
       char filename[MAX_FILENAME_LENGTH];
} hec_zdssLastError;

Notes:

A more convienent function to obtain error information, although other errors may occur before this call (often where there is a memory or corrupt file error.)

zerrorCheck

Description: Quick functions to determine if an error has occurred (regardless of DSS file.)

Declaration:

int zerrorCheck();

Returns:

STATUS_OKAY (0): No error.
<0: The severity of the error, ranging from 1 (informational) to 9 (memory error).

Notes:

This function checks a general error flag in DSS and does not require the ifltab. It should be used when an error check is needed, but there are multiple files opened or you do not have access to ifltab. Usually, the return status from an operation is check instead of using this function.

A return severity of CORRUPT_FILE (8) or MEMORY_ERROR (9) indicates you should exit the program. Do not close or attempt other operations, as they will fail or cause the program to crash. MEMORY_ERROR (9) generally indicates that memory is exhausted (and is not all that uncommon.)

zerrorCode

Description: Quick functions to determine if an error has occurred.

Declaration:

int zerrorCode(long long *ifltab);

Parameters:

long long *ifltab

The file table of the opened DSS file (from zopen)

Returns:

STATUS_OKAY (0): No error.
<0: Error code, a large negative number. zerrorSpecifics can be used to decode.

Notes:

Usually, the return status from an operation is checked instead of using this function.

zerrorSpecifics

Description: When an error occurs, this returns specifics about that error. If you do not have the error code, pass in zero to use that last error that occurred.

Declaration:

void zerrorSpecifics(int errorCode, int *severity, int *errorType, int *errorNumber, char *errorMessage, size_t sizeofErrorMessage, char *systemMessage, size_t sizeofSystemMessage, char *functionName, size_t sizeofFunctionName, char *calledByFunction, size_t sizeofCalledByFunction);

Parameters:

int errorCode (input)

The error code returned by a function that has experienced an error. This is usually a large negative number.

int *severity

Returns the severity of the error, ranging from 1 (information) to 9 (memory error):

STATUS_OKAY (0): if no error has occurred.
INFORMATION (1): An inconsequential action failed.
WARNING (2): Unable to compete the request given.
INVALID_ARGUMENT (3): A invalid argument (e.g., a null pointer) was passed to a function.
WARNING_NO_WRITE_ACCESS (4): You cannot write to the file.
WARNING_NO_FILE_ACCESS (5): You cannot read or write to the file.
WRITE_ERROR (6): An error was thrown on a write action.
READ_ERROR (7): An error was thrown on a read action. The file maybe damaged. It might be recovered by a squeeze, at the user's discretion.
CORRUPT_FILE (8): Flags and pointers are not correct, indicating that something has changed the file outside of DSS.
MEMORY_ERROR (9): Flags and pointers in memory are not correct.

int *errorType

Indicates what kind of error occurred and what should be done about it:

0 - Warning or Informational (do nothing)
1 - Access error (file does not exist, permission problem, ...) (User needs to fix.)
2 - File error (broken file, junk in file) (Squeeze file)
3 - Memory error or memory exhausted. Exit program without saving anything.

int *errorNumber

Returns the actual number of the error (usually a 2 digit number)

char *errorMessage

Returns a description of the error

size_t sizeofErrorMessage (input)

The size of string errorMessage

int *systemMessage

If the error was a system error (e.g., no permission to write), then this is that message, otherwise blank.

size_t sizeofSystemMessage (input)

The size of string systemMessage

int *functionName

The name of the function where the error occurred

size_t sizeofFunctionName (input)

The size of string functionName

int *calledByFunction

The name of the highest level function when the error occurred

size_t sizeofFunctionName (input)

The size of string functionName

See Also:

Zerror

zerrorStructClear

Description: Clears the last error.

Declaration:

void zerrorStructClear();

Notes:

Usually, the error struct is not saved for informational or warning errors. The struct is saved for more sever errors, but usually requires significant action that might make this function unnecessary. For example, if a data set is missing, the struct is not filled and a program should be able to handle that situation. But if a file cannot be accessed, most programs will need to have that resolved before continuing. And if the error is memory exhaustion, the program should exit quickly.

zisError

Description: A convenience function returns 1 (true) if the passed in status is an error.

Declaration:

int zisError (int status);

Parameters:

int status

The status return from a DSS function.

Returns:

0: No error.
1: The status shows an error.

Notes:

Meant to be used in the following form.

status = zcheck(ifltab, pathname);
if (zisError(status)) {
    zerror(&errorStruct);
    notifyUser(&errorStruct); // (e.g., display an error dialog)
    if (zerrorSeverity(status) >= zdssErrorSeverity.MEMORY_ERROR) exitProg();
    return status;
}