ISAM logging, error codes, and troubleshooting

This section lists error codes that are specific to FairCom RTG/ISAM. You may encounter these errors in addition to FairCom DB errors and standard Btrieve errors.

Configurable Log Output

The output of the FairCom RTG log includes a file name with the log messages. Warning and error log messages are formatted with the file name appended at the end of the message. The file name is preceded by the instance name, when specified in ctree.conf with the <instance name> attribute, or by the instance number and file number to uniquely identify the file as follows:

instance_number#file_number:file_name.

The file name is logged for START, READ, NEXT, PREVIOUS, WRITE, REWRITE, DELETE, and UNLOCK operations.

In addition, every entry in the log is pre-pended with a thread ID to uniquely identify the process/thread that made the log entry. The thread ID is made of 8 hexadecimal digits followed by a “>” sign.

Example:

00002D40> 20140915T141358 core:3494:cts_rewdel ERROR 5:42:0 record is locked 0#0:arc1.dat

Substitution Specifiers

The following substitution specifiers can be used in the name attribute of the <instance> and its variant elements:

• %t to print the thread ID in unsigned decimal format
• %p to print the process ID in unsigned decimal format
• %i to print the instance number in unsigned decimal format

These specifiers can optionally contain embedded format specifiers with the following prototype:

%[0][width][x|X]specifier

• [0] left-pads the number with zeroes (0) instead of spaces when width is specified
• [width] minimum number of characters to be printed. If the value to be printed is shorter than this number, the result is padded with blank spaces. The value is not truncated even if the result is larger.
• [x] (lower case) number is as unsigned hexadecimal integer
• [X] (upper case) number is as unsigned hexadecimal integer

Driver Error Codes

The table below lists the logical error codes logged by the driver in the log file and returned by ctutil. These errors are generated internally by the driver and are converted into an error to be returned to the application. They do not match any standard Btrieve error codes.

The error codes logged by the driver in the log file are formatted as follows:

THREAD> DATE  T  TIME  SRC:LINE:FUNCTION  TYPE  E1:E2:E3 MESSAGE
 

For example:

00002038> 20150506T105656  api:5248:ctl_regins ERROR 19:133:0 INTISAMX(1280,32,64,1280,1,,(not displayed),FAIRCOMS)
 

The first part of the message is the thread ID. The next part is a date-time stamp. DATE is formatted as yyyymmdd followed by T and then the TIME formatted as hhmmss:

20140312T081659 = March 12, 2014 at 8:16:59 AM.

The next part of the message (SRC:LINE:FUNCTION) indicates the source module, line number, and function returning the error, which may be required by FairCom Support:

• SRC: Columns 16-20 acronym for source module where the error is logged (usually add ctcb in front to get the actual source module name)
• LINE: Columns 22-25 line number where the error has been logged (usually just after it is generated)
• FUNCTION: Columns 27-36 function name where the error has been logged

For example:

api:4397:ctl_regins

Columns 38-42 indicate the event type: ERROR, WARNG, INFO, PROFL, DEBUG.

Following the ERROR event type, you will see three numbers delimited by colons (":"). These numbers indicate the following in the order listed:

• E1: Logical driver error (see the table below)
• E2: c-tree isam_err/uerr_cod (see Errors.)
• E3: c-tree sysiocod

For example, ERROR 19:133:0 indicates COBOL error 19 (CTE_INTERFACE), FairCom DB error 133 (ASKY_ERR), and sysiocod 0.

The final part of the message is internal information (the failing function and the function arguments), for example:

INTISAMX(1280,32,64,1280,1,a)

Below are examples of other event types:

20140725T165133  api:0436:ctl_init   INFO  configuration file: ctree.conf
20140725T165133  api:0437:ctl_init   INFO  client version:10.5.0.28751-140717 id:34
20140725T165133  api:4706:ctl_setins INFO  server version:10.5.0.28751-140717 id:34

