=================================================
                        RELEASE NOTES
                            FOR
       INFORMIX ESQL/C for Windows 5.01.WD1 and 5.01.WC1
                        As Of 5/12/94
       =================================================

TABLE OF CONTENTS
I.    OVERVIEW OF RELEASE NOTES

II. INSTALLATION & SUPPORTED CONFIGURATIONS

III. NEW FEATURES

IV. NEW ARCHITECTURE & PERFORMANCE

V. THIRD PARTY VENDOR WINSOCK IMPLEMENTATIONS

VI. DLL PROGRAMMING CONSIDERATIONS

VII. TROUBLESHOOTING ESQL/C

VIII. NOTES FOR MIGRATING APPLICATIONS FROM 4.X TO 5.01 ESQL/C

IX. KNOWN PRODUCT DEFICIENCIES

X. BUGS FIXED WITH 5.01.WD1


I. OVERVIEW OF RELEASE NOTES The purpose of these release notes is to make the user aware of changes in products that might affect existing applications. The release notes contain information on changes from previous versions, known problems, and work-arounds. Problem IDs are assigned to known problems to assist you in identifying the problems to Client Services personnel. The release notes document is not intended to be all-inclusive; it is a tool to assist you in the update process. Please consult Informix product manuals for additional information on product features and for clarification of product behavior.
II. INSTALLATION & SUPPORTED CONFIGURATIONS The order of installation for Informix products is important. For DOS/Windows client products, install in version number order. ESQL/C for Windows, communicating via INet for Windows, was tested with the following supported server configurations: 5.0x OnLine for UNIX database servers 6.00 OnLine for UNIX database servers 5.0x SE for UNIX database servers 6.00 SE for UNIX database servers 5.0x SE for NT database servers 4.1x OnLine for NetWare database servers NOTE: The cancel request feature of ESQL/C for Windows and INet for Windows is only supported by versions 5.01 and later of BSD based UNIX ports (e.g., Sun) and by versions 5.02 and later of System V based UNIX ports (e.g. HP). The cancel request feature is not supported over the IPX protocol.
III. NEW FEATURES The following major features have been introduced in the ESQL/C for Windows 5.01 release: New Routines to Facilitate Canceling an SQL Request New Routines to Manage Database Connections Directly Structure for Runtime Specification of Server Information Support for the Microsoft C/C++ 8.00 and 8.00c Compilers (Microsoft Visual C/C++ 1.0 and 1.5) Support for the Borland C/C++ 3.1 and 4.0 Compilers New Compile Options Prototype Header File for ANSI Compliance Dynamic SQL X/Open Interface New Datetime and Interval Conversion Routines Ability to Access NLS Databases The following features have been added with 5.01.WD1: ESQL/C Displays compiler command line ------------------------------------- A new Esql option has been added, "dcmdl", if coded the command line of all programs executed by Esql will be displayed on STDOUT, these programs are ESQLC, the C compiler (CL or BCC), LINK, and RC. ESQLC errors in Microsoft Error Format -------------------------------------- A new Esql option has been added, "mserr", if coded Esqlc errors and warnings will be displayed in the Microsoft error format. If you have a Text Editor that can run the pre-processor (esql or %INFORMIXDIR%\lib\esqlc), capture STDOUT/STDERR and interpret it in MS error format the editor can display the file and line with an error and display the error text from the pre-processor. Most Microsoft IDEs (Integrated Development Environment) can do this. NOTE: For ease of coding call "esql -mserr" unless you get an out of memory error, then call %INFORMIXDIR%\lib\esqlc -mserr.
IV. NEW ARCHITECTURE & PERFORMANCE OPEN ARCHITECTURE ----------------- INet PC 4.10 is implemented as five TSRs which communicate with specific versions of specific PC TCP/IP packages. INet for Windows 5.01 is implemented as a series of DLLs which communicate with any WINSOCK 1.1 compliant TCP/IP package or with IPX. The architecture of INet for Windows 5.01 is open and flexible. However, the open architecture requires that a series of DLLs be used. Communication along a chain of DLLs is not as fast as direct communication to a specific TSR. 4.10 INet PC ------------ Application - LDLLSQLW.DLL - REMSQL.EXE (TSR) - Network Driver(TSR) 5.01 INet for Windows --------------------- Application - ISQLI501.DLL - WINETMAN.DLL - INETWSOK.DLL - Vendor's WINSOCK.DLL - Network Driver (TSR or DLL) or Application - ISQLI501.DLL - WINETMAN.DLL - INETIPX.DLL - INETIPX.EXE (TSR) - IPX (TSR) CPU SHARING ----------- INet for Windows gives up the CPU using the Windows PeekMessage() function. This allows other applications to share CPU time. This automatic sharing of the CPU may cause ESQL/C applications to run a little more slowly than applications run with 4.10 Inet PC. The CPU sharing capability may be turned off. MULTIPLE EVERYTHING ------------------- INet for Windows provides support for multiple applications, with multiple connections, using multiple cursors. To provide support for multiple applications, connections, and cursors additional SQLI code is required to switch connections and contexts. For some ESQL/C applications, this context switching may increase execution time when moving from 4.10 ESQL/C to 5.01 ESQL/C. NON-BLOCKING CONNECT -------------------- The default behavior of I-Net for Windows is to release the CPU when response from the network is not available. This allows other Windows applications to run. Some applications will not function correctly if the CPU is released. It is possible for an I-Net for Windows application to prevent the release of the CPU. This is accomplished by creating an asynchronous callback function which does not call PeekMessage(), and registering the callback function with sqlbreakcallback(). In 5.01.WC1, it was possible to prevent release of the CPU for all operations except connect. This was because the user's callback function was not enabled until after a connection is established. This behavior has been changed in 5.01.WD1, and the release of the CPU by connect can now be prevented by the method described above. NOTE: By design the WINSOCK API will release the CPU during the API calls gethostbyname() and getservbyname() when the Domain Name Server is used. The only way to prevent the release of the CPU is to have local files on the PC that the WINSOCK API can use to resolve hosts and service names. Use of the Domain Name Server or local services is controlled by the WINSOCK vendor's configuration parameters.
V. THIRD PARTY VENDOR WINSOCK IMPLEMENTATIONS Informix-Net for Windows supports both IPX and TCP/IP protocols for communication with remote database servers. For TCP/IP protocols, any TCP/IP implementation with a true WINSOCK 1.1 interface is supported. Although most vendors now have WINSOCK implementations, many are not truly WINSOCK 1.1 compliant. The following WINSOCK 1.1 compliant TCP/IP packages are known to work with Informix-Net for Windows, with the conditions shown. NOTE FOR ALL VENDOR WINSOCK PRODUCTS: Be sure that the WINSOCK.DLL file provided by the vendor is dated after January 1993. The WINSOCK 1.1 specification was finalized in January 1993. Any WINSOCK.DLL released prior to that date is not WINSOCK 1.1 compliant. FTP PC/TCP 2.2 -------------- NOTE: Because of tne new Non-Blocking Connect feature, a patch for FTP 2.2 must to be obtained from FTP Software. The patch is named 222TS210.EXE. After the patch has been applied, the ETHDRV kernel must be started with the -B parameter. The line in the autoexec.bat file will look like this: ethdrv -B. The WINSOCK.DLL released in March 1993 has exhibited strange behavior in our testing. The WINSOCK.DLL released in July 1993 has proven reliable under all conditions. NetManage Chameleon 3.10, 3.11 and Newt 3.10, 3.11 -------------------------------------------------- NOTE: Version 3.10 of NetManage products do not support the Informix-NET for Windows cancel request feature. Version 3.11 of NetManage products do support the Informix-NET for Windows cancel request feature. NOTE: Version 3.10 and 3.11 do not support the new non-blocking Connect properly and will hang when attempting a connect to a non-existent Service (see section IV on non-blocking Connect). Wollongong Pathway Runtime for DOS/Windows 1.2.0.1 -------------------------------------------------- NOTE: The version of the Pathway Runtime software, which provides the WINSOCK.DLL, is not tied to a particular version of the entire Pathway Access package. Be sure that the Pathway Runtime piece of Access is the 1.2.0.1 version or later. SUN PC-NFS 5.0 -------------- When loading Sun PC-NFS, the RTM.EXE module should be loaded with the -heap 64 parameter. The line in autoexec.bat should look like this: RTM -heap 64 If the RTM module is loaded without the -heap parameter, you may receive WSAENOBUFS errors from WINSOCK.DLL. The Sun implementation of WINSOCK may show poor performance as compared to other vendor WINSOCK implementations. There are several patches available on Compuserve that help to improve the performance of Sun's WINSOCK.DLL. Occasionally, PC-NFS will fail on the WINSOCK call getservbyname(). This problem can sometimes be solved by copying the services file from the PC-NFS directory to the \WINDOWS\SYSTEM directory. Novell LAN Workplace for DOS 4.1 -------------------------------- NOTE: Lan Workplace for DOS 4.1 does not come with a WINSOCK DLL. Novell makes the WINSOCK.DLL for LAN Workplace available through Compuserve. As of this writing, the latest WINSOCK.DLL, dated 11/23/93, is in the file LWP168.EXE on Compuserve. Microsoft Client TCP/IP for Windows for Workgroups -------------------------------------------------- NOTE: If the message "WINSOCK API Initialization Error" occurs when starting an Informix-Net for Windows application, it may be necessary to start a Microsoft WINSOCK application, such as telnet, before starting the Informix-Net for Windows application. To successfully run Microsoft TCP/IP, it is necessary to have a fairly large amount of conventional memory available before starting Windows. If there is not enough memory, a message box indicating the low memory situation will come up when a connection is attempted.
VI. DLL PROGRAMMING CONSIDERATIONS Any pointers passed to or used by a DLL must be far pointers. The SQL statement "WHENEVER ERROR STOP" cannot be used in a DLL. Dynamically loading (using LoadLibrary) a DLL that uses Float (using WIN87EM.DLL) from an application that does not use any floats causes a GPF the second time the library is loaded. To avoid this problem, have a float value in your application, or Load library WIN87EM.DLL before loading any DLL that uses floats and free WIN87EM.DLL at exit time.
VII. TROUBLESHOOTING The paragraphs below describe some common problems encountered when using ESQL/C for Windows and INet for Windows and their solutions. Environment Variables Not Recognized ------------------------------------ INet for Windows does not use DOS environment variables. All values for environment variables which should be passed to the engine (such as DBPATH) must be set in the [Environment] section of the INFORMIX.INI file. Memory Leaks Encountered ------------------------ There are a few ESQL/C functions that can cause memory leaks. Cursors and statement IDs use a small amount of memory for internal structures that is not released. A full description is in the Known Problems section. Also, it is up to the user to free memory associated with an sqlda structure. When the user is finished with an sqlda structure, the associated memory should be freed. SQLCA Unresolved External Error ------------------------------- If a program does not use any ESQL/C statements or functions, none of the ESQL/C wrapper libraries are linked to the executable, since the linker will only link those objects/modules within the wrapper libraries which contain the called functions. The sqlca structure is defined in the wrapper libraries. If the sqlca.h file is included in an application with no ESQL/C statements or functions, the sqlca structure will be undefined and will cause the "sqlca unresolved external" error at link time. "Memory Allocation Failed" on Allocate Descriptor ------------------------------------------------- The maximum value which can be used in the statement "ALLOCATE DESCRIPTOR WITH MAX X" is (32K-1)/(sizeof(sqlvar_struct). An attempt to use a larger value will result in the "Memory Allocation Failed" error. Escape Sequences Not Recognized ------------------------------- Where the line: esql -EDTEST=\\"123\\" is required on Unix, the line: esql -EDTEST=\\\"123\\\" is required when using ESQL/C for Windows. When calling esql from a make file, it is necessary to have one more level of escaping: esql -EDTEST=\\\\\\"123\\\\\\" Error Message Lists Wrong Engine Version ---------------------------------------- Some error numbers contain multiple sections of information. For example, Error -404 has different descriptions for 5.X and 6.X engines. RGETMSG will return the first description encountered in the message files. To see all descriptions for the error, run the FINDERR utility, and scroll through all the text. -952 "User's Password is not correct for the remote host" --------------------------------------------------------- INet for Windows cannot transmit passwords with spaces. The user account on the remote machine must not use spaces as part of its password.
VIII. NOTES FOR MIGRATING APPLICATIONS FROM 4.X TO 5.01 ESQL/C Some of the changes, bug fixes or enhancements made in Version 5.0 could potentially require changes to existing applications. We expect that incompatibilities will be rare; however, we are providing the information so you can determine if you have any applications that may require updating. Many of the following items have references to additional information contained in the documentation. 1. Prior to Version 4.1, the database server products allowed explicit table name qualification (<table name.<column name) in the column list of INSERT statements and the SET clause of UPDATE statements. For example, INSERT INTO tab (tab.col1, tab.col2) VALUES (1, 2); UPDATE tab SET tab.col1 = 10; The above syntax is incompatible with the ANSI standard, so Version 4.10.UD1 was modified to return a syntax error if a column was explicitly qualified with a table name in these contexts. The modified syntax which produces results equivalent to the above syntax is as follows: INSERT INTO tab (col1, col2) VALUES (1, 2); UPDATE tab SET col1 = 10; However, due to backward compatibility problems that this change imposed, in versions later than Version 4.10.UD2, and in Version 5.0, the table.column syntax is allowed again. If the user has the environment variable DBANSIWARN set or uses the -ansi option at runtime, an ANSI warning is returned to the user when s/he uses the above non-ANSI syntax. 2. New syntax has been introduced to support the creation of private synonyms in non-ANSI databases. A private synonym can only be accessed by the owner of the synonym, or by explicitly naming the owner of the private synonym. Existing synonyms in non-ANSI databases are public synonyms and can be accessed by all users. In ANSI databases, synonyms are always private. If a public and a private synonym have the same name, precedence is given to the private synonym. Prior to Version 4.0, synonyms were always private. A change was made in Version 4.00.UC1 that created some problems with backward compatibility. This has been corrected and now private synonyms are supported again in non-ANSI databases. The new syntax is as follows: CREATE [PUBLIC | PRIVATE] SYNONYM [owner.]<synonym FOR [dbname[@sitename]:][owner.]<table 3. There is a new command-line option introduced for static cursor names and statement-id names to be consistent with the behavior of case sensitivity in the Informix Embedded products, Version 4.1. In the following example, $prepare st from "select * from tab1"; $prepare ST from "insert into tab2 values (1,2)"; $declare curname cursor for st; $declare CURNAME cursor for ST; Informix embedded products, Version 4.1 did not return an error in the case of the statement-id and cursor names. In Version 5.0, this syntax is not allowed as both the cursor names and statement-id names are now case insensitive. The database server products have always treated the cursor names as case insensitive. If this change presents a compatibility problem for existing embedded language applications, you may instruct the preprocessor to be sensitive to case differences in statement-id and cursor names, effectively retaining the 4.X behavior. To do so, specify the -cs parameter in your preprocessor command line. However, we do not recommend using this new option except as a temporary solution, as it will be removed in Version 6.0 Please make a note to change your applications accordingly. Note that dynamically named cursors and statement-ids have always been case insensitive. 4. Beginning with Version 5.0, when a statement is prepared and executed, the database server performs extra validation checks to make sure that each time the prepared statement is executed, the information gathered at preparation time is still valid. If a DROP TABLE, ALTER TABLE, or RENAME TABLE statement affects a table referenced in the statement, the prepared statement is invalidated. If the statement is invalid, an error is returned, and the user must reprepare the statement. For example, in the following sample ESQL/C program, the open of the cursor will now return an error because the table is dropped after the statement is prepared. $prepare qid from "select * from tab"; $drop table tab; $create table tab(a int); $declare c cursor for qid; $open xx; /* this will return an error -242 or -710 */ 5. Currently Version 5.0 conforms with the ANSI SQL89 standard, dated August 1987. Thus, for views created with the WITH CHECK OPTION, the insert statement below succeeds. In other words, a data row inserted into a view created with the WITH CHECK OPTION must result in the WHERE clause of the view definition evaluating to true or unknown. CREATE TABLE t(a int); CREATE VIEW v AS SELECT * FROM t WHERE a 10 WITH CHECK OPTION; INSERT INTO v VALUES(NULL); Subsequently, the SQL89 standard has been changed to correct an errata. As a result of this correction, the insert above should now fail. In other words, rows inserted into views created with the WITH CHECK OPTION must result in the WHERE clause of the view definition evaluating to true and only true. In order to conform with the corrected ANSI standard, in a future version, the insert statement above will no longer succeed. 6. Keyword Limitations In Version 5.0, with the introduction of referential and entity integrity and stored procedures, new keywords were introduced to the SQL language. As a result, certain uses of these new keywords may now result in ambiguities that did not exist prior to Version 5.0. For example, the following statement now returns a syntax error because "check" is an SQL keyword; in the following context, it can be interpreted as being part of a check constraint definition. CREATE TABLE tab (check INT); For a complete list of keyword limitation, refer to "The Informix Guide to SQL: Reference" Manual, Chapter 7. 7. Scope of SQL statement identifiers In Informix embedded SQL products Version X.10.03 and earlier, prepared SQL statement names and cursor names (as specified in the PREPARE and DECLARE statements) were local to the compilation unit (i.e., .ec source module) in which they were defined. A cursor or prepared statement declared in any paragraph in that source file could be used by any other paragraph in that same source file, but it could not be referenced from other source files. This practice is consistent with the other Informix embedded SQL products and with INFORMIX-4GL. This feature allowed programmers to use identical statement names in separate source files, with each file having its own object identified with that name. The base file name would be prepended to the internal statement name during the preprocessing phase so that the database engine would still be able to uniquely identify the statements. However, this functionality introduced some problems of its own. Since the database engine only recognizes the first 18 characters of a statement name, long source file names and/or statement names which were non unique in the first few characters could cause the statement names to collide and be misassigned. In Version 4.0, this functionality was changed to consider all database server statement names to be global to the entire program. This practice avoids the disadvantages mentioned in the previous paragraph and is more in line with ANSI requirements. Although well-intentioned, this change can result in behavior changes in applications compiled from multiple source files that had similarly-named cursors or prepared SQL statements. In Version 5.0, we have introduced a new preprocessor option that restores the X.10.03 prepared statement and cursor naming conventions. By specifying the "-local" flag on the command line, the older convention for internally naming cursors and prepared statements can be chosen. Example: esql -local [other options] main.ec func1.ec func2.ec 8. Describe with Floats A DESCRIBE of a prepared statement such as the following: select f from tab where tab is defined as: create table tab ( f float ); will describe f as of type DECIMAL instead of FLOAT. This happens because in a heterogeneous client/server configuration, the floating point formats of the two computers are different. 9. Limits in ESQL/C Size of host object name: 132 chars Size of host object subscript: 132 chars Size of indicator object name: 132 chars Size of value for fetch relative: 132 chars Size of SQL identifier (table name, etc): 132 chars Size of number constant: 132 chars Size of macro name: 132 chars Size of macro value: 132 chars Size of statement name: 132 chars Size of quoted string literal: 256 chars Number of statement_ids 64 Number of levels of host-language block nesting 16 Number of levels of include-file nesting: 8 Length of line: 512 chars Size of statement label: 70 chars Number of nested records: 100
IX. KNOWN PRODUCT DEFICIENCIES The following deficiencies are known to exist in the 5.01 ESQL/C for Windows product. Bug 17745: FAR/NEAR KEYWORD IN HOST VARIABLE DECLARATIONS CAUSE SYNTAX ERROR The following usage causes syntax error: void test_fn(stmt) $char far *stmt; { $char far *t; ... ... ... } Syntax errors -33051 and -33040 are flagged. Bug 21833: DECLARING A CURSOR NAME THAT IS TOO LONG RETURNS THE WRONG ERROR NUMBER If you code a Cursor Name that is longer than 18 characters you should get error -484 "SQL descriptor's name is too long", instead you get -404 "A NULL control block has been passed as an argument". This problem occurs on UNIX ESQL/C as well and will be fixed in all versions at the same time.
X. BUGS FIXED WITH 5.01.WD1 Bug 19788: Statement ID truncated to 8 bits with 4.10 apps, no warning given. Problem: 4.10 cursor structure allows only 8 bits for the statement ID (256 IDs), 5.01 allows 16 bits (64k). Solution: When truncation of statement ID is done generate error number -257 "System limit on maximum number of Statements exceeded" as the 4.10 Front-End did. Statement or Cursor is freed. Bug 24607: Trailing spaces are not allowed in Statement name. Problem: Engine will not detect that a statement name with 1 or more spaces is the same as one that does not end with a space. Solution: Terminate the statement name at the 1st trailing space. Bug 25387: SETNET stays in memory after Exit. Problem: When user requests SETNET to exit it destroys its Window but does not exit. Solution: Destroy window and force Exit. Bug 22498: I-NET loses control during a connect. Problem: During a connect the WINSOCK API can release control of the CPU. Solution: See section IV. Non-Blocking Connect.