Programming Idioms
[SHORE Storage Manager Application Programming Interface (SSM API)]

Collaboration diagram for Programming Idioms:

The storage manager is written with programming idioms to make sure all return codes are checked, and as a user of the storage manager, you strongly encouraged to use these idioms.

It is especially important that you understand the storage manager's return code type, w_rc_t. Most of the storage manager methods return this type. The return code type is a dynamically-allocated class instance (except when RCOK, the default, non-error code, is returned: this is a static constant). Because it is heap-allocated, when the compiler generates code for its destruction, certain programming errors are nastier than in the case of returning an atomic type (e.g., int). For example, if you write a function with a w_rc_t return type and neglect to give it a return value, your program will probably fail catastrophically. (You can avoid this problem by compiling with compiler warnings enabled.)

The return code from a storage manager method should always be checked:

 w_rc_t func(...)
 {
     ...
     w_rc_t rc = ss_m::create_file(...);
     if(rc.is_error()) {
        ...
     }
     return RCOK;
 }

The act of calling

 rc.is_error() 

flags the return code as having been checked. The destructor for w_rc_t can be made to issue an error if the return code was never checked for destruction. The message takes the form:

 Error not checked: rc=1. error in j_create_rec.cpp:176 Timed out waiting for resource [0x40000]

(When a return code is sent to an output stream, it prints a stack trace. The above message contains a stack trace with one level.)

The error-not-checked checking happens if the storage manager is configured and built with

 --enable-checkrc 

. By default this configuration option is off so that it is off for a "production", that is, optimized build. When you are debugging your code, it is a good idea to configure the storage manager with it enabled.

Several macros defined in w_rc.h support writing and using methods and functions that return a w_rc_t.

 w_rc_t
 func(...)
 {
     W_DO(ss_m::create_file(...));
     return RCOK;
 }

The W_DO macro returns whatever the called function returns if that return code was an error code, otherwise, it falls through to the code below the macro call. This is the most-often used idiom.

The RC_* macros let you construct a return code for a return value from a function. The normal, non-error return code is RCOK.

Return codes are described in some detail ERRNUM. There you may also see how to create your own return codes for server modules.

See the examples as well as Significant C Preprocessor Macros in w_rc.h.

---