Informix Return Codes for OnBar

Problem
What are the return codes when using Informix/OnBar?


Cause


Solution
When performing a TDP Informix backup with OnBar an Informix/OnBar error may be encountered. The following listing identifies some of these Informix/OnBar return codes.

#define BSA_RC_ABORT_ACTIVE_NOT_FOUND 0x02 (02)
#define BSA_RC_ABORT_SYSTEM_ERROR 0x03 (03)
#define BSA_RC_AUTHENTICATION_FAILURE 0x04 (04)
#define BSA_RC_BAD_CALL_SEQUENCE 0x05 (05)
#define BSA_RC_BAD_HANDLE 0x06 (06)
#define BSA_RC_BUFFER_TOO_SMALL 0x07 (07)
#define BSA_RC_DESC_TOO_LONG 0x08 (08)
#define BSA_RC_OBJECTSPACE_TOO_LONG 0x09 (09)
#define BSA_RC_INVALID_TOKEN 0x0a (10)
#define BSA_RC_INVALID_VOTE 0x0b (11)
#define BSA_RC_INVALID_KEYWORD 0x0c (12)
#define BSA_RC_MATCH_EXISTS 0x0d (13)
#define BSA_RC_MORE_DATA 0x0e (14)
#define BSA_RC_MORE_RULES 0x0f (15)
#define BSA_RC_NEWTOKEN_REQD 0x10 (16)
#define BSA_RC_NO_MATCH 0x11 (17)
#define BSA_RC_NO_MORE_DATA 0x12 (18)
#define BSA_RC_NO_RESOURCES 0x13 (19)
#define BSA_RC_NULL_DATABLKPTR 0x14 (20)
#define BSA_RC_NULL_OBJNAME 0x15 (21)
#define BSA_RC_NULL_POINTER 0x16 (22)
#define BSA_RC_NULL_RULEID 0x17 (23)
#define BSA_RC_OBJECT_NAME_TOO_LONG 0x18 (24)
#define BSA_RC_OBJECT_NOT_EMPTY 0x19 (25)
#define BSA_RC_OBJECT_NOT_FOUND 0x1a (26)
#define BSA_RC_OBJINFO_TOO_LONG 0x1b (27)
#define BSA_RC_OBJNAME_TOO_LONG 0x1c (28)
#define BSA_RC_OPERATION_NOT_AUTHORIZED 0x1d (29)
#define BSA_RC_OLDTOKEN_REQD 0x1e (30)
#define BSA_RC_TOKEN_EXPIRED 0x1f (31)
#define BSA_RC_TXN_ABORTED 0x20 (32)
#define BSA_RC_UNMATCHED_QUOTE 0x21 (33)
#define BSA_RC_USER_OWNS_OBJECTS 0x22 (34)

However, since X/Open does not define what any of these return codes
really means, the X/Open Backup Services API will not dictate which
of these will be returned by any particular function in the API. The
individual storage manager's documentation should provide details
on the meaning of the return codes above. The following return codes are
generated by the ON-Bar utilities themselves, and are not generated directly
by the storage manager. For this reason, more explanation for each is
possible.

#define BAR_NOTFOUND 100 (200)
This means that ON-Bar was looking for a specific record in
the sysutils database or was trying to retrieve a specific
object from the storage manager and could not find it.

#define BAR_BUG 0x9f (159)
A specific check for an unacceptable error condition during
the execution of ON-Bar failed. This should be reported to
Technical Support along with the complete contents of the
ON-Bar activity log.

#define BAR_LISTERR 0x9e (158)
An internal error was detected in the handling of lists of
objects (such as dbspaces or logical logs). This error should
be reported to Technical support along with the complete
contents of the ON-Bar activity log.

#define BAR_NO_SHMBASE 0x9d (157)
ON-Bar could not set the INFORMIXSHMBASE environment variable.

#define BAR_NO_PDQPRIORITY 0x9c (156)
This is an XPS-specific error.

#define BAR_NO_SERVER 0x9b (155)
ON-Bar requires that the INFORMIXSERVER environment variable
be set when performing a cold restore. If it cannot find a
value, then ON-Bar cannot distinguish between the need for a
cold restore and a simple environment problem, and so it will
not proceed.

#define BAR_NO_PERMISSION 0x9a (154)
This release of ON-Bar requires that the onbar utility be
executed by either the root or informix user.

#define BAR_PGID_FAILED 0x99 (153)
To provide reasonable control of processes and to allow a
collection of onbar processes to be killed together (see
SIGQUIT handling in the user documentation), if BAR_MAX_BACKUP
is set to any value other than 1 and ON-Bar encounters an
error setting the UNIX process group ID, this value is
returned.

#define BAR_NO_LOG_BACKUP 0x98 (152)
If an onbar process tries to perform a logical log backup and
finds that there is already a log backup in progress, it
returns this error.

