Social Networking Solutions

Btrieve Status Codes

The following information is copyrighted material from Btrieve Technologies, Inc. This information can NOT be duplicated in any form without written permission from Btrieve Technologies, Inc.

1: The operation parameter is invalid.

The specified Btrieve operation does not exist or is not valid for this version of the MicroKernel.

2: The application encountered an I/O error.

An error occurred while reading from or writing to the disk. One of the following has occurred:

The file is damaged and must be recreated.
For pre-v6.0 MicroKernels, there is a large pre-image file inside a transaction, and there is not enough space for a write to the pre-image file.
For v5.x MicroKernels, there is one pre-image file for multiple data files. For example, if you name the data files CUSTOMER.ONE and CUSTOMER.TWO, both files have pre-image files named CUSTOMER.PRE.
For files in pre-v6.0 Btrieve format that are larger than 768 MB, there is a conflict among locking mechanisms. The file has not been corrupted. Your application can retry the operation until the conflict is resolved (when the competing application releases the lock your application requires).
A pre-v6.0 Btrieve engine attempted to open a Btrieve v6.x or later file.

3: The file is not open.

The operation cannot execute because the file is not open. The application must perform a successful Open operation before the MicroKernel can process any other operations. The MicroKernel may also return this status code if the application passed an invalid position block for the file, or if the application passed a position block with a client ID other than the client ID used to open the file.

4: The application cannot find the key value.

The MicroKernel cannot find the specified key value in the index path. When you receive this status on an update or delete operation, it usually means that the file is damaged and must be recreated. Also, pre v6.x client/server database engines could return this status code if two separate files have different alternate collating sequences (ACSs), but those ACSs have the same name. Never use the same name for different ACSs, regardless of the version you are using.

5: The record has a key field containing a duplicate key value.

The MicroKernel cannot add or update a record because the record has a key field that contains a duplicate key value for an index that does not allow duplicate values.

6: The key number parameter is invalid.

The value stored in the key number parameter is not valid for the file being accessed. The key number must correspond to one of the keys defined for the file. Valid key numbers are 0 through 118.

7: The key number has changed.

The key number parameter changed before a Get Next, Get Next Extended, Get Previous, or Get Previous Extended operation. The operation requires the same key number parameter as the previous operation because the MicroKernel uses positioning information relative to the previous key number. In a related situation, the MicroKernel may return this status code when an application performs a Delete or Update operation immediately following a Get operation. If the application changes the value of the key number in the Delete or Update operation (from the value returned by the preceding Get operation), the MicroKernel deletes or updates the record as requested and will not return Status Code 07, at least not at this point. However, the MicroKernel does return Status Code 07 on the very first Get operation performed after the deletion or update, even if that Get operation uses the same key value the application passed to the Delete or Update operation. If you need to change key numbers between consecutive Get Next, Get Next Extended, Get Previous, or Get Previous Extended operations (or in Delete or Update operations as described in the preceding paragraph), use a Get Position operation followed by a Get Direct/Record operation to reestablish positioning for the new index path.

8: The current positioning is invalid.

You must establish the current position in order to update or delete a record. Perform a Get or Step operation to establish the current position. The MicroKernel may also return this status code if the application passed an invalid position block for the file.

9: The operation encountered the end-of-file

. The MicroKernel returns this status code in one of the following situations:

The operation encountered an end-of-file boundary or tried to read past a file boundary (end-of-file or start-of-file).
In a Get Next Extended, Get Previous Extended, Step Next Extended, or Step Previous Extended operation, the number of records satisfying the filtering condition is less than the number of specified records to be returned, and the reject count has not been reached.
When reading a file in ascending order according to an index path, the MicroKernel has already returned the last record in that index path. When reading a file in descending order according to an index path, the MicroKernel has already returned the first record in the index path.
When using the Get By Percentage operation, either the value supplied for the percentage is too high—it exceeds 10,000 decimal (0x2710)—or the file contains no records.

10: The key field is not modifiable.

During an Update operation, the application attempted to modify a key field that is defined as nonmodifiable.

11: The specified filename is invalid.

