FIX: DB-Library Version 4.20.50 FixList and README.TXT

ID: Q105089

The information in this article applies to:

Microsoft SQL Server Programmer's Toolkit, version 4.2
Microsoft SQL Server version 4.2x

DB-Library Update version 4.20.50

FIXLIST

The following list of problems, and various other improvements that were discovered during internal testing, have been fixed in DB-Library version 4.2.5. For more information, please contact your primary support provider.

Please note that workarounds have been provided for your information only. It is not necessary to implement these workarounds if you have the updated software.

FIX: dbopen Trap Locks Up Windows in Debugging Mode

BUG# PRSQL9209030

SYMPTOMS

When a call to the dbopen function fails due to a bad login ID and the application is being run from Microsoft QuickC for Windows, QuickC for Windows traps the error. However, if Windows is in debugging mode while the application is being run, Windows will lock up.

WORKAROUND

During the debugging phase of development of a Windows DB-Library (dblib) application, avoid issuing a dbopen function with an invalid login ID.

FIX: Keyset-Driven Cursors Cannot Be Opened in MS-DOS

BUG: 7343

SYMPTOMS

A call to the dbcursoropen() function for a keyset-driven cursor under MS-DOS will fail, with the application's message handler reporting that the DBPROCESS is dead. The keyset cursor will fail to open under all concurrency options available to cursors, namely CUR_READONLY, CUR_LOCKCC, CUR_OPTCC, CUR_OPTCCVAL. Even a results set returning as few as 50 rows cannot be handled.

CAUSE

The dbcursoropen() function attempts to allocate memory to hold the keyset. It fails when it tries to allocate the hard-coded 65,532 bytes of memory. DB-LIBRARY (db-lib) immediately marks the DBPROCESS as dead for this failure to allocate memory. The application's message handler is then called, which reports that the DBPROCESS is dead.

WORKAROUND

If cursors need to be used under MS-DOS, use dynamic cursors or mixed cursors instead of keyset-driven cursors.

FIX: dbreadtext() May Not Read Data in Large Chunks

PROBLEM ID: 8216

SYMPTOMS

The DB-LIBRARY (db-lib) dbreadtext() function returns successfully on reading image/text data, but no data is retrieved into the application-defined buffer.

CAUSE

When reading text/image data in chunks of 32K or greater, db-lib incorrectly fails to copy the data into the application-defined buffer. Note that this problem arises only when, for instance, a 48K text/image data value is read in 33K chunks using dbreadtext().

WORKAROUND

For image/text data that is larger than 32K, read the data in smaller chunks (each chunk being smaller than 32K) using the dbreadtext() function. In other words, application programmers must make sure the "bufsize" parameter in the dbreadtext() call is set to less than 32K.

For text/image data that is greater than 32K and less than 64K, if all the data needs to be retrieved in one step, use a SELECT statement to retrieve the data. Note that DBTEXTSIZE and DBTEXTLIMIT options must be set appropriately.

Another workaround is to use the Transact-SQL readtext() function.

FIX: commit_xact in Windows Returns FAIL

PROBLEM ID: BUG# 7824

SYMPTOMS

In a Windows DB-LIBRARY (db-lib) program, the commit_xact function returns FAIL when it should return SUCCEED. Very rarely, commit_xact can return SUCCEED when it should return FAIL.

CAUSE

Windows db-lib incorrectly miscasts a far pointer into a near pointer, causing commit_xact to return an incorrect value. This incorrect return value is usually FAIL, though it may be SUCCEED.

FIX: dbcursoropen Can GP Fault with Certain SELECTs

Problem ID: Bug#8375

SYMPTOMS

The dbcursoropen function can GP fault when the SELECT statement contains a HAVING, GROUP BY or ORDER BY clause.

CAUSE

DB-Library attempts to read too much memory when parsing the SELECT statement. If it reads off the end of a segment, a GP fault will occur. This is more likely to occur when the FROM or WHERE clause is significantly longer in than the HAVING, GROUP BY or ORDER BY clause.

