Error Codes

This page describes the error codes used in the various Shore Storage Manager modules.

These numbers are generated by the Perl script

 tools/errors.pl

This page is of interest to those who wish to use this tool to generate their own sets of error codes.

Error Codes and Modules

Error codes are unsigned integers. Each error code has associated metadata, which consists of a descriptive string and a name (either by way of an enumeration, or by a C-preprocessor-defined name).

The integer values associated with error code names, the descriptive strings, the enumerations, and the C Preprocessor macros are generated by the Perl script. Error codes are grouped into modules, so that all the error codes for a software module and their metadata are kept together. Each module is given a mask, which is folded into the values assigned to the errorcodes. This keeps the error codes for different software modules distinct. The software that manages error codes keeps a (global) list of all the modules of error codes. Each software layer that uses the error codes must invoke a method to `install' its module in the global list, preferably at server start-up time, in the main thread, using w_error_t::insert, which is called by a Perl-generated method <class>init_errorcodes();-

Generating Sets of Error Codes

Generating the codes is best described by way of an example. The following example is taken from the Shore Storage Manager.

The script takes one of two mutually exclusive options, and a file name. One or the other of the options (-d, -e) is required:

 $(SHORE_SOURCES)/tools/errors.pl -d <input-file>
    or
 $(SHORE_SOURCES)/tools/errors.pl -e <input-file>

In the first case (-d) the named constants are generated as C preprocessor defined constants. The prefix of the generated names is capitalized and separated from the rest of the name by an underscore character.

In the second case (-e) the named constants are generated as members of an anonymous enumeration. The prefix of the generated names is taken, case unchanged, from the input file.

 e = 0x00080000 "Storage Manager" smlevel_0 {
 
 ASSERT          Assertion failed
 USERABORT       User initiated abort
 ... and so on ...
 }

The input is parsed as follows. On the first line:

• e A prefix used to generate the names of the constants for the error codes for this module. This prefix must not conflict with prefixes for other modules.
• = Separates the name prefix from the mask.
• 0x00080000 This mask is added into each named constant generated for this module. This mask must not conflict with the masks used in other modules.
• "Storage Manager" The name of the module.
• smlevel_0 The name of a C++ class. If a class name is present, certain generated data structures and methods will be members of the class, such as init_errorcodes(), which will be <class>init_errorcodes(). If no class name appears, these entities will have global namescope.
• { Begins the set of error codes and descriptions for this module.

• The next two lines define error codes:
  • ASSERT
  • USERABORT These cause the named constants eASSERT and eUSERABORT to appear in an anonymous enumeration type. The values associated with eASSERT and eUSERABORT will contain the mask:

       enum {
         eASSERT    = 0x80000,
         eUSERABORT = 0x80001,
         ...
       }
    

    The string "Assertion failed" is the descriptive string associated with eASSERT. These descriptive strings will appear in arrays generated by the Perl script.
• } Ends the set of error codes and descriptions for this module.

Blank lines may appear anywhere. Lines beginning with # are comments.

Generated Files

The names of the files generated contain the prefix given on the first line of the module's input. In the above example, that prefix is e.

The set of files generated is determined by the arguments with which the script is invoked:

errors.pl -d <file> :

• <prefix>_error_def_gen.h
  • defines C Preprocessor macros for the <prefix>_ERROR values, e.g.,

            #define E_ASSERT 0x80000
    

• <prefix>_errmsg_gen.h (same as with -e option)
  • defines an array

     static char* <prefix>_errmsg[] 
    

    containing the descriptive strings and

     const <prefix>_msg_size = <number of error codes in this module> 
    

    .
• <prefix>_einfo_gen.h (same as with -e option)
  • defines an array

     <class>::error_info[] 
    

    of { integer, descriptive-string } pairs.
  • defines the method

     void <class>::init_errorcodes() 
    

    to be called by the server at start-up to insert the module information into the global list; this is generated only if the module contains a class name.
• <prefix>_einfo_bakw_gen.h
  • defines an array

     <prefix>_error_info_backw[] 
    

    of { integer, string-name-of-macro } pairs.

errors.pl -e <file> :

• <prefix>_error_enum_gen.h
  • defines an enumeration for the <prefix>_ERROR values, e.g.,

            enum {
             eASSERT         = 0x80000,
             eUSERABORT      = 0x80001,
             ...
            }
    

• <prefix>_errmsg_gen.h (same as with -d option)
  • defines an array

     static char* <prefix>_errmsg[] 
    

    containing the descriptive strings and

     const <prefix>_msg_size = <number of error codes in this module> 
    

    .
• <prefix>_einfo_gen.h (same as with -d option)
  • defines an array

     <class>::error_info[] 
    

    of { integer, descriptive-string } pairs.
  • defines the method

     void <class>::init_errorcodes() 
    

    to be called by the server at start-up to insert the module information into the global list. This is generated only if the module contains a class name.

---