This status code indicates either that the specified filename does not conform to file naming conventions, or that the pathname is invalid. Make sure the filename or pathname is valid for the environment.
Status Code 11 can also have the following meanings in client-server database versions of the MicroKernel:

The application attempted to open a file that has .^^^ as its extension. This extension is reserved for the MicroKernel to use during continuous operation. (Only server engines can use continuous operations.)
The data buffer for a Begin or End continuous operation is not set up correctly.

12: The MicroKernel cannot find the specified file.

Check the key buffer parameter to make sure the pathname is terminated with a blank or a binary zero. Also, check to be sure the file exists. When accessing a file on a server, be sure that you have FILE SCAN rights to the directory in which the file resides.

13: The MKDE could not open the extension file for an extended file.

The pre-v6.0 Btrieve could not find the extension file for an extended file that the application tried to open. Extension files must be loaded on the logical disk drive specified when the extension was created. Both the primary file and its extension file must be on-line to access an extended file.

14: The MicroKernel cannot create or open the preimage file.

Only pre-v6.0 MicroKernels use pre-image files. The MicroKernel returns this status code in one of the following four situations:

The MicroKernel cannot create a new pre-image file because the disk directory is full. The MicroKernel must be able to create a pre-image file.
The MicroKernel cannot open the pre-image file to restore file integrity. If the pre-image file is erased or damaged, the MicroKernel cannot restore the file's integrity.
In a client/server environment, or in the DOS or OS/2 workstation environments, either use the RECOVER command in the File Manager to retrieve the damaged file's data records in a sequential file, or replace the file with its most recent backup.
In the Windows environment, use the Save command from the Data menu of the File Manager utility to retrieve the damaged file's data records in a sequential file. Be sure to specify no indexes when executing the Save command in this situation. You can also use SQLScope to retrieve records from the damaged file via SQL calls.
The workstation database engine cannot assign a handle to the pre-image file because the MicroKernel was not started by a user with access rights to the pre-image file.
The file structure of a pre-image file created by a v6.0 or later MicroKernel is different from the file structure of a pre-image file created by a v5.x Btrieve engine. If you have an extraneous .PRE file in v5.x format and you are using a v6.0 or later MicroKernel, the MicroKernel returns Status Code 14 when you try to open the data file to which the .PRE file belongs.

15: The application encountered an I/O error during preimaging.

Only pre-v6.0 MicroKernels use pre-image files. This status code indicates that either the disk is full or the pre-image file is damaged. If you receive this status code, proceed as follows: - If the pre-image file is damaged, the integrity of the data file cannot be ensured. - In the client/server environment or in the DOS or OS/2 workstation environments, either use the RECOVER command in the File Manager to retrieve the damaged file's data records in a sequential file, or replace the file with its most recent backup. - In the Windows environment, use the Save command from the Data menu of the File Manager utility to retrieve the damaged file's data records in a sequential file. Be sure to specify no indexes when executing the Save command in this situation. You can also use SQLScope to retrieve records from the damaged file via SQL calls. - If the disk is full, erase any unnecessary files.

16: The application encountered an expansion error.

Pre-v6.0 Btrieve returns this status code when it encounters an error while writing the directory structure to disk prior to creating the expanded file partition. Either the MicroKernel cannot close the file, or a new page was added to the file and the MicroKernel cannot close and reopen the file to update the directory structure. Check for a disk hardware failure.

17: The application encountered a close error.

Pre-v6.0 Btrieve returns this status code when it encounters an error while writing the directory structure to disk prior to closing the file. Either the MicroKernel cannot close the file, or a new page was added to the file, and the MicroKernel cannot close and reopen the file to update the directory structure. Check for a disk hardware failure. The MicroKernel may also return this status code if the application passed an invalid position block for the file.

18: The disk is full.

