========================================= RELEASE NOTES FOR DATABLADE DEVELOPERS KIT VERSION 4.0 April 29, 2005 ========================================= TABLE OF CONTENTS I. OVERVIEW OF RELEASE NOTES II. DATABASE SERVER COMPATIBILITY III. SOFTWARE COMPATIBILITY IV. CLIENT OPERATING SYSTEM COMPATIBILITY V. NEW FEATURES VI. UPGRADE ISSUES VII. CONVERSION AND REVERSION ISSUES VIII. EXAMPLE FILES IX. KNOWN PROBLEMS X. FIXED PROBLEMS +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ I. OVERVIEW OF RELEASE NOTES ============================= The purpose of these release notes is to make you aware of any special actions that are required to install, configure, and use the DataBlade Developers Kit on your computer. This file also describes new features and feature differences from earlier versions of this product and how these differences affect current products. In addition, this file contains information about known bugs and their workarounds. These release notes are not intended to be all-inclusive; they should be used as an addendum to the "DataBlade Developers Kit User's Guide," which provides thorough information about product features and product behavior. The "DataBlade Developers Kit User's Guide" is provided in PDF format in the %INFORMIXDIR%\dbdk\doc directory. To view the PDF file, you must have Adobe Acrobat Reader, available from the Adobe Web site at http://www.adobe.com. The "DataBlade Developers Kit User's Guide" is also provided in HTML format as part of the DBDK InfoShelf, which you can access from the Informix program group or the BladeSmith Help menu. These release notes are written for DataBlade module developers who use the DataBlade Developers Kit software utilities and documentation. II. DATABASE SERVER COMPATIBILITY ================================== The code you can generate with this version of the DataBlade Developers Kit is compatible with the following IBM Informix database servers: o IBM Informix Dynamic Server, Version 9.4 and later DBDK needs Client SDK 2.80 and later installed to work. Client SDK is no longer bundled in DBDK, and need to be installed prior to installing DBDK. III. SOFTWARE COMPATIBILITY ============================ This version of the DataBlade Developers Kit requires the Windows 2000 and later operating system. You can use Microsoft Visual C++ Version 6.0 to edit and compile code generated with this version of the DataBlade Developers Kit. You can use InstallShield 3.1 or InstallShield 5.1 and 5.5 with DBDK BladePack to create interactive installation packages for the DataBlade modules you develop. IV. CLIENT OPERATING SYSTEM COMPATIBILITY ========================================== DataBlade Developers Kit Version 4.0 client code has been tested on Windows 2000. V. ADDITIONAL FEATURES ======================= This version of the DataBlade Developers Kit contains the following features in addition to the description in the user guide and the documentation notes: * New merging functionality * Migrating to the new format * InstallShield 5.5 support A. New merging functionality ----------------------------------------- The merging functionality has changed, and now works as originally intended. Everything inside a block that has a merge instruction set to be a PreserveSection will be maintained. There is one restriction, the code section must exist in the generated code. The merging mechanism first generates an internal file of the newly generated code, then indexes the old file, and finally iterates through the new file searching for blocks to keep. The combination of the old and the new file is then pushed out as a new file. During the process, two new blocks are introduced in the code: o COMMENT_BLOCK o ADDITIONAL_CODE COMMENT_BLOCK identifies a comment for a function or a file header that will be preserved when code is generated. ADDITIONAL_CODE is a block in which you can enter code that is not generated by BladeSmith, but that you want to use in the routines of the project. (This block has been added since the majority of projects will have internal routines and structures that are not generated by BladeSmith.) B. Migrating to the new format: -------------------------------------------- All blocks in the code have an ID in order to distinguish them and to enable them to be handled as unique objects. This means that blocks that used to look like this: /* --- Your_Declarations (PreserveSection) --- */ And /* --- Your_Code (PreserveSection) --- */ Now look like this: /* --- Your_Declarations(FUNCTIONNAME)(PreserveSection) --- */ And /* --- Your_Code(FUNCTIONNAME)(PreserveSection) --- */ The combination of the SECTIONNAME Your_Code with the function name provides the unique key that the merging functionality requires. Although significant measures have been taken to ensure that all code is converted correctly, you are encouraged to perform a thorough check of the code after merging an old project for the first time. **** WARNING **** Code outside blocks will be removed from the .c file. The fact that prior releases at times did not remove code that was written outside of the code blocks should be considered a bug. The purpose of code blocks is to enable regeneration of code without the concern of overwriting user code. If a section in another file than udr.c but that have been generated by BladeSmith need to be modified, please switch Merge instruction from: MergeSection to PreserveSection. This can be done prior to migrating to ensure that changes in for instance UDT's are not overwritten. ********************** To alleviate the transition to the new, correct behavior, DBDK provides the two additional blocks ADDITIONAL_CODE, and COMMENT_BLOCK described in section A, above. They provide additional places to put code and comments that you may want to maintain. There is also an area in the header file where additions can be made. The backup procedure has also been improved so that it no longer overwrites the old copy when re-generating code. Instead, DBDK creates a new directory with the name Save. Order number is the first free location number starting from zero. This ensures that you can always recover your old code, if necessary. C. InstallShield 5.5 support --------------------------------------- You can now generate installation programs for InstallShield 5.5, and later. The functionality is the same as that of InstallShield 5.1 and provides a framework for future customization by the DataBlade developer. The framework is generated as a 5.1 project; when you open the project in InstallShield 5.5 for the first time, you are prompted whether you want to convert to InstallShield 5.5. You can convert an InstallShield 5.5 installation to an InstallShield for Microsoft Windows Installer. For more information, see the InstallShield documentation for the InstallShield Windows Installer. VI. UPGRADE ISSUES =================== A. UPGRADING PROJECT FILES --------------------------- BladeSmith recognizes project files saved by previous versions. When you first open an old project file, BladeSmith converts all of the objects contained in the project. If there are problems converting objects, BladeSmith describes them in a message box. The disk file is not changed until you save the project. Because Illustra and Informix server architectures are different, you might need to re-create some objects upgraded from the Illustra version of DBDK (2.1 or earlier). B. UPGRADING DATABLADE MODULES CREATED WITH EARLIER VERSIONS ------------------------------------------------------------- This section contains important upgrading information about the following topics: o Merging source code generated with BladeSmith Version 3.5 and earlier o Upgrading DataBlade modules with BladeManager o Upgrading DataBlade modules created with BladeSmith 3.2 and earlier 1. Merging Code Generated with BladeSmith 3.5 .............................................. Because BladeSmith Version 4.0 creates more than one source code file when it generates code, you cannot automatically merge changes that you made to code generated by Version 3.5 and earlier into source code files generated with BladeSmith Version 4.0. To upgrade, you must regenerate Version 3.5 source code files. When you upgrade to Version 4.0, BladeSmith merges user-changed routines from Version 3.5 or earlier into Version 4.0 routines. Version 3.5 routines that have not been modified by you are ignored; Version 4.0 generated routines are used. Any routine that you modified is copied from the old .c file and placed in the appropriate source code file. For opaque types, the old support routines are placed in the .c file; all other routines are placed in the udr.c file. Only BladeSmith-generated routines are merged into the new structure. No other files are examined. If you made changes to the makefile or added other source code files, you need to manually copy them to the src/C directory. To upgrade BladeSmith Version 3.5 and earlier source code to BladeSmith Version 4.0 source code, complete these steps: 1. Open the DataBlade module project file in BladeSmith Version 4.0. 2. Choose Generate->Generate DataBlade to display the Generate DataBlade dialog box. 3. Select the Source node in the file tree. 4. Make sure the Merge property is set to True. If Merge is set to False, new source code files are generated; the old source code is not upgraded. A message box confirms that you are merging a 3.5 project into a 4.0 project. 5. Click Generate Source to generate source files. Your new source code files are in the src\C directory. 6. Delete your old source code files. The next section describes how BladeManager 4.0 upgrades DataBlade modules created with earlier versions of DBDK. 2. Upgrading with BladeManager ............................... DataBlade Developers Kit Versions 3.3 through 4.0 support automatic upgrades for registered DataBlade modules. In DataBlade Developers Kit 3.2 or earlier, it was necessary to first unregister an older version of a DataBlade module before a new version could be registered. Before a DataBlade module can be unregistered, all instances of opaque types provided by the DataBlade module must be dropped from the database. Therefore, prior to Version 3.3, upgrading a DataBlade module required unloading data and dropping tables and then, after registering the new DataBlade module version, re-creating tables and reloading data. BladeManager Version 4.0 can upgrade DataBlade modules "in place," as long as the following three conditions are true: o There are no changes to the internal structure of opaque types used in the database. o The SQL scripts for the new version of the DataBlade module were created with BladeSmith Version 3.3 or later. o The SQL scripts for the old version of the DataBlade module were created with BladeSmith Version 3.3 or later, or you provide an upgrade script for the earlier version. If any of these conditions is not true, the earlier DataBlade module version must be unregistered before the new version is registered. 3. Upgrading from Versions Before DBDK 3.3 ........................................... If you are upgrading a DataBlade module created using a pre-3.3 version of the DataBlade Developers Kit, it is best to include an upgrade script for the older version. To create an upgrade script for a previous version of a DataBlade module, complete these steps: 1. With BladeSmith Version 4.0, open the project file for the earlier version of the DataBlade module. 2. Choose Generate->Generate DataBlade to display the Generate DataBlade dialog box. 3. Click the SQL folder in the file tree. 4. Click Generate SQL. 5. Save the project file and exit BladeSmith. 6. Rename the objects.sql file to upgrade..sql, where is the release number of the earlier version of the DataBlade module. 7. Copy this "upgrade" script to the scripts subdirectory in the project directory of the new version of the DataBlade module. 8. Create a file called prepare..sql that contains the following SQL INSERT command: insert into sysbldscripts (bld_id, blocale_id, bscr_type, bscr_sequence, bscr_sql_script, bscr_old_bld) values ( "%SYSBLDNAME%", "any", 3, 1, "upgrade..sql", "" ); Replace with the name of the previous DataBlade module release. 9. Use BladePack to add the upgrade script and the prepare script to the installation package for the new version of the DataBlade module. When BladeManager starts, it automatically executes the prepare script, which identifies the upgrade script. The new upgrade script adds descriptions of objects in the earlier version of the DataBlade module to the system tables. This information allows BladeManager to upgrade the DataBlade module. VII. CONVERSION AND REVERSION ISSUES ===================================== If you create an object in a Version 9.2 database server, you cannot revert to Version 9.14. To facilitate conversion to and reversion from Version 9.2 of the database server, Version 3.7 and later of the DataBlade Developers Kit uses the ALTER FUNCTION or ALTER ROUTINE SQL keywords to change most properties of user-defined routines. Earlier versions of the DataBlade Developers Kit drop and re-create user-defined routines that change. Therefore, if you install a DataBlade module created with a pre-3.7 version of the DataBlade Developers Kit on a Version 9.2 database server and then make changes to that DataBlade module, you cannot revert to a Version 9.14 database server. You can change almost all properties of a user-defined routine and still allow reversion from Version 9.2 to Version 9.14, except for the following routine properties: o Arguments o Return type o Language IMPORTANT: It is recommended that you regenerate your DataBlade modules in Version 4.0 of the DataBlade Developers Kit before you convert to Version 9.2 of the database server. If you created your DataBlade module with a version of the DataBlade Developers Kit earlier than Version 3.6, you must first upgrade the module to Version 3.6. See Section VI, "Upgrade Issues," for instructions. To upgrade a Version 3.6 DataBlade module that is not installed on a database server: 1. Open the .ibs file in BladeSmith. 2. Regenerate the SQL. To upgrade a Version 3.6 DataBlade module while it is installed on a Version 9.14 database server: 1. Open the .ibs file in BladeSmith. 2. Regenerate the SQL. 3. Register the new version of the DataBlade module on the Version 9.14 database server. You can then convert from Version 9.14 to 9.2. VIII. EXAMPLE FILES ==================== This product includes example DataBlade modules. Each example includes a BladeSmith project file and files generated by BladeSmith. The source code has been modified to complete the functionality of the DataBlade module. See the DataBlade Developers Kit InfoShelf for information about the example DataBlade modules. NOTE: If you install a compiled example DataBlade module by manually copying the .bld file into the database server, check that it is marked as read-only. If you use BladePack to install an example DataBlade module, the .bld file is automatically set as read-only. IX. KNOWN PROBLEMS =================== This section describes the known problems with this release of the DataBlade Developers Kit and shows how to work around some of these problems. X. FIXED PROBLEMS ------------------ 165727: BLADESMITH: TESTING PRIVATE STATE INFORMATION IS NOT PLACED IN THE PRESERVE SECTION 165726: BLADESMITH GENERATE FUNCTION CALL OF MI_FP_SETFUNCSTATE WHOSE 2ND ARGUMENT WITHOUT CASTING TO (VOID*), WHICH RECOMMENDED BY THE MANUAL. 166151: BLADESMITH GENERATE ITERATOR FUNCTION THAT ALWAYS EVALUATE 0 FROM RETURN TYPE TO NULL, NO MATTER WHETHER THE RETUEN VALUE IS 0 OR NULL, AND ALSO PLACED IN THE PRESERVE SECTION THAT RESULT IN FURTHER MANUAL CORRECTION LOST WHEN REGENERATE THE CODE. 165200: BLADESMITH CAN NOT GENERATE ITERATION ROUTINE WHICH RETURNS DISTINCT TYPE WITH A QUALIFIED TYPE AS A SOURCE 163690: 4.00.TC5 BUNDLE: CUSTOM INSTALL OF BLADE MANAGER DOESN'T INSTALL ICMNT04B.DLL AND ICMNTRES04B.DLL Fixes introduced in DBDK 4.00.TC4 & 4.00.TC5: 159838: DBLD/DBDK/DATA.TAG IN THE UNIX INSTALL BUNDLES SPECIFIES A VERSION OF 1.00.000 AND A COMPANY OF "INFORMIX SOFTWARE INC" 113032: BLADESMITH 4.0 ROUTINE WIZARD DOES NOT ALLOW YOU TO HAVE MULTIPLE UDRS SHARE A COMMON C ENTRYPOINT. 113034: BLADESMITH GENERATES DUPLICATE CODE FOR SHARED C ENTRYPOINTS 158308: C++ SINGLE LINE COMMENTS (//) NOT UNDERSTOOD BY VARIOUS UNIX COMPILERS. THESE COMMENTS APPEAR IN THE 'ADDITIONAL CODE' {PRESERVESECTION] OF BOTH 158342: WHEN UPDATING A ROUTINE OBJECT THROUGH THE PROPERTY PAGES, THE BLADE PATH CAN BE SET TO DEFAULT SETTINGS IN THE ACTUAL CROUTINE OBJECT 158307: *.BLD FILES AND OBJECTS.SQL CORRUPTED AFTER BUILDING INSTALLATION ON UNIX PLATFORMS. NT IS FINE. Fixes introduced in DBDK.4.00.TC3: 108805 and 109940 The output HTML file no longer displays only the executable SQL statements; it displays the complete SQL file with comments. 108047 BladePack no longer reports "CANNOT SAVE F:\BLADE\WEB\SRC\DBDK\WEB.PRD" when in fact it is WEB.STR that has permissions problems. 108370 and 155009 Icons are now correctly placed if you specify a folder other than Informix and the command executed by the icon succeeds. 111386 For IfxQuery, the number of connection attempts and length of timeout are no longer hardcoded. 130062 The merge error no longer occurs when generating the fuzzy-match example. 134704 The Back button now always brings up the previous window. 111848 The Finish button is now enabled on the New Row Type wizard. 119862 IfxQuery now displays the SQL statement being run. 119984 Code merges now correctly handle comment blocks. 112078 Removing the definition of an opaque type no longer changes the return type of a routine that uses that opaque type. 113032 BLADESMITH 4.0 ROUTINE WIZARD DOES NOT ALLOW YOU TO HAVE MULTIPLE UDRS SHARE A COMMON C ENTRYPOINT. 113034 BLADESMITH GENERATES DUPLICATE CODE FOR SHARED C ENTRYPOINTS 114238 The Statistics Support checkbox value now takes effect when set inside the Property sheet. 114281 BladeSmith now enters all necessary dependencies for objects in the project. 117047 While calculating the internal length of an opaque type, an MI_UNSIGNED_INTEGER component is allocated 12 bytes instead of 4. 118286 The support functions of user-defined aggregates now include the parallelizable modifier in the SQL scripts. 119538 Now, when you change the name or parameters of a routine and regenerate code, the new name is reflected in the new code. 122186 Memory alignment values can now be set by the user. 126025 BladeSmith now supports the CANNOTHASH opaque type modifier. 127923 Object dependencies are now correctly generated. 133979 You can now specify a function that is its own commutator. 154511 and 154838 Pressing Cancel in the first dialog box during installation now correctly causes you to exit. 155531 Code is now removed in the UDR file when you remove a C or Java routine from a BladeSmith project and regenerate code with MERGING = TRUE. 155533 Now when you delete routines from a BladeSmith project and regenerate code with MERGING = TRUE, old, customized code can be retained. 155796 The DBDK installation program now installs the new version of BladeManager. 155862 Now when you copy routines between projects, test data gathered for the routine is also copied. 156081 CodeGen no longer reports the error SYNTAX ERROR IN MAKE_PROJECT6.TPL when generating code for C++ projects. 156330 The CodeGen keyword DECLARE now successfully creates and populates a template list. 156496 If you are using the Client SDK, Version 2.70, BladeSmith can now successfully retrieve the environment variables required for code generation. 155797 The DBDK Add-In now correctly reports when a server is remote. 155799 If the Microsoft MSDEV tools key is set under HKEY_LOCAL_MACHINE instead of HKEY_CURRENT_USER, CREATEADMIN.EXE no longer fails to create MSDEV keys. 156893 COPYING USER DEFINED OBJECTS FROM ONE PROJECT TO ANOTHER CRASHED BLADESMITH 156894 TRYING TO SAVE A PROJECT AFTER OVERWRITING A TARGET WHILE COPYING A USER DEFINED OBJECT FROM ONE PROJECT TO ANOTHER CAUSES A CRASH. 156895 CHANGING THE NAME OF AN ARGUMENT IN THE PROPERTIES BOX INSERTS TWO ARGUMENTS WITH THE NAME CHANGE. TRYING TO SAVE THE PROJECT CRASHES. 156896 CRASHES WHEN SAVING AFTER REPEATEDLY OVERWRITING THE TARGET WHILE COPYING A USER DEFINED OBJECT FROM ONE PROJECT TO ANOTHER 156897 INFORMIXDIR NOT RETRIEVED WHILE ATTEMPTING TO DEBUG A DATABLADE MODULE IN THE ADD-IN. 156916 SWITCHING DATABASE IN DBDKADDIN AND PRESSING REGISTER BLADE AFTER THAT COULD CAUSE BLADEMANAGER TO REPORT A BUNCH OF -1227 AND CRASH MSDEV