1 error handling interface hdf-eos workshop ix quincey koziol and ray lu 30 nov 2005

1

Error Handling Error Handling InterfaceInterface

HDF-EOS Workshop IXHDF-EOS Workshop IXQuincey Koziol and Ray LuQuincey Koziol and Ray Lu

30 Nov 200530 Nov 2005

2

ContentsContents

I.I. Basic conceptsBasic concepts

II.II. Basic error operationsBasic error operations

III.III. Advanced error operationsAdvanced error operations

3

Basic ConceptsBasic ConceptsAn example:An example:

HDF5-DIAG: Error detected in HDF5 (1.7.52) thread 0:HDF5-DIAG: Error detected in HDF5 (1.7.52) thread 0: #000: ../../hdf5_1.7/src/H5D.c line 1175 in H5Dcreate(): not a location #000: ../../hdf5_1.7/src/H5D.c line 1175 in H5Dcreate(): not a location

IDID major: Invalid arguments to routinemajor: Invalid arguments to routine minor: Inappropriate typeminor: Inappropriate type #001: ../../hdf5_1.7/src/H5Gloc.c line 162 in H5G_loc(): invalid object #001: ../../hdf5_1.7/src/H5Gloc.c line 162 in H5G_loc(): invalid object

IDID major: Invalid arguments to routinemajor: Invalid arguments to routine minor: Bad valueminor: Bad value

Library’s error report:Library’s error report: automatic automatic reset for each API function call.reset for each API function call.

Concepts:Concepts: Error stackError stack Error recordError record Error message: major and minorError message: major and minor Error descriptionError description

4

Basic Error OperationsBasic Error Operations

1. To print error stack explicitly:1. To print error stack explicitly:H5Eprint_stackH5Eprint_stack(hid_t error_stack, FILE* stream)(hid_t error_stack, FILE* stream)

2. To clear error stack:2. To clear error stack:H5Eclear_stackH5Eclear_stack(hid_t error_stack)(hid_t error_stack)

3. To disable error stack printing:3. To disable error stack printing:H5Eset_auto_stackH5Eset_auto_stack(hid_t error_stack, (hid_t error_stack,

H5E_auto_stack_t func, void *client_data)H5E_auto_stack_t func, void *client_data)

H5Eget_auto_stackH5Eget_auto_stack(hid_t error_stack,(hid_t error_stack,H5E_auto_stack_t *func, void *client_data)H5E_auto_stack_t *func, void *client_data)

typedef herr_t (*typedef herr_t (*H5E_auto_stack_tH5E_auto_stack_t)(hid_t estack, )(hid_t estack, void *client_data)void *client_data)

5

Basic Error OperationsBasic Error OperationsExample: Turn off error printing while “probing” a function.Example: Turn off error printing while “probing” a function.

/* Save old error handler *//* Save old error handler */H5E_auto_stack_t old_func;H5E_auto_stack_t old_func;void void *old_client_data; *old_client_data;

H5Eget_auto_stack(error_stack, &old_func, &old_client_data);H5Eget_auto_stack(error_stack, &old_func, &old_client_data);

/* Turn off error handling *//* Turn off error handling */H5Eset_auto_stack(error_stack, NULL, NULL);H5Eset_auto_stack(error_stack, NULL, NULL);

/* Probe. Likely to fail, but that’s okay *//* Probe. Likely to fail, but that’s okay */status = H5Fopen(……);status = H5Fopen(……);

::/* Restore previous error handler *//* Restore previous error handler */H5Eset_auto_stack(error_stack, old_func, old_client_data);H5Eset_auto_stack(error_stack, old_func, old_client_data);

Another example: the library provides a cleaner way to do the Another example: the library provides a cleaner way to do the same. same. H5E_BEGIN_TRY {H5E_BEGIN_TRY {

status = H5Fopen(……);status = H5Fopen(……);} H5E_END_TRY; } H5E_END_TRY;

6


4. To customize printing of error 4. To customize printing of error stack:stack:Example:Example:

herr_t my_hdf5_error_print(hid_t err_stack, void *unused){ herr_t my_hdf5_error_print(hid_t err_stack, void *unused){ fprintf (stderr, "An HDF5 error was detected. Bye.\n"); fprintf (stderr, "An HDF5 error was detected. Bye.\n");

exit (1);exit (1);

}}

The function is installed as the error handler by sayingThe function is installed as the error handler by saying

H5Eset_auto_stack(H5E_DEFAULT, my_hdf5_error_handler, NULL);H5Eset_auto_stack(H5E_DEFAULT, my_hdf5_error_handler, NULL);

7


5. To walk through error stack:5. To walk through error stack:H5Ewalk_stackH5Ewalk_stack(hid_t err_stack, H5E_direction_t dir,(hid_t err_stack, H5E_direction_t dir,

H5E_walk_t func, void *client_data)H5E_walk_t func, void *client_data)