The MicroKernel can return this status code in the following situations: - The disk is full, and the file cannot be expanded to accommodate additional records. Erase any unnecessary files. If using a pre-v6.0 engine, you can possibly extend the file to gain additional disk space. - There is not enough space to append a new page to the data file. - The pre-image file is out of disk space. If your files are in pre-v6.0 Btrieve format and you are in a transaction, the pre-image file size increases for the duration of the transaction. If you receive this status, either reduce the number of operations in the transaction, or obtain more disk space. - For files located on a NetWare server, the NetWare owner name for the file is no longer valid, and your application tried to insert or update records in the file, thus causing the file to expand. In this case, the MicroKernel returns this status code when it needs to add a page to the file, regardless of how much disk space is available. To check for an owner name, use the NetWare utility NDIR. To add an owner name, use either FILER (a NetWare text utility) or the NetWare Administrator graphical utility. - In some environments, you can limit the amount of disk space available to each user. This status code indicates that the application attempted to expand a data file beyond the amount of disk space allocated to the file's owner.

19: The application encountered an unrecoverable error.

To ensure file integrity, recover the file as follows: - In the client/server environment, or in the DOS or OS/2 workstation environments, either use the RECOVER command in the Maintenance utility to retrieve the damaged file's data records in a sequential file, or replace the file with its most recent backup. - In the Windows environment, use the Save command from the Data menu of the Maintenance utility to retrieve the damaged file's data records in a sequential file. Be sure to specify no indexes when executing the Save command in this situation. You can also use SQLScope to retrieve records from the damaged file via SQL calls.

20: The MKDE or Btrieve Requester is inactive.

In the DOS and NetWare environments, you must load the MicroKernel and, if applicable, the Btrieve Requester before generating any requests. By default in the Windows and Windows NT environments, the Setup utility turns on the Local Engine Usage option. To access a client/server MicroKernel engine but not a workstation engine, turn the Local option off and turn the Server option on. To access both workstation and client/server MicroKernels, turn the Server option on and leave the Local option on. Also, in the Windows environment, be sure that the Btrieve for Windows DLLs and MicroKernel executable are in your PATH or in the top level of your Windows directory. In the Windows NT environment, you must start the MicroKernel before generating any requests. Make sure the Windows NT DLLs are in your path. In the OS/2 environment, be sure that the necessary DLLs are in your LIBPATH directory.

21: The key buffer parameter is too short.

The key buffer parameter is not long enough to accommodate the key field for the requested index path. Verify that the length of the key buffer equals the defined length of the key specified in the key number parameter. Only language interfaces that track the buffer length can return this status code.

22: The data buffer parameter is too short.

The data buffer parameter is not large enough to accommodate the length of the data record defined when the file was created or the entire record including its variable portion. Verify that the length of the data buffer is at least as long as the file's defined record length. - For Get or Step operations, the MicroKernel returns as much data as it can and a Status Code 22, indicating that it cannot return the entire record. - For an Insert operation, the MicroKernel does not insert the record if the data buffer is shorter than the fixed-length portion of the record. - For an Update operation, if the data buffer is too short to contain the fixed-length portion of a record, the MicroKernel does not update the record. - For the Create operation, the last key defined in the file specification has the segmented attribute set, but has no definition for additional segments. Either remove the segmented attribute for the key or add the definition(s) for the missing segment(s). - For the Create, Stat, and Create Index operations, the data buffer is not long enough to contain all the file specifications, the key specifications, and (if specified) the alternate collating sequence definition(s). - For the Get By Percentage or Find Percentage operation, the data buffer length is less than 4 bytes. - For the Version operation, the data buffer length is less than 5 bytes.

23: The position block parameter is not 128 bytes long.

Only older language interfaces that track the position block length can detect and return this status code. None of the currently- shipping language interfaces return Status Code 23.

24: The page size is invalid.

The MicroKernel returns this status code in one of the following situations: - The page size is invalid. The page size must be a multiple of 512 bytes and cannot exceed 4,096 bytes. - During a Create operation, the page size is the first file specification the MicroKernel checks. A Status Code 24 at this point may indicate an invalid data buffer parameter. In pre-v6.1 MicroKernels, the Open operation can return this status code. In this case, the MicroKernel cannot open the file because the file's page size exceeds the Largest Page Size configuration option. To successfully open the file, you must increase the value of the Largest Page Size configuration option and then reload the MicroKernel. The v6.1 or later MicroKernel does not return Status Code 24 from the Open operation.

25: The application cannot create the specified file.

