m4_comment([$Id: errorret.so,v 10.49 2006/08/25 18:22:01 bostic Exp $])define(M4PAGELOCAL,	[DB_KEYEMPTY, DB_KEYEXIST, DB_LOCK_DEADLOCK, DB_LOCK_NOTGRANTED,	DB_NOTFOUND, DB_RUNRECOVERY])m4_ref_title(Programmer Notes,    Error returns to applications,    @error returns, program/appsignals, program/environ)m4_p([dnlExcept for the historic m4_ref(dbm), m4_ref(ndbm), and m4_ref(hsearch)interfaces, m4_db does not use the global variable m4_envvar(errno) toreturn error values.  The return values for all m4_db functions aregrouped into the following three categories:])m4_tagbeginm4_tag(0, [A return value of 0 indicates that the operation was successful.])m4_tag([__GT__ 0], [dnlA return value that is greater than 0 indicates that there was a systemerror.  The m4_bold(errno) value returned by the system is returned bythe function; for example, when a m4_db function is unable to allocatememory, the return value from the function will be ENOMEM.])m4_tag([__LT__ 0], [dnlA return value that is less than 0 indicates a condition that was nota system failure, but was not an unqualified success, either.  Forexample, a routine to retrieve a key/data pair from the database mayreturn m4_ref(DB_NOTFOUND) when the key/data pair does not appear inthe database; as opposed to the value of 0, which would be returned ifthe key/data pair were found in the database.m4_p([dnlm4_idefz(error name space)All values returned by m4_db functions are less than 0 in order to avoidconflict with possible values of m4_bold(errno).  Specifically, m4_dbreserves all values from -30,800 to -30,999 to itself as possible errorvalues.  There are a few m4_db interfaces where it is possible for anapplication function to be called by a m4_db function and subsequentlyfail with an application-specific return.  Such failure returns will bepassed back to the function that originally called a m4_db interface.To avoid ambiguity about the cause of the error, error values separatefrom the m4_db error name space should be used.])])m4_tagendm4_p([dnlAlthough possible error returns are specified by each individual function'smanual page, there are a few error returns that deserve general mention:])m4_section(m4_idef(DB_NOTFOUND) and m4_idef(DB_KEYEMPTY))m4_p([dnlThere are two special return values that are similar in meaning and thatare returned in similar situations, and therefore might be confused:m4_ref(DB_NOTFOUND) and m4_ref(DB_KEYEMPTY).])m4_p([dnlThe m4_ref(DB_NOTFOUND) error return indicates that the requested key/datapair did not exist in the database or that start-of- or end-of-file hasbeen reached by a cursor.])m4_p([dnlThe m4_ref(DB_KEYEMPTY) error return indicates that the requestedkey/data pair logically exists but was never explicitly created by theapplication (the Recno and Queue access methods will automaticallycreate key/data pairs under some circumstances; see m4_ref(dbh_open)for more information), or that the requested key/data pair was deletedand never re-created.  In addition, the Queue access method will returnm4_ref(DB_KEYEMPTY) for records that were created as part of atransaction that was later aborted and never re-created.])m4_section(m4_idef(DB_KEYEXIST))m4_p([dnlThe m4_ref(DB_KEYEXIST) error return indicates the m4_ref(DB_NOOVERWRITE)option was specified when inserting a key/data pair into the database andthe key already exists in the database, or the m4_ref(DB_NODUPDATA)option was specified and the key/data pair already exists in the data.])m4_idefz(DB_LOCK_DEADLOCK)m4_section(m4_idef(DB_LOCK_DEADLOCK))m4_p([dnlWhen multiple threads of control are modifying the database, there isnormally the potential for deadlock. In m4_db, deadlock is signified byan error return from the m4_db function of the valuem4_ref(DB_LOCK_DEADLOCK).  Whenever a m4_db function returnsm4_ref(DB_LOCK_DEADLOCK), the enclosing transaction should be aborted.])m4_p([dnlAny m4_db function that attempts to acquire locks can potentially returnm4_ref(DB_LOCK_DEADLOCK).  Practically speaking, the safest way to dealwith applications that can deadlock is to anticipate am4_ref(DB_LOCK_DEADLOCK) return from any m4_ref(Db) or m4_ref(Dbc)handle method call, or any m4_ref(DbEnv) handle method call thatreferences a database, including the database's backing physical file.])m4_section(m4_idef(DB_LOCK_NOTGRANTED))m4_p([dnlIf a lock is requested from the m4_ref(lock_get) or m4_refT(lock_vec)swith the m4_ref(DB_LOCK_NOWAIT) flag specified, the method will returnm4_ref(DB_LOCK_NOTGRANTED) if the lock is not immediately available.])m4_p([dnlIf the m4_ref(DB_TIME_NOTGRANTED) flag is specified to them4_refT(dbenv_set_flags), database calls timing out based on lock ortransaction timeout values will return m4_ref(DB_LOCK_NOTGRANTED)instead of m4_ref(DB_LOCK_DEADLOCK).])m4_section(m4_idef(DB_RUNRECOVERY))m4_p([dnlThere exists a class of errors that m4_db considers fatal to an entirem4_db environment.  An example of this type of error is a corrupteddatabase page.  The only way to recover from these failures is to haveall threads of control exit the m4_db environment, run recovery of theenvironment, and re-enter m4_db. (It is not strictly necessary that theprocesses exit, although that is the only way to recover systemresources, such as file descriptors and memory, allocated by m4_db.)])m4_p([dnlWhen this type of error is encountered, the error valuem4_ref(DB_RUNRECOVERY) is returned. This error can be returned by anym4_db interface.  Once m4_ref(DB_RUNRECOVERY) is returned by anyinterface, it will be returned from all subsequent m4_db calls made byany threads of control participating in the environment.])m4_p([dnlApplications can handle such fatal errors in one of two ways: first, bychecking for m4_ref(DB_RUNRECOVERY) as part of their normal m4_db errorreturn checking, similarly to m4_ref(DB_LOCK_DEADLOCK) or any othererror.  Alternatively, applications can specify a fatal-error callbackfunction using the m4_refT(dbenv_set_event_notify).  Applications withno cleanup processing of their own should simply exit from the callbackfunction.])m4_page_footer