typedef herr_t (*typedef herr_t (*H5E_walk_tH5E_walk_t)(unsigned )(unsigned nn, H5E_error_t , H5E_error_t **eptreptr, , void *void *client_dataclient_data))

typedef struct { typedef struct { hid_thid_t cls_id; cls_id; hid_t hid_t maj_nummaj_num; ; hid_t hid_t min_nummin_num; ; const char *const char *func_namefunc_name; ; const char *const char *file_namefile_name; ; unsigned unsigned lineline; ; const char *const char *descdesc;;

} } H5E_error_tH5E_error_t; ;

8

Advanced Error Advanced Error OperationsOperations

A new feature to allow application to push its own error records onto A new feature to allow application to push its own error records onto the HDF5 error stack.the HDF5 error stack.

Example:Example:

Error Test-DIAG: Error detected in Error Program (1.0) thread 0:Error Test-DIAG: Error detected in Error Program (1.0) thread 0: #000: ../../hdf5_1.7/test/error_example.c line 164 in advanced_operations(): H5Dcreate #000: ../../hdf5_1.7/test/error_example.c line 164 in advanced_operations(): H5Dcreate

failedfailed major: Error in APImajor: Error in API minor: Error in H5Dcreateminor: Error in H5DcreateHDF5-DIAG: Error detected in HDF5 (1.7.52) thread 0:HDF5-DIAG: Error detected in HDF5 (1.7.52) thread 0: #001: ../../hdf5_1.7/src/H5D.c line 1175 in H5Dcreate(): not a location ID#001: ../../hdf5_1.7/src/H5D.c line 1175 in H5Dcreate(): not a location ID major: Invalid arguments to routinemajor: Invalid arguments to routine minor: Inappropriate typeminor: Inappropriate type #002: ../../hdf5_1.7/src/H5Gloc.c line 162 in H5G_loc(): invalid object ID#002: ../../hdf5_1.7/src/H5Gloc.c line 162 in H5G_loc(): invalid object ID major: Invalid arguments to routinemajor: Invalid arguments to routine minor: Bad valueminor: Bad value

More concepts:More concepts: Error classError class Library nameLibrary name Library versionLibrary version

9


1.1. To register application with error API:To register application with error API:

H5Eregister_classH5Eregister_class((const char*const char* cls_name, cls_name, const char*const char* lib_name, lib_name, const char*const char* version) version)

H5Ecreate_msgH5Ecreate_msg((hid_thid_t class, class, H5E_type_tH5E_type_t msg_type, msg_type, const char*const char* mesg) mesg)

H5Eget_class_nameH5Eget_class_name((hid_thid_t class_id, class_id, char*char* name, name, size_tsize_t size) size)

H5Eget_msgH5Eget_msg((hid_thid_t mesg_id, mesg_id, H5E_type_t* H5E_type_t* mesg_type, mesg_type, char*char* mesg, mesg, size_tsize_t size) size)

H5Eclose_msgH5Eclose_msg((hid_thid_t mesg_id) mesg_id)

H5Eunregister_classH5Eunregister_class((hid_thid_t class_id) class_id)

10

Advance Error Advance Error OperationsOperations

Example:Example:

An application creates an error class and error messages.An application creates an error class and error messages.

/* Create an error class *//* Create an error class */class_id = H5Eregister_class(ERR_CLS_NAME, PROG_NAME, PROG_VERS);class_id = H5Eregister_class(ERR_CLS_NAME, PROG_NAME, PROG_VERS);

/* Create a major error message in the class *//* Create a major error message in the class */maj_id = H5Ecreate_msg(class_id, H5E_MAJOR, “… …”);maj_id = H5Ecreate_msg(class_id, H5E_MAJOR, “… …”);

/* Create a minor error message in the class *//* Create a minor error message in the class */min_id = H5Ecreate_msg(class_id, H5E_MINOR, “… …”);min_id = H5Ecreate_msg(class_id, H5E_MINOR, “… …”);

Application closes error messages and un-registers error Application closes error messages and un-registers error class.class.

H5Eclose_msg(maj_id);H5Eclose_msg(maj_id);H5Eclose_msg(min_id);H5Eclose_msg(min_id);H5Eunregister_class(class_id);H5Eunregister_class(class_id);

11


2. To manipulate error stack:2. To manipulate error stack:

