Release Notes for INFORMIX ESQL/C for Windows 5.01.WD1
====================================
RELEASE NOTES
FOR
INFORMIX ESQL/C for Windows 5.01.WD1
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: In order to use the Cancel Request feature of Informix-Net
for Windows, a patch for FTP 2.2 needs 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.