FIX: Keyset dbcursorfetch of SELECT that Returns No Rows

Problem ID: Bug#8517

SYMPTOMS

The first call to the dbcursorfetch function sets only the FTC_ENDOFKEYSET flag in pstat[0].

CAUSE

When the SELECT statement used to open a keyset driven cursor returns no rows, DB-Library fails to set the FTC_ENDOFRESULTS flag in pstat[0].

FIX: Incorrect dbrpcparam() Function Prototype

Problem ID: Bug#8400

SYMPTOMS

The dbrpcparam() function prototype in the DBMSWIN section of SQLDB.H incorrectly lists "DBPROCESS*" as the first parameter. This parameter should be "DBPROCESS NEAR *".

WORKAROUND

In the DBMSWIN section of SQLDB.H, change the following line (line 505 in the SQLDB.H file dated 9/15/92) from:


   extern RETCODE SQLAPI dbrpcparam(DBPROCESS*,CHAR far *,
      BYTE,INT,DBINT,DBINT,BYTE far*);

to the following:


   extern RETCODE SQLAPI dbrpcparam(DBPROCESS NEAR *,CHAR far *,
      BYTE,INT,DBINT,DBINT,BYTE far*);

FIX: dbwinexit After dbinit Causes Error

PROBLEM ID: BUG# 7855

SYMPTOMS

Running debug Windows 3.1, calling dbwinexit generates the following debug Windows error:

err SQLEDIT->W3DBLIB GLOBALHANDLE+C: Invalid HANDLE: 0x0000 FatalExit code = 0x600B

CAUSE

DB-LIBRARY (db-lib) does not properly handle calling dbwinexit immediately after dbinit. Note that this error occurs only in debug Windows 3.1, not in retail Windows 3.1.

WORKAROUND

Use the Windows SDK tool DBWIN to set the "Don't Break on Fatal" option in debug Windows 3.1.

FIX: bcp_collen Can Cause Error 10066 During bcp_moretext

Problem ID: Bug#8897

SYMPTOMS

Calling bcp_moretext results in DB-LIBRARY (db-lib) in the following error message (error 10066):

"Attempt to send too much TEXT data via the bcp_moretext() call."

CAUSE

DB-LIBRARY incorrectly handles bulk copy (BCP) text and image data transfer when bcp_collen is called with a varlen parameter greater than 65535.

WORKAROUND

Use bcp_bind to adjust the varlen parameter of text and image columns.

FIX: Cursor Functions Generate Error in Debug Windows 3.1

Problem ID: Bug#9000

SYMPTOMS

Using DB-Library cursors in debug Windows 3.1 generates the following error:

GlobalUnwire: Object usage count underflow 0000:00F3
FatalExit code = 0x02F0
Abort, Break, Exit or Ignore?

CAUSE

DB-Library incorrectly calls GlobalUnwire under certain circumstances when using cursor functions like dbcursoropen and dbcursorclose.

WORKAROUND

Start the DBWIN application that comes with debug Windows 3.1, choose the Settings command from the Options menu, and check the "Don't Break on Errors" options. This will avoid the FatalExit prompt.

FIX: Incorrect dbcursoropen Function Prototype

Problem ID: Bug#8386

SYMPTOMS

The dbcursoropen function prototype in the DBMSWIN section of SQLDB.H incorrectly lists "DBPROCESS *" as the return value. This return value should be "DBPROCESS NEAR *".

WORKAROUND

In the DBMSWIN section of SQLDB.H, change the following line (line 592 in the SQLDB.H file dated 9/15/92) from:


   extern  DBCURSOR * SQLAPI dbcursoropen(DBPROCESS NEAR *,
      CHAR far *,INT,INT,UINT, DBINT far *);

to the following:


   extern  DBCURSOR NEAR * SQLAPI dbcursoropen(DBPROCESS NEAR *,
      CHAR far *,INT,INT,UINT, DBINT far *);