H5Eget_current_stackH5Eget_current_stack((voidvoid))H5Eset_current_stackH5Eset_current_stack((hid_thid_t error_stack) error_stack)H5Epush_stackH5Epush_stack((hid_thid_t error_stack, error_stack, const char*const char* file, file,

const char*const char* func, func, unsignedunsigned line, line, hid_thid_t cls_id, cls_id, hid_thid_t major_id, major_id, hid_thid_t minor_id, minor_id, const const char*char* desc, … )desc, … )H5EpopH5Epop((hid_thid_t error_stack, error_stack, size_tsize_t count) count)H5Eget_numH5Eget_num((hid_thid_t error_stack) error_stack)H5Eclear_stackH5Eclear_stack((hid_thid_t error_stack) error_stack)H5Eclose_stackH5Eclose_stack((hid_thid_t error_stack) error_stack)

12


Example:Example:/* Make call to HDF5 I/O routine *//* Make call to HDF5 I/O routine */if((dataset = H5Dcreate(FAKE_ID, DSET_NAME, H5T_STD_I32BE, if((dataset = H5Dcreate(FAKE_ID, DSET_NAME, H5T_STD_I32BE,

space, H5P_DEFAULT))<0)space, H5P_DEFAULT))<0){{

/* Push client error onto error stack *//* Push client error onto error stack */H5Epush_stack(H5E_DEFAULT, __FILE__, FUNC_adv, __LINE__, H5Epush_stack(H5E_DEFAULT, __FILE__, FUNC_adv, __LINE__,

ERR_CLS, ERR_MAJ_API, ERR_MIN_CREATE,ERR_CLS, ERR_MAJ_API, ERR_MIN_CREATE, "H5Dcreate failed");"H5Dcreate failed");

/* Print the error stack explicitly */ /* Print the error stack explicitly */ H5Eprint_stack(H5E_DEFAULT, stderr); H5Eprint_stack(H5E_DEFAULT, stderr);

}}

13


Another example:Another example:H5E_BEGIN_TRY {H5E_BEGIN_TRY {

ret = H5Dwrite(dset_id, mem_type_id, mem_space_id, file_space_id, ret = H5Dwrite(dset_id, mem_type_id, mem_space_id, file_space_id, dset_xfer_plist_id, buf);dset_xfer_plist_id, buf);

} H5E_END_TRY;} H5E_END_TRY;

if(ret<0) {if(ret<0) {/* Push client error onto error stack */ /* Push client error onto error stack */ H5Epush_stack(H5E_DEFAULT,FILE,FUNC,LINE,cls_id, H5Epush_stack(H5E_DEFAULT,FILE,FUNC,LINE,cls_id,

CLIENT_ERR_MAJ_IO, CLIENT_ERR_MINOR_HDF5,"H5Dwrite failed");CLIENT_ERR_MAJ_IO, CLIENT_ERR_MINOR_HDF5,"H5Dwrite failed");

/* Preserve the error stack by assigning an object handle to it */ /* Preserve the error stack by assigning an object handle to it */ error_stack = H5Eget_current_stack(); error_stack = H5Eget_current_stack();

/* Close dataset *//* Close dataset */H5Dclose(dset_id); H5Dclose(dset_id);

/* Replace the current error stack with the preserved one */ /* Replace the current error stack with the preserved one */ H5Eset_current_stack(error_stack);H5Eset_current_stack(error_stack);Return(1);Return(1);

} }

14

ContentsContents

I.I. Basic conceptsBasic concepts

II.II. Basic error operationsBasic error operations

III.III. Advanced error operationsAdvanced error operations

15

DocumentsDocuments

User’s Guide: User’s Guide: http://hdf.ncsa.uiuc.edu/HDF5/doc_dev_snapshot/HE9-http://hdf.ncsa.uiuc.edu/HDF5/doc_dev_snapshot/HE9-ErrorAPI,DataConversion/ErrorHandling-H5E-July05.pdfErrorAPI,DataConversion/ErrorHandling-H5E-July05.pdf

Reference Manual: Reference Manual: http://hdf.ncsa.uiuc.edu/HDF5/doc_dev_snapshot/H5_dev/RM/RM_H5E.hthttp://hdf.ncsa.uiuc.edu/HDF5/doc_dev_snapshot/H5_dev/RM/RM_H5E.htmlml

Acknowledgement: Acknowledgement: This presentation is based upon work supported in part by a This presentation is based upon work supported in part by a Cooperative Agreement with the National Aeronautics and Space Cooperative Agreement with the National Aeronautics and Space Administration (NASA) under NASA grant NNG05GC60A. Any Administration (NASA) under NASA grant NNG05GC60A. Any opinions, findings, and conclusions or recommendations opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not expressed in this material are those of the author(s) and do not necessarily reflect the views of NASA. Other support provided by necessarily reflect the views of NASA. Other support provided by NCSA and other sponsors and agencies NCSA and other sponsors and agencies (http://hdf.ncsa.uiuc.edu/acknowledge.html). (http://hdf.ncsa.uiuc.edu/acknowledge.html).