The MicroKernel can return this status code if an application attempts to create a data file, but the disk directory or the disk itself is full. If the application is creating a file over an existing file, the MicroKernel returns this status code when the existing file is open or when the operating system prevents the operation for some other reason (for example, because the file is flagged transactional). Sometimes pre-v6.0 MicroKernels can return Status Code 25 if the HOLD parameter in NET.CFG or SHELL.CFG is set to ON and the application attempts to create a data file on a network drive. (The HOLD parameter is set to OFF by default.) Creation of the file on a local drive is successful regardless of the value of the HOLD parameter.

26: The number of keys specified is invalid.

The number of keys specified for the page size is invalid. The number of key segments must be within the following limits:

Page Size       Max. No. Key Segments 
512                     81,024                   231,536                   242,048                   542,560                   543,072                   543,584                   544,094                   119

27: The key position is invalid.

The specified key field position is less than 1 or exceeds the defined record length for the file. Either the key position is greater than the record length or the key position plus the key length exceeds the record length.

28: The record length is invalid.

The specified record length (plus overhead for duplicates, record usage count, variable record pointers, key pointers, and blank truncation information) must be less than or equal to the page size minus 6 bytes, and greater than or equal to 6 bytes.

29: The key length is invalid.

The specified key length must be greater than 0 but cannot exceed 255 bytes. The length of a binary key must be an even number. Each key page in the file must be large enough to hold at least eight keys. If the page size is too small to accommodate eight occurrences of the specified key length (plus overhead), either increase the file's page size or decrease the key length.

30: The file specified is not a Btrieve-compatible file.

Either the MicroKernel did not create the file, or a pre-v3.x MicroKernel created it. You may also receive this status from earlier versions of Btrieve when you open a file created by a later version, if the file has a format incompatible with the earlier version. This status code can also indicate that the first page of the file is damaged. Use a backup copy of your data file. If you are trying to recover from receiving Status Code 30 and you suspect that the header page of the source file might be damaged, try using the Maintenance utility to create the new data file with a description file.

31: The file is already extended.

Pre-v6.0 workstation and VAP-based engines return this status code if an application tries to extend a file that has already been extended; you can only extend a file once. An application cannot extend files on a NetWare v3.x or NetWare v4.x server using the MicroKernel NLM. Btrieve v6.x also does not support the extended files feature.

32: The file cannot be extended.

Pre-v6.0 workstation and VAP-based engines return this status code if an application tries to extend a file that cannot be extended. Possible causes for receiving this status code are that the directory is full, the disk is full, or the disk is write-protected.

33: The MicroKernel cannot unload.

In the DOS environment, the MicroKernel returns this status code for one of two reasons. First, you may get this status code if you attempt to unload the MicroKernel when you have loaded another terminate and stay resident (TSR) program after you loaded the MicroKernel. Unload the other TSR before unloading the MicroKernel. Second, you may get this status code if you attempt to unload the MicroKernel from a 32-bit application that uses the BSTUB interface with the DOS/4G extender.

34: The specified extension name is invalid.

Pre-v6.0 workstation and VAP-based engines return this status code if an application specified an invalid filename for the extended partition. Check the validity of the filename.

35: The application encountered a directory error.

Either a Get Directory operation specified a drive that does not exist, or a Set Directory operation specified an invalid pathname. Check the validity of both the drive and the pathname.

36: The application encountered a transaction error.

The MicroKernel tried to perform a Begin Transaction operation, although it was not configured to allow transactions. Run the Setup utility and specify a higher value for the Number of Transactions configuration option. Next, stop and then restart the MicroKernel so that your changes will take effect. On a workstation that is running both a workstation MicroKernel and a Btrieve Requester accessing a client/server MicroKernel, be sure that both the workstation database engine and the client/server MicroKernel are configured for transactions. In a client/server environment, all servers running MicroKernel Database Engines to which the workstation is attached must be configured for transactions, even if the files involved in the transaction are only located on one of the servers.

37: Another transaction is active.

The application issued a Begin Transaction (19 or 1019) or Begin Nested Client Transaction (2019 or 3019) operation while another non-nested transaction was active by the same user or task. You also receive this status code if the application issued a Begin Transaction (19 or 1019) operation while a nested transaction was active.