FIX: dbcancel Returns FAIL During dbreadtext Operations

Problem ID: Bug#8675

SYMPTOMS

The dbcancel function returns FAIL when called during dbreadtext operations. This can cause DB-Library error 10038 "Attempt to initiate a new SQL Server operation with results pending" when a new command is later executed on the same connection.

CAUSE

When dbcancel is called after dbreadtext returns a positive value N indicating that N bytes were read, DB-Library incorrectly fails to cancel the command batch.

WORKAROUND

Call dbreadtext until it returns 0, indicating an end of row condition, or NO_MORE_ROWS. Then call dbcancel to cancel the command batch.

FIX: dbopen Generates Error in Debug Windows 3.1

Problem ID: Bug#8399

SYMPTOMS

Making a connection to SQL Server in debug Windows 3.1 generates the following error:

err WINQUERY -> W3DBLIB LOCALFREE+c: Invalid local handle: 0x0000
FatalExit code = 0x6023
Abort, Break, Exit or Ignore?

CAUSE

When dbopen is called, DB-Library incorrectly attempts to free a NULL memory handle.

WORKAROUND

Start the DBWIN application that comes with debug Windows 3.1, choose the Settings command from the Options menu, and check the "Don't Break on Errors" options. This will avoid the FatalExit prompt.

FIX: bcp_sendrow Incorrectly Handles NULL Values

PROBLEM ID: Bug#8586

SYMPTOMS

bcp_sendrow does not fail when an attempt is made to insert NULL values in columns of a table that do not allow nulls. In the case of variable length datatypes columns, such as VARCHAR and VARBINARY, NULLs are inserted whereas other datatypes may contain 0 or an empty string.

Consider the following table:


  Create table test (c1 char(30), c2 varbinary(30))

then the bcp_bind call specifies a NULL data value by setting varlen parameter to 0:


  bcp_bind(dbproc,c1,0,0,NULL,0,0,1)

followed by


  bcp_sendrow(dbproc)

which does not fail and inserts NULLs for variable length columns and 0 or empty string for other datatypes in the table.

FIX: Browse Mode Update with a Datetime Index on the Table

PROBLEM ID: Bug#8633

SYMPTOMS

When attempting to update a table with unique clustered index on a datetime field from a browse mode DB-Library program, the update does not fail but some rows are not updated. This happens only for those rows that have non-zero seconds and milliseconds parts in the datetime column.

CAUSE

The dbqual() function does not generate the correct 'where' clause on a table with datetime column in the unique index where the datetime values have a non-zero seconds and milliseconds part. The string comparison for the datetime column does not contain the seconds and milliseconds part.

For example, consider the table


   create table test(c1 datetime, c2 char(4))
   go
   create unique index testind on test(c1)
   go
   insert test values ("May 1 1993 1:30:10:10PM", "Hi")
   go

Then the string comparison generated by dbqual() function is (c1='May 1 1993 1:30PM'). This should be generated instead as (c1='May 1 1993 1:30:10:10PM').

WORKAROUND

Perform non-browse mode update for rows which are failing. If possible, drop index on datetime and create it on another unique field in the table. If the seconds and milliseconds parts are not important, you can also make them zero in the datetime values entered by enforcing this either in the front end application or by putting an insert/update trigger on the table.

NEW NET-LIBRARY ERROR REPORTING

The new Net-Library files have enhanced run-time error reporting. If a network or operating system error is encountered during run-time, the Net-Library will pass the network or operating system error code back to the application's DB-Library error handler.

The network or operating system errors reported by the Net-Library will usually have the following format

Net-Library Error <net/os error code>:
<Net-Library function> (<net/os function>).

where
<net/os error code>

Is the error code returned by the <net/os function> during run-time. The meaning of this error code is dependent on the <net/os function> that returned this error code, and the Net-Library in use at the time the error occurred. Please examine your network or operating system documentation for complete information about this error code.

<Net-Library function>