20140725T165908 core:0611:cts_make   DEBUG FILE created: custmast
20140725T165908  api:5492:ctl_conffi DEBUG FILE "custmast" matches <file> #0
20140725T165908  fsi:0576:ct_make2   PROFL 079310 counts on file:custmast

20140725T170057  api:1926:ctl_open2  WARNG transaction configuration mismatch: <transaction>no</transaction> but file is ctPREIMG

FairCom RTG/ISAM Error Codes

FairCom RTG/ISAM SQL Access Errors

The FairCom RTG/ISAM solution is enabled through a server-side callback module, which implements FairCom DB API callback routines. Errors that occur within these routines generate a standard FairCom DB API error code that is context sensitive to this implementation. Here is a list of possible return codes from this module, and their meaning in FairCom RTG/ISAM XDD handling.

Troubleshooting

This section provides some useful troubleshooting tips.

For troubleshooting performance issues, see the section titled Performance Tuning.

A Note About Error Codes

Most of the FairCom RTG/ISAM errors are intended for developers and will seldom be seen during normal operation.

The FairCom RTG/ISAM products are built upon a specialized version of the FairCom DB core database engine. The complete list of possible FairCom RTG/ISAM errors can be found in the Errors document.

For error codes returned by the XDDCHECK API, see:

• XDDCHECK Errors

Error 407

Support has been added to the FairCom RTG/ISAM ctutil utility to open files affected by error 407 so it can export data from a file that has a damaged resource chain. This support requires ADMIN permission and the OPENCRPT file mode. To use this functionality, ctutil must be renamed to ctunload407. The ctunload407 utility functions similar to ctutil ‑unload except that it automatically connects as ADMIN (with the default ADMIN password) and enables the <allowcorrupt> setting.

Error 408 / 438

Error 408 / 438 during -sqlink indicates that no record definition is available. Either the file does not have an XDD resource (-sqlinfo was not performed) or the server did not load the data conversion callback library. Possible causes are:

• LOAD_CALLBACK_LIB ctsrvr.cfg keyword was not specified or invalid.

Or

• The callback library is not in LD_LIBRARY_PATH (UNIX).

Client/Server Incompatibility

An internal error CTE_INCOMPATIBLE (37) is returned when the client or server is outdated. An entry is sent to <log> with a logical error 37 and one of the following:

• c-tree error -3 (CTE_OLD_CLIENT) when the client is older than the server
• c-tree error -4 (CTE_OLD_SERVER) when the server is older than the client

File Matching Rules in ctree.conf

When ctree.conf contains only one <instance> element, it is not mandatory to specify a <file> rule because it is implicit that FairCom RTG/ISAM needs to use the one available instance to open files.

If you specify more than one instance, you need to specify a <file> rule so that FairCom RTG/ISAM knows which instance to use to open files. When specifying more than one instance, specify a default file rule into the instance you want to use:

<config>
    <log>n</log>
    <instance server="FAIRCOMS"></instance>
    <redirinstance>
        <file name="*">
        </file>
    </redirinstance>
</config>

Please notice that to specify a default file rule you can omit the name/dir attributes so the above configuration can also be specified as follows:

<config>
    <log>n</log>
    <instance server="FAIRCOMS"></instance>
    <redirinstance><file/></redirinstance>
</config>

The above concept applies to all <*instance> elements: <instance>, <redirinstance>, etc.

Troubleshooting Performance

The following features can improve performance:

• Using the <prefetch> feature to improve performance of sequential reads.
• Using the KEEPOPEN feature (which can be enabled in ctsrvr.cfg) if the application is frequently using OPEN/CLOSE.
• Disabling <optimisticadd> if the application frequently performs WRITE operations on existing records.
• Disabling <transaction> if transactions are not in use and data is stored on secure media (hardware redundancy, etc.).
• Enabling <ctfixed> to force creating fixed-length record data files as ctFIXED files.