APPENDIX B: STATUS CODES MESSAGES BTRIEVE STATUS CODES The Btrieve Record Manager returns a status value after each operation an application performs. A value of O indicates that the operation was successful. The possible nonzero status codes that the Record Manager returns are described below. 01 INVALID OPERATION The operation parameter specified in the Btrieve call is invalid. 02 I/O ERROR An error occurred during disk read/write. This status may indicate that the file has been damaged and must be recreated, or that the filename specified on the open call was not created by Btrieve. This status may also occur if the application writes on the position block allocated for the file. 03 FILE NOT OPEN An application must perform a successful Open operation before Btrieve can process any other operations. This status may also occur if the application writes on the position block allocated for the file or passes an invalid position block. 04 KEY VALUE NOT FOUND Btrieve did not find the requested key value in the specified access path. 05 DUPLICATE KEY VALUE An attempt was made to add a record with a key field containing a duplicate key value to an index that does not allow duplicate values. 06 INVALID KEY NUMBER 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 when the file was created, or to a supplemental index. 07 DIFFERENT KEY NUMBER The key number parameter changed before a Get Next, Get Previous, Update, or Delete operation. The operation requested requires the same key number parameter as the previous operation because the Record Manager uses positioning information relative to the previous key number. If you need to change key numbers between consecutive Get Next or get Previous operations, first use the Get Direct operation to re- establish positioning by the new access path. 08 INVALID POSITIONING An attempt was made to update or delete a record without first performing a Get or Step operation to establish current position. This status may also occur if the application writes on the position block allocated for the file. 09 END OF FILE An attempt was made to read past the end of file. When following an access path in ascending order (using Get Next operations) Btrieve returns the last record in the access path for the previous request. When following an access path in descending order (using Get Previous operations) Btrieve returns the first record in the access path for the previous request. 10 MODIFIABLE KEY VALUE ERROR An attempt was made to modify a key field which is defined as nonmodifiable. 11 INVALID FILE NAME The file name specified does not conform to file naming conventions. 12 FILE NOT FOUND The file name requested does not exist. Check the key buffer parameter to make sure the file name is terminated with a blank or a binary zero and that it is being passed correctly to Btrieve. 13 EXTENDED FILE ERROR Btrieve cannot find the extension file for a partitioned file which you have attempted to open. Extension files must be loaded on the disk drive specified when the extension was created with EXTEND. Both the primary file and its extension must be loaded to access a partitioned file. 14 PRE-IMAGE OPEN ERROR The pre-image file could not be created/opened. There are three possible causes for this error. þ The Record Manager cannot create a new pre-image file to protect future operations because your disk directory is full. Btrieve must be able to create a pre-image file in order to operate. þ The Record Manager may be trying to open the pre-image file to restore file integrity. If the pre-image file has been erased or damaged, the Record Manager cannot restore the file's integrity. In this case, either use RECOVER to retrieve the damaged file's data records in a sequential file, or replace the file with its most recent backup. þ The Record Manager cannot assign a handle to the pre-image file because the Record Manager was not started by a user with access rights to the pre-image file. 15 PRE-IMAGE I/O ERROR This status indicates an I/O error during the pre-imaging function. Either the disk is full or the pre-image file has been damaged. þ If the disk is full, erase any unnecessary files or use EXTEND to gain additional disk space. þ If the pre-image file has been damaged, the integrity of the Btrieve file cannot be ensured. Either use RECOVER to retrieve the damaged file's data records in a sequential file, or replace the Btrieve file with its most recent backup. 16 EXPANSION ERROR The directory structure could not be flushed for the expanded file partition. Either the Record Manager cannot close the file or a new page was added to the file and the Record Manager cannot close and reopen the file to update the directory structure. Check for a damaged disk. This status may also occur if the application writes on the position block allocated for the file. 17 CLOSE ERROR The directory structure could not be flushed for the Btrieve file. Either the Record Manager cannot close the file or a new page was added to the file and the Record Manager cannot close and reopen the file to update the directory structure. Check for a damaged disk. This status may also occur if the application writes on the position block allocated for the file. 18 DISK FULL The disk is full and will not allow the file to be expanded to accommodate the insertion. Either erase any unnecessary files or use EXTEND to gain additional disk space. 19 UNRECOVERABLE ERROR An unrecoverable error has occurred. File integrity cannot be guaranteed. Either use RECOVER to retrieve the damaged file's data records in a sequential file, or replace the Btrieve file with its most recent backup. 20 RECORD MANAGER INACTIVE A request has been made before BREQUEST or the Record Manager has been started. 21 KEY BUFFER TOO SHORT The key buffer parameter is not long enough to accommodate the key field for the access path requested. Verify that the length of the key buffer equals the defined length of the key specified by the key number parameter. 22 DATA BUFFER LENGTH The data buffer parameter is not long enough to accommodate the length of the data record defined when the file was created. Verify that the length of the data buffer is as least as long as the file's defined record length. þ For Get or Step operations, if the data buffer is too short to contain the fixed length portion of the record, Btrieve will not return any data to the data buffer. If the record is a variable length record, and the data buffer is too short to contain the entire variable length portion of the record, Btrieve will return as much data as it can and a status 22, indicating that it could not return the entire record. þ For the Insert operation, Btrieve will not insert the record if the data buffer is shorter than the fixed length portion of the record. þ For the Update operation, if the data buffer is too short to contain the fixed length portion of any record, Btrieve will not update the record. þ For the Create, Stat, and Create Supplemental Index operations, a status 22 indicates that the data buffer is not long enough to contain all the file and key specifications, and the alternate collating sequence definition, if needed. 23 POSITION BLOCK LENGTH The position block parameter is not 128 bytes long. 24 PAGE SIZE ERROR The page size must be a multiple of 512 bytes but must be no larger than 4O96 bytes. During a CREATE operation, page size is the first file specification Btrieve checks, and a status of 24 may indicate an invalid data buffer. 25 CREATE I/O ERROR The filename specified could not be created. Possible causes are a full disk directory, a full disk, or a write-protected disk. If you are creating a file over an existing file, Btrieve can return a status code 25 because the existing file is open or is flagged transactional. 26 NUMBER OF KEYS For standard Btrieve files with a page size of 512 bytes, the number of key segments for all key fields specified must be between 1 and 8. For larger page sizes, the number of key segments for all key fields must be between 1 and 24. You must define at least one key without the null attribute. 27 INVALID KEY POSITION The key field position specified must not exceed 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. For key-only files, the key must begin in the first byte of the record (position 1). 28 INVALID RECORD LENGTH The record length specified (plus overhead for duplicates) is greater than the page size minus 6, or is less than 4 bytes long. 29 INVALID KEY LENGTH The key length specified must be greater than O and cannot exceed 255. The length of a binary key must be even. Btrieve requires that each key page in the file be large enough to hold at least eight keys. If the file's 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 NOT A BTRlEVE FILE The file name specified is not a valid Btrieve data file. Either the file was not created by Btrieve or it was created by an earlier version of Btrieve. Use the program CONVERT4.EXE on the Btrieve Diskette to convert extended files created by Btrieve v3.x to the current format. Another possibility is that the first page of the file, which contains the File Control Record, is damaged. 31 FILE ALREADY EXTENDED The file name specified is already extended. A file can be extended only once. 32 EXTEND I/0 ERROR The file cannot be extended. Possible causes are that the disk directory is full, the disk is full, or the disk is write-protected. 34 INVALID EXTENSION NAME The filename specified for the extended partition is not valid. 35 DIRECTORY ERROR An error occurred while switching between the current directory and the directory which contains the Btrieve file. Either the current directory or the Btrieve file directory is invalid. 36 TRANSACTION ERROR A Begin Transaction operation cannot be performed because no transactions were specified when BSERVER.VAP was initialized. 37 TRANSACTION IS ACTIVE A Begin Transaction was issued while another transaction was active at that station. Transactions cannot be nested. 38 TRANSACTION CONTROL FILE I/O ERROR An error occurred when the Record Manager tried to write to the transaction control file. Possible causes are that the disk is full, the disk is write-protected, or the transaction control file (which is created when the Record Manager is loaded) has been deleted. 39 END/ABORT TRANSACTION ERROR An End or Abort Transaction operation was issued without a corresponding Begin Transaction operation. 40 TRANSACTION MAX FILES An attempt was made to update more than the maximum number of files allowed within a transaction. The maximum number of different files that may be updated during a logical transaction is 12. 41 OPERATION NOT ALLOWED Some operations are not allowed under certain operating conditions. For example, Btrieve will return this status if you attempt to perform a Step, Update, or Delete operation on a key-only file, or a Get operation on a data-only file. Also, certain operations are prohibited during transactions because they have too great an effect on the pre-image file or on Btrieve's performance. These operations include Close, Set or Clear Owner, Extend, Create Supplemental Index, and Drop Supplemental Index. In addition, during a transaction you can only open files in Read-only mode. 42 INCOMPLETE ACCELERATED ACCESS An attempt was made to open a file that was previously accessed in accelerated mode and never successfully closed. The file's integrity cannot be ensured. Either use RECOVER to build a new file or write your own recovery program that opens the file in recover mode and uses Step Direct to retrieve the data records. 43 INVALID RECORD ADDRESS The record address specified on a Get Direct is invalid. Either the address is outside of the file's bounds, it is not on a record boundary within a data page, or it is not on a data page. The 4- byte address you specify on Get Direct should be one that was obtained by a Get Position operation. 44 NULL KEY PATH An attempt has been made to use Get Direct to establish an access path for a key whose value is null in the corresponding record. Btrieve cannot establish positioning based on a null key value. 45 INCONSISTENT KEY FLAGS 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. 46 ACCESS TO FILE DENIED Your application opened a file in read-only mode and attempted to perform an Update, Delete, or Insert on that file. Inconsistent files that are opened in recover mode can be read but not updated. You should build a new file using either the RECOVER utility or the Step Direct operation. Another possible cause is that the owner name required for updates was not specified correctly when your application opened the file. 47 MAXIMUM OPEN FILES When a file is opened in accelerated mode, the Record Manager reserves one of its cache buffers for the file. The number of files opened in accelerated mode cannot exceed the number of buffers available in Btrieve's cache. Btrieve always reserves five empty buffers for index manipulation. Reconfigure the Record Manager with a smaller page size parameter to allocate more buffers. 48 INVALID ALTERNATE SEQUENCE DEFINITION Btrieve returns this status if the first byte of an alternate collating sequence definition, the identification byte, does not contain the hexadecimal value AC. 49 KEY TYPE ERROR You attempted to create a file or a supplemental index with an invalid extended key type, or you attempted to assign an alternate collating sequence to a binary key or key segment. You can only assign an alternate collating sequence to a string, lstring, or zstring type key. Btrieve will also return this status if you defined a supplemental index requiring an alternate collating sequence, and no alternate collating sequence definition exists either in the file or in the key definition passed in the data buffer. 50 OWNER ALREADY SET An attempt has been made to perform a set owner operation on a file that already has an owner. Use the clear owner operation to remove the previous owner before setting a new one. 51 INVALID OWNER There are two possible causes for this status code. þ If your application receives this status code affer a Set Owner operation, the owner names specified in the key buffer and data buffer do not match. þ If your application receives this status code after an Open operation, the file you are opening has had an owner name assigned to it. Your application must specify the correct owner name in the data buffer. 52 ERROR WRITING CACHE While trying to make a cache buffer available, Btrieve attempted to write data to a disk from a file that was previously opened in accelerated mode. The operating system returned an I/O error during the write. 53 INVALID INTERFACE An application attempted to access a file containing variable length records with a language interface from Btrieve v3.15 or earlier. To access files with variable length records, you must use a v4.xx interface. 54 VARIABLE PAGE ERROR During a Step Direct operation Btrieve could not read all or part of the variable length portion of a record. In this case, Btrieve returns as much data as possible to your application. This error usually indicates file damage to one or more pages in the file. 55 AUTOINCREMENT ERROR The application attempted to specify either the segmented or duplicates attribute for an autoincrement type key. An autoincrement key cannot be part of another key, and cannot allow duplicates. 56 INCOMPLETE INDEX A supplemental index is damaged. This can occur if a Create Supplemental Index operation or a Drop Supplemental Index operation is interrupted and does not run to completion. Perform a Drop Supplemental Index operation to completely remove the index from the file. 58 COMPRESSION BUFFER TOO SHORT The application attempted to read or write a record that is longer than the value you specified for the size of the compression buffer. Reconfigure BSERVER, specifying a higher value for the "Maximum Compressed Record Size" option, and restart the network. 59 FILE ALREADY EXISTS Btrieve will return this status for a Create operation if you specified -1 in the key number parameter and the name of an existing file in the key buffer parameter. 80 CONFLICT The Update or Delete operation cannot be performed because the record has been changed by another station since this station read it. Reread the record to perform the operation. 81 LOCK ERROR This error can result from any one of three conditions: þ The Btrieve lock table is full. Speciiy a larger value for the locks parameter of BSERVER. þ The lock function call to the operating system failed. þ You attempted to unlock one record that was locked with a multiple record lock, and the record position stored in the data buffer did not correspond with any record that was locked in that file. 82 LOST POSITION When performing a Get Next or Get Previous on a key with duplicates, an attempt has been made to retrieve a record that has been deleted or whose key value has been modified by another station. Re-establish positioning using a Get Equal or a Get Direct operation. 83 READ OUTSIDE TRANSACTION An attempt has been made to delete or update a record within a transaction but the record was not read within the transaction. If you are going to update or delete a record within a transaction, you must read the record within the transaction to ensure you have first obtained exclusive access to the data. 84 RECORD IN USE The application attempted to lock a record that is currently locked by another handle, or the application attempted to access a file within a tiansaction while another station held active record locks in that file. 85 FILE IN USE The application attempted to open a file, lock a record, or access a record while another handle holds the transaction lock on the file or has the file open in accelerated mode. 86 FILE TABLE FULL BSERVER's file table is full. Specify a larger number for the files parameter for BSERVER. 87 HANDLE TABLE FULL BSERVER's handle table is full. Specify a larger number for the handles parameter for BSERVER. Another possibility is that NetWare cannot assign a handle to the file. 88 INCOMPATIBLE MODE ERROR The application attempted to open a file in an incompatible mode. If the first handle to access a file opens it in accelerated mode, all others must open it in accelerated mode. The opposite is true for opens made in non-accelerated mode. 90 REDIRECTED DEVICE TABLE FULL Either the redirection table or the server routing table is full. This error can occur if you attach to additional servers or map to more drives after you have loaded BREQUEST. Reload BREQUEST, specifying a larger number for the JR or IS option. This error can also occur if you are attached to 8 servers, and then unattach a particular server and attach to a different server.Once a workstation has attached to a server, BREQUEST will not remove its name from the server table. 91 SERVER ERROR BREQUEST cannot establish a session with the server. Either BSERVER has not been started for the device controlling the requested file, or the server is not active. Verify that BSERVER is active on the server to which the device has been redirected, and that the server is active. 92 TRANSACTION TABLE FULL The number of active transactions you specified when you loaded BSERVER has been exceeded. Specify a larger number for the transactions parameter for BSERVER. 93 INCOMPATIBLE LOCK TYPE The application attempted to mix single record locks (+1OO/+2OO) and multiple record locks (+3OO/+4OO) in the same file at the same time. All locks of one type must be released before a lock of the other type can be executed. 94 PERMISSION ERROR A user attempted to open or create a file in a directory where he or she does not have those rights. Btrieve does not override the network privileges assigned to users. 95 SESSION NO LONGER VALID A previously established session is no longer active due to an error either at the workstation or the file server, or on the network. Verify that the file server is still attached and then reload BREQUEST at the workstation. 96 COMMUNICATIONS ENVIRONMENT ERROR The SPX connection table is full. Reload SPX, specifying a higher value for the connection table. Refer to the NetWare Supervisor Reference manual for more inforination. 97 DATA MESSAGE TOO SMALL The application attempted to read or write a record which is longer than the value you specified with the record length parameter of BSERVER or the data message option of BREQUEST. Determine the correct maximum record length required by your application and reload the appropriate program, specifying a larger value. þ For an Update, Insert, or Create operation, the application will receive this error status if the data buffer length it specifies for the record exceeds the length specified for either the ID option of BREQUEST or record length parameter of BSERVER. þ For a Get, Step, or Stat operation, the application can receive this error status if the value specified for the data message parameter is shorter than the length of the data Btrieve returns, regardless of the data buffer length specified in the program. 98 INTERNAL TRANSACTION ERROR An error has occurred during an operation within a transaction. All Insert, Update, and Delete operations since the last Begin Transaction operation have been rolled back. You should issue an Abort Transaction operation (21) to complete the rollback and exit the transaction. BREQUEST STATUS CODES (05/2) BREQUEST.DLL can return the following run-time status codes at an OS12 workstation. 2001 INSUFFICIENT MEMORY BREQUEST cannot allocate enough memory for the parameters specified with the REQPARMS environment variable. Either reduce the size of the ID: option, or reduce the size of other memory resident routines loaded prior to BREQUEST. 2002 POINTER INVALID OR OUT OF RANGE One of the parameters specified with the REQPARMS environment variable is either invalid (such as 1P: instead of ID:) or the value specified for a parameter is out of range. Check the SET REQPARMS statement to make sure that it is correct. 2003 NO LOCAL ACCESS ALLOWED The application attempted to access a file stored on a local drive. The version of BTRCALLS.DLL installed at the workstation does not allow access to local files. BUTIL COM 5 The following sections describe how to use each of the following BUTIL commands: Command Function CLONE Creates an empty Btrieve file with the same file specifications as an existing file COPY Copies the contents of one Btrieve file to another Btrieve file CREATE Creates a Btrieve file DROP Drops a supplemental index EXTEND Creates a partitioned file INDEX Creates an external index file LOAD Loads the contents of a standard sequential file into a Btrieve file RECOVER Recovers data from a damaged Btrieve file RESET Closes data files and releases resources SAVE Saves the contents of a Btrieve file into a standard sequential file SINDEX Creates a supplemental index STAT Reports statistics about file attributes and current sizes STOP Terminates BREQUEST and the local Record Manager (if loaded) and removes them from memory VER Retrieves the Btrieve version and revision numbers Utilities CLONE Command Format BUTlL -CLONE < Existing File>< New File >[ -0 < Owner>] Description The CLONE command creates a new, empty Btrieve file with the same file specifications, including any supplemental indexes, as an existing file. You can use CLONE when you want to replicate an existing file, but you don't want to destroy the information contained in the existing file, as would happen if you used CREATE. In addition, CLONE does not require a description file in order to create a new file. How To Use Clone To run COPY, enter the command in the format shown above. For , substitute the name of the Btrieve file that you want to replicate. You can specify a full path name if necessary. For , substitute the name you want to use for the new, empty Btrieve file. You can specify a full path name if necessary. For , substitute the owner name of the existing file, if one is required. The new file will retain the existing file's owner name. Example The following command clones the NEWINV.DAT file from the INVOICE.DAT file. The owner name for the INVOICE.DAT file is "Sandy." BUTIL -CLONE INVOICE.DAT NEVVINV.DAT -O Sandy COPY Command Format BUTlL -cOpY Input File>< Output File>[ -0 < Owner! -0 Owner2>]] Description The COPY command copies the contents of one Btrieve file to another. A common use of COPY is to change the defined key characteristics (such as key position, key length, or duplicate key values) for a Btrieve file. COPY retrieves each record in the input file and inserts it into the output file using Btrieve Get and Insert operations. COPY performs in a single step the same function as SAVE followed by LOAD. How To Use Copy To run COPY, enter the command in the format shown above. Replace with the name of the Btrieve file from which you are transferring the records. You can specify a full path name if necessary. Replace with the name of the Btrieve file into which you want to insert the records. The file may or may not be empty. You can specify a full path name if necessary. Replace and with the owner names for the Btrieve files, if required. If the requires an owner name, you may specify the owner for or use the asterisk option described on page 4-2. If the requires an owner name, use both the and options. If the input file does not require an owner name, you can leave blank. Use to specify the owner name for the . After the records have been copied from the input file to the output file, COPY will display on the screen the total number of records copied.