Is the Net-Library function that was in use when the run-time error occurred.

Is the network or operating system function that returned the error code. Please examine your network or operating system documentation for complete information.

To properly distinguish DB-Library, Net-Library and operating system errors, a DB-Library application should have an error handler similar to the following


int err_handler(dbproc, severity, dberr, oserr, dberrstr, oserrstr)

DBPROCESS   *dbproc;
int         severity;
int         dberr;
int         oserr;
char        *dberrstr;
char        *oserrstr;
{
    printf("DB-Library error %d: %s\n", dberr, dberrstr);

    if (severity == EXCOMM && (oserr != DBNOERR || oserrstr))
        printf(Net-Library error %d: %s\n"' oserr, oserrstr);

    if (oserr != DBNOERR)
        printf("Operating system error %d: %s\n", oserr, oserrstr);

    if ((dbproc == NULL) || (DBDEAD(dbproc))
        return(INT_CANCEL);
    else
        return(INT_CANCEL);
}

For example, if the following error occurred while using the named pipe Net-Library on a LAN Manager - based network

DB-Library Error 10010:
Possible network error: Read from SQL Server failed.
Net-Library Error 53:
ConnectionRead (read()).

This would mean that LAN Manager error 53 occurred when the named pipe Net-Library function ConnectionRead called the network read() function. The meaning of LAN Manager error 53 can be determined by examining the LAN Manager documentation, or typing NET HELPMSG 53 at the command prompt. This returns

SYS0053: The network path was not found.

EXPLANATION: The server that you specified does not exist or has not been started. ACTION: Verify that you specified the path name correctly. Contact your network administrator if you continue to have problems.

OPERATING SYSTEM ERROR DOCUMENTATION

For a 16-bit MS-DOS or Windows DB-Library client, the operating system errors are standard MS-DOS extended error and are documented in the "Microsoft MS-DOS Programmer's Reference" (ISBN 1-55615-329-5) in Appendix C on pages 447 - 449, "The Programmer's PC Sourcebook" by Thom Hogan (second edition, ISBN 1-55615-321-X) on pages 3-123 - 3-124, also "Advanced MS-DOS Programming" by Ray Duncan (second edition, ISBN 1- 55615-157-8) on pages 453 - 455 and in "The MS-DOS Encyclopedia" (ISBN 1-55615-174-8) in Appendix C on pages 1461 - 1462. They are the same codes returned by Microsoft C run-time function _dosexterr(), and also MS-DOS Int 21 Function 59H.

For a 16-bit OS/2 DB-Library client, the operating system errors are standard OS/2 errors (many are in common with the MS-DOS errors) and are documented in the "Microsoft OS/2 Programmer's Reference" Volume 3 (ISBN 1-55615-222-1) in Appendix A on pages 409 - 413, and also in "Essential OS/2 Functions" by Ray Duncan (ISBN 1-55615-177-2) on pages 193 - 203.

For a 32-bit Windows NT DB-Library client, the operating system errors are standard Windows NT errors (many are in common with the MS-DOS errors) and are documented in the "Microsoft Win32 Programmer's Reference" Volume 2 (ISBN 1-55615-516-6) in Appendix A on pages 819 - 869. They are the same codes returned by Win32 function GetLastError().

NEW DB-LIBRARY FUNCTION

DB-Library for Windows, MS-DOS and OS/2 includes a new function, dbserverenum. Using the dbserverenum function, you can obtain the names of servers to which you can connect. The dbserverenum function can search for the names of SQL Servers either locally or over the network. For network searches, the Net-Library DLL used must support the dbserverenum function. A Net-Library DLL registers and finds servers on networks for a specific network environment such as Microsoft LAN Manager - based networks.

Syntax

The dbserverenum function has the following syntax:


RETCODE dbserverenum(searchmode, servnamebuf, sizeservnamebuf, numentries)

unsigned short  searchmode;<BR/>
char            *servnamebuf;<BR/>
unsigned short  sizeservnamebuf;<BR/>
unsigned short  *numentries;

where

searchmode

Defines whether the dbserverenum function checks for server names locally, on the network, or both.

To search for the names of servers listed in your WIN.INI file (Windows), or in OS2.INI (OS/2), set searchmode to LOC_SEARCH.

The LOC_SEARCH constant has the value 0x0001.

To search for the names of servers registered by the default Net Library, set searchmode to NET_SEARCH. The NET_SEARCH constant has the value 0x0002.

To search both locally and on the network for server names, use a bitwise OR operation (NET_SEARCH | LOC_SEARCH) to combine the values of LOC_SEARCH and NET_SEARCH. In this case, a server name is duplicated if the server name is defined both locally and on the network.

DB-Library first tries to load the default Net-Library set by the DSQUERY entry in the .INI file (Windows and OS/2). If no default entry exists, DB-Library loads the appropriate named pipe Net-Library.

servnamebuf

Is a pointer to a buffer that stores the server names returned by a search. When the dbserverenum function successfully returns a list of server names, the servnamebuf buffer contains the server names separated by null characters. The end of the list is designated by two consecutive null characters. Only complete server names are copied to the buffer. When a buffer is full and there are additional names that could not be copied to the buffer, dbserverenum returns the value MORE_DATA. Server names are returned in non-sorted order; names found using the LOC_SEARCH constant are returned before those names found using the NET_SEARCH constant. Note that dbserverenum can return server names even when SQL Server is not running. Therefore, although a server name is returned in the list of servers, it does not guarantee that you can access the server.

sizeservnamebuf

Specifies the size of the buffer for the server names returned by a successful search. The buffer size limits the maximum number of names that dbserverenum can return in a single call.

numentries

Returns the number of server names copied to the buffer by the current call to dbserverenum.

Returns

The dbserverenum function returns one or more of the following status code constants:

ENUM_SUCCESS (0x0000)

Indicates that the search to detect server names succeeded. ENUM_SUCCESS can be returned even when no servers are detected (when numentries = 0).

MORE_DATA (0x0001)

Indicates that DB Library has enough memory to service the dbserverenum request but the buffer passed to dbserverenum is not large enough to hold all the names returned. Increasing the size of sizeservnamebuf enables the buffer to hold more server names.

NET_NOT_AVAILABLE (0x0002)

Indicates that the Net-Library DLL is unavailable. A Net-Library DLL might be unavailable because no DLL is found or because the available Net-Library DLL does not support the dbserverenum function. When the searchmode parameter includes the NET_SEARCH mode, dbserverenum calls the default Net-Library DLL. When searchmode includes both the NET_SEARCH and LOC_SEARCH modes (NET_SEARCH | LOC_SEARCH), dbserverenum can return both MORE_DATA and NET_NOT_AVAILABLE (MORE_DATA | NET_NOT_AVAILABLE).

OUT_OF_MEMORY (0x0004)

Indicates that DB Library cannot allocate enough memory to service the dbserverenum request.

NOT_SUPPORTED (0x0008)

Indicates that the capability is not supported by the current Net-Library version or the current server platform.

ENUM_INVALID_PARAM (0x0010)

Indicates that an invalid parameter, such as a null pointer, was passed to the function.

Remarks

When the search mode is set to NET_SEARCH, dbserverenum calls the default Net-Library DLL (for example, named pipes or Novell* IPX/SPX). Because only one Net-Library DLL can be the default, those servers discernible to the specific server are enumerated using the NET_SEARCH parameter. You must add a specific server entry in the .INI file (Windows and OS/2) to use a Net-Library DLL other than the default Net-Library DLL. Servers listed in the .INI file (Windows and OS/2) are enumerated when the search mode is set to LOC_SEARCH.

Additional query words: dblib

Keywords : SSrvDB_Lib SSrvGen
Version : 4.2.5 | 4.2.5 | 4.2.5 4.2
Platform : MS-DOS OS/2 WINDOWS
Issue type :