#define BAR_BAD_SERVER_STATE 0x97 (151)
Certain backup/restore operations are only permitted if the
OnLine server is in a particular state. For example, a
dbspace backup cannot be performed if the OnLine server is
offline. This error is returned if a backup/restore request
is made when the server is in a state incompatible with the
request.

#define BAR_CONFIG_ERROR 0x96 (150)
ON-Bar obtains configuration information from
$INFORMIXDIR/etc/$ONCONFIG. It returns this error if there
was a problem reading this file or if illegal values were
found there.

#define BAR_BAD_USAGE 0x95 (149)
This error is returned if an illegal set of command line
arguments has been passed. Look in the ON-Bar activity log
for more details.

#define BAR_SQL_ERROR 0x94 (148)
This is returned for general SQL errors from which ON-Bar
cannot recover. The specific SQL and ISAM error codes and
messages are put in the ON-Bar activity log.

#define BAR_NO_LIST 0x93 (147)
This is the error code returned when ON-Bar cannot figure out
what work to perform. For example, if the user specifies a
point-in-time restore, but gives a time from before the first
dbspace backup, ON-Bar cannot build a list of dbspace backups
from which to perform the restore.

#define BAR_SRV_CONNECT 0x92 (146)
This indicates that ON-Bar tried to exchange dbspace or
logical log data with the OnLine database engine, but the
engine did not respond within a timeout period. This is not
the same as having an SQL query that times out because of a
SET LOCK MODE statement.

#define BAR_NO_MEMORY 0x91 (145)
This indicates that ON-Bar encountered a memory allocation
failure, usually because too few OS resources are available.

#define BAR_BLOB_DOWN 0x90 (144)
If performing a logical log backup in accordance with an onbar -l
command line, ON-Bar returns this error if a blobspace is
down. Log backup can be reenabled by restoring the blobspace.

#define BAR_NO_PID 0x8f (143)
If BAR_MAX_BACKUP is not 0, then ON-Bar spawns child processes
to parallelize backups and restores. This error is returned
if a backup or restore task could not be completed because the
operating system would not allow these children to be started.

#define BAR_FILE_OPEN 0x8e (142)
ON-Bar works with several files that live in the file system.
If it cannot open one of these files for some reason (e.g.
UNIX filesystem permissions) then it returns this error.

#define BAR_FUNCINTRPT 0x8d (141)
When an ON-Bar process receives a signal while executing it
returns this value to its caller.

#define BAR_FAKE_FAILED 0x8c (140)
For some reason a fake backup (onbar -f) could not complete
properly.

#define BAR_BAD_VERSION 0x8b (139)
There is no record in the bar_version table (sysutils
database) that matches the version number returned by the
storage manager during ON-Bar initialization. This is usually
a problem with the storage manager installation.

#define BAR_SM_ERROR 0x8a (138)
This is a generic storage manager error return code, and is
only used internally by ON-Bar. Usually one of the
XBSA-defined error codes will be returned to ON-Bar's caller.

#define BAR_MAX_DBS 0x89 (137)
This should never be encountered. This error indicates that
someone has requested more dbspaces be backed up or restored
than OnLine and ON-Bar will permit to exist.

#define BAR_NO_WARM 0x88 (136)
The caller of onbar has requested that one of the critical
dbspaces be restored. This is an illegal operation.

#define BAR_NO_CHILD 0x87 (135)
This should never be returned to a caller. It indicates that
onbar started a child process as part of the parallelization
of a backup or restore, and then could not find that child
process running.

#define BAR_EARLY_LOG 0x86 (134)
This is returned if a point-in-log restore was requested with
a logical log file that cannot be used because it
preceeds the dbspaces that have already been physically
restored.

#define BAR_NO_BSALIB 0x85 (133)
This indicates that the storage manager has been incompletely
or improperly installed or that the BAR_BSALIB_PATH parameter
in the $INFORMIXDIR/etc/$ONCONFIG file has not been set
properly. Note that not all platforms support the
BAR_BSALIB_PATH parameter.

#define BAR_SHLIB_ERR 0x84 (132)
This indicates that the storage manager has not implemented
one of the functions that ON-Bar depends on. Contact your
storage management vendor and Informix Technical Support.

#define BAR_AAPI_ERROR 0x83 (131)
This error is returned if there was some problem exchanging
backup or restore data for dbspaces or logical logs between
ON-Bar and the OnLine database server. Look in the ON-Bar
activity log for more information. Often these errors can be
worked around simply by retrying the same ON-Bar command line.
If this does not work, contact Technical Support.

#define BAR_SERVER_CRASH 0x82 (130)
This error is returned if ON-Bar detects that the OnLine
database server has quit unexpectedly during a backup or
restore operation.

** Errors for specific storage management systems:

Occasionally a storage management vendor's implementation of the XBSA
is more strict than that standard requires. The following error is
the only one Informix has encountered that cannot be accomodated with
strict adherance to the standard.

#define ADSM_RC_PSWD_GEN 0x68 (104)
IBM ADSM is in password-generating mode.