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

• Microsoft SQL Server Programmer's Toolkit, version 4.2

                     Microsoft SQL Server version 4.2

                     DB-Library Update version 4.20.50

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*);

   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

   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.

   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 *);

   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))

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

  bcp_sendrow(dbproc)

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

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>).

<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.

    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.

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);
}

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

    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.

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;

char            *servnamebuf;

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.

    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.

    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.

    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).

    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.

    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).

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

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

    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.