38: The MicroKernel encountered a transaction control file I/O error.

Pre-v7.x MicroKernels return this status code if the MicroKernel encountered an error when it tried to write to the transaction control file. Possible causes for receiving this status code are that the disk is full, the disk is write protected, the transaction control file (MKDE.TRN) that is created when you load the MicroKernel has been deleted, or the transaction control file is flagged read-only.

39: A Begin Transaction operation must precede an End/Abort Transaction operation.

The application issued an End Transaction (20) or Abort Transaction (21) operation without a corresponding Begin Transaction (19 or 1019) operation. Make sure that each End or Abort Transaction operation in your program is executed only after a successful Begin Transaction operation.

40: The file access request exceeds the maximum number of files allowed.

This status code applies only to pre-v6.0 MicroKernels. The application tried to access more than the maximum number of files allowed within a transaction. The maximum number of different files that can be accessed during a logical transaction is set when the MicroKernel is configured.

41: The MicroKernel does not allow the attempted operation.

The MicroKernel returns this status code for one of the following reasons: - The application tried to perform an operation that is not allowed at this time. The MicroKernel does not allow some operations under certain operating conditions. For example, the MicroKernel returns this status code if the application attempts to perform a Step operation on a key-only file or a Get operation on a data-only file. - If using a server engine, the key number parameter of a continuous operation MicroKernel call is not 0, 1, or 2. Also, the MicroKernel prohibits certain operations during transactions because they have too great an effect on the file or on performance. These operations include Set Owner, Clear Owner, Extend, Create Index, Drop Index, and Close (for files updated during the transaction).

42: A file previously opened in Accelerated mode was not closed.

The MicroKernel returns this status code for one of the following reasons: - Either the application tried to open a v5.x data file that was previously accessed in Accelerated mode by a v5.x Btrieve engine and never successfully closed, or the application tried to open a file for which a v6.0 or later MicroKernel encountered an unrecoverable error during a Set or Clear Owner operation. The file's integrity cannot be ensured. In a client/server environment, or in the DOS or OS/2 workstation environments, either use the RECOVER command in the Maintenance utility to retrieve the damaged file's data records in a sequential file, or replace the file with its most recent backup. In the Windows environment, use the Save command from the Data menu of the Maintenance utility to retrieve the damaged file's data records in a sequential file. Be sure to specify no indexes when executing the Save command in this situation. You can also use SQLScope to retrieve records from the damaged file via SQL calls. - Your application tried to open a file in Btrieve v5.x format using a v5.x Btrieve engine; however, that same file was previously accessed by a v6.0 or later MicroKernel, which failed to close the file successfully due to a crash. Version 5.x does not understand the format of a pre-image file created in v6.0 or later format.

43: The specified record address is invalid.

The MicroKernel returns this status code for one of the following reasons:

The record address specified for a Get Direct operation is invalid. Either the address is outside the file's boundaries, or it is not on a record boundary within or on a data page, or the record at the specified address has been deleted. For a Get Direct operation, specify the 4-byte address obtained by a Get Position operation.
If the records' file is in v5.x format, this error may indicate a file access conflict. For example, task 1 has a file locked in an exclusive transaction. Task 2 is reading records from the same file and tries to update a record that the transaction inserted. If task 2 reads the record and then task 1 aborts the transaction, task 2 receives this status code when issuing the Update operation.
For a Find Percentage operation that is seeking a percentage based on a record's physical location within the file, the specified record address is invalid.
The file may be corrupt, and you must rebuild it.

44: The specified key path is invalid.

The application tried to use the Get Direct/Record operation to establish an index path for a key whose value is null in the corresponding record. The MicroKernel cannot establish positioning based on a null key value. Some earlier versions of the MicroKernel return Status Code 82 in this situation; therefore, write your application to check for both of these status codes.

45: The specified key flags are invalid.

The key flags specification on a Create operation is inconsistent. If a key has multiple segments, the duplicate, modifiable, and null attributes should be the same for each segment in the key. Also, you cannot use the null or manual key attributes in a key-only file. The MicroKernel also returns this status code if the application attempted to specify a different alternate collating sequence for two or more segments of a segmented key.

46: Access to the